Files
napalm-proxmox/napalm_proxmox/system_mixin.py
T
Christian Manivong 0b5f82cc02 refactor: share connection and Debian host code for a second product (#52)
Proxmox Backup Server speaks the same REST dialect, logs in the same way
and runs on Debian too, so what a second driver needs moves out of
ProxmoxDriver first:

- napalm_proxmox._base: the connection (proxmoxer service PVE or PBS,
  each with its port), the token split, the SSH session, run_command,
  the node helpers and the DMI read.
- napalm_proxmox.host_mixin: packages and APT updates, the subscription,
  restart and shutdown through the API, root file writes and the
  transports of the host readers (kernel, listening sockets, identity,
  systemd, host status, apt's proxy).

The PVE driver behaves as before; what it hands proxmoxer is pinned by
tests first, and it now names service="PVE" explicitly. get_packages is
split so the dpkg line parser stands alone; get_facts and get_packages
leave the quality baseline.
2026-11-02 22:29:04 +01:00

648 lines
27 KiB
Python

# Copyright 2025 The NetOrk Project Authors. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""System-level NAPALM getters for Proxmox VE nodes.
Environment, NTP, SNMP, users, hostname and disk SMART. What a PVE node shares
with a Proxmox Backup Server as a Debian host is in ``host_mixin``.
"""
from __future__ import annotations
import ipaddress
import logging
import re
from typing import Any
from napalm.base.exceptions import CommandErrorException
from napalm_proxmox.ntp import NTP_STATS_COMMAND, parse_ntp_stats
logger = logging.getLogger(__name__)
_JsonDict = dict[str, Any]
#: What may stand in an snmpd.conf value: no whitespace, no quote, no comment.
_SNMP_WORD = re.compile(r'^[^\s"#]+$')
#: The net-snmp agent's configuration file.
_SNMPD_CONF = "/etc/snmp/snmpd.conf"
#: Exit status 0 when the node is a cluster member. pvecm itself decides
#: membership by /etc/pve/corosync.conf; /etc/corosync/corosync.conf is the
#: local copy every member keeps, there even when /etc/pve is not mounted.
#: Not ``pvecm status``: it also fails on a member whose corosync is down.
_CLUSTER_MEMBER_CHECK = "[ -e /etc/pve/corosync.conf ] || [ -e /etc/corosync/corosync.conf ]"
def _rename_in_hosts(hosts: str, old_short: str, new_short: str, new_domain: str | None) -> str:
"""*hosts* (an /etc/hosts) with the node's names renamed from *old_short*.
Only whole names change: ``old_short`` becomes ``new_short``, and
``old_short.<domain>`` becomes ``new_short.<new_domain>`` (the old domain
kept when *new_domain* is None). Other names that merely start with the
old name (``pve-backup``) and comments stay as they are.
"""
def rename(match: re.Match[str]) -> str:
name = match.group(0)
if name == old_short:
return new_short
if name.startswith(f"{old_short}."):
return f"{new_short}.{new_domain or name[len(old_short) + 1 :]}"
return name
lines = []
for line in hosts.splitlines(keepends=True):
entry, hash_, comment = line.partition("#")
lines.append(re.sub(r"\S+", rename, entry) + hash_ + comment)
return "".join(lines)
#: Proxmox's superuser, whatever the ACL says.
_PVE_SUPERUSER = "root@pam"
#: The role that makes a Proxmox user an administrator of the node.
_PVE_ADMIN_ROLE = "Administrator"
#: Regular login accounts: Debian gives them uids from 1000 up; 65534 is nobody.
_FIRST_REGULAR_UID = 1000
_NOBODY_UID = 65534
def _words(value: Any, sep: str | None = None) -> list[str]:
return [w.strip() for w in str(value or "").split(sep) if w.strip()]
def _user_entry(level: int) -> _JsonDict:
# NAPALM's get_users shape; the password is never read.
return {"level": level, "password": "", "sshkeys": []} # nosec B105
def _login_accounts(passwd: str) -> list[tuple[str, int]]:
"""``(name, uid)`` of root and every regular account in *passwd*."""
accounts = []
for line in passwd.splitlines():
parts = line.split(":")
if len(parts) < 7:
continue
try:
uid = int(parts[2])
except ValueError:
continue
if uid == 0 or _FIRST_REGULAR_UID <= uid < _NOBODY_UID:
accounts.append((parts[0], uid))
return accounts
def _net(value: str) -> str:
return str(ipaddress.ip_network(value.strip(), strict=False))
def render_snmpd_conf(settings: dict) -> str:
"""net-snmp's configuration for *settings*: read-only v2c, per allowed source."""
community = settings["community"]
if not _SNMP_WORD.match(community):
raise ValueError("the community must be one word without quotes or #")
listen = settings.get("listen")
lines = [f"agentAddress udp:{listen + ':' if listen else ''}161"]
sources = [_net(s) for s in settings.get("allowed_sources", [])]
lines += [f"rocommunity {community} {s}" for s in sources] or [f"rocommunity {community}"]
for key, directive in (("location", "sysLocation"), ("contact", "sysContact")):
value = settings.get(key, "")
if value:
if "\n" in value:
raise ValueError(f"{key} must be one line")
lines.append(f"{directive} {value}")
return "\n".join(lines) + "\n"
class ProxmoxSystemMixin:
"""Mixin providing system-level NAPALM methods."""
# ------------------------------------------------------------------ #
# get_environment
# ------------------------------------------------------------------ #
def get_environment(self) -> _JsonDict:
"""Return environment status (CPU, memory, temperature)."""
status = self._get_node_status()
env: _JsonDict = {
"fans": {},
"temperature": {},
"power": {},
"cpu": {},
"memory": {"available_ram": 0, "used_ram": 0},
}
# CPU
cpu_usage = status.get("cpu", 0.0)
env["cpu"]["0"] = {"%usage": round(float(cpu_usage) * 100, 2)}
# Memory (Proxmox reports in bytes)
mem = status.get("memory", {})
total = int(mem.get("total", 0) or 0)
used = int(mem.get("used", 0) or 0)
env["memory"]["available_ram"] = total
env["memory"]["used_ram"] = used
# Temperature (from node sensors if available)
try:
sensors = self._node_api().hardware.sensors.get() or []
except Exception as exc:
logger.debug("Failed to fetch hardware sensors: %s", exc)
sensors = []
for sensor in sensors:
name = sensor.get("name", "unknown")
value = sensor.get("value", None)
if value is not None:
try:
temp_c = float(value)
env["temperature"][name] = {
"temperature": temp_c,
"is_alert": temp_c >= 80.0,
"is_critical": temp_c >= 95.0,
}
except (TypeError, ValueError):
pass
return env
# ------------------------------------------------------------------ #
# get_ntp_servers / get_ntp_stats
# ------------------------------------------------------------------ #
def get_ntp_servers(self) -> dict[str, _JsonDict]:
"""Return configured NTP servers."""
ntp = self._get_node_ntp()
servers: dict[str, _JsonDict] = {}
# Proxmox reports a comma-separated or space-separated server list
raw = ntp.get("server", "") or ntp.get("servers", "")
for srv in re.split(r"[\s,]+", raw):
srv = srv.strip()
if srv:
servers[srv] = {}
return servers
def get_ntp_stats(self) -> list[_JsonDict]:
"""Return NTP synchronisation statistics from chrony, or ntpd where chrony is missing."""
return parse_ntp_stats(self._exec_ssh_command(NTP_STATS_COMMAND))
# ------------------------------------------------------------------ #
# get_snmp_information
# ------------------------------------------------------------------ #
def get_snmp_information(self) -> _JsonDict:
"""Return SNMP information.
Proxmox does not expose SNMP configuration via the REST API.
We read /etc/snmp/snmpd.conf via exec if available.
"""
raw = self._exec_ssh_command("cat /etc/snmp/snmpd.conf 2>/dev/null || true")
communities: dict[str, _JsonDict] = {}
location = ""
contact = ""
for line in raw.splitlines():
line = line.strip()
if line.startswith("#") or not line:
continue
# rocommunity <community> [source]
m = re.match(r"^(ro|rw)community\s+(\S+)", line)
if m:
mode = "ro" if m.group(1) == "ro" else "rw"
community = m.group(2)
communities[community] = {"acl": "N/A", "mode": mode}
m_loc = re.match(r"^sysLocation\s+(.+)", line)
if m_loc:
location = m_loc.group(1).strip()
m_con = re.match(r"^sysContact\s+(.+)", line)
if m_con:
contact = m_con.group(1).strip()
return {
"chassis_id": self._node_name,
"community": communities,
"contact": contact,
"location": location,
}
# ------------------------------------------------------------------ #
# get_users
# ------------------------------------------------------------------ #
def get_users(self) -> dict[str, _JsonDict]:
"""Return users configured on the Proxmox node.
Proxmox's own users (``/access/users``) at level 15 when they hold the
Administrator role on the whole datacenter (``/``), directly or through
a group, 1 otherwise; ``root@pam`` is always 15. Then the node's login
accounts from the passwd database: root (15) and regular users
(uid 1000 and up, without ``nobody``) at 0; system accounts are left out.
"""
result: dict[str, _JsonDict] = {}
admins, admin_groups = self._pve_administrators()
for user in self._pve_users():
uid = user.get("userid", "")
if not uid:
continue
groups = set(_words(user.get("groups"), sep=","))
is_admin = uid == _PVE_SUPERUSER or uid in admins or bool(groups & admin_groups)
result[uid] = _user_entry(15 if is_admin else 1)
raw = self._exec_ssh_command("getent passwd 2>/dev/null || cat /etc/passwd")
for uname, uid_int in _login_accounts(raw):
result.setdefault(uname, _user_entry(15 if uid_int == 0 else 0))
return result
def _pve_users(self) -> list[_JsonDict]:
try:
return self._api.access.users.get() or [] # type: ignore[union-attr]
except Exception as exc:
logger.debug("Failed to fetch Proxmox users: %s", exc)
return []
def _pve_administrators(self) -> tuple[set[str], set[str]]:
"""Users and groups holding the Administrator role on ``/`` (``/access/acl``)."""
try:
acl = self._api.access.acl.get() or [] # type: ignore[union-attr]
except Exception as exc:
logger.debug("Failed to fetch the Proxmox ACL: %s", exc)
acl = []
users: set[str] = set()
groups: set[str] = set()
for entry in acl:
if entry.get("path") != "/" or entry.get("roleid") != _PVE_ADMIN_ROLE:
continue
if entry.get("type") == "user":
users.add(entry.get("ugid", ""))
elif entry.get("type") == "group":
groups.add(entry.get("ugid", ""))
return users, groups
# ------------------------------------------------------------------ #
# Kernel facts (KernelFactsMixin supplies get_kernel_facts)
# ------------------------------------------------------------------ #
# ------------------------------------------------------------------ #
# Listening sockets (ListeningSocketsMixin supplies get_listening_sockets)
# ------------------------------------------------------------------ #
# ------------------------------------------------------------------ #
# Packages (Debian APT)
# ------------------------------------------------------------------ #
# ------------------------------------------------------------------ #
# Licenses (napalm-device-types' LicenseMixin)
# ------------------------------------------------------------------ #
# ------------------------------------------------------------------ #
# Services (systemd, through napalm-device-types' SystemdServicesMixin)
# ------------------------------------------------------------------ #
# ------------------------------------------------------------------ #
# Available updates
# ------------------------------------------------------------------ #
# ------------------------------------------------------------------ #
# SNMP / Health
# ------------------------------------------------------------------ #
def get_snmp_config(self):
"""Return SNMP agent config if snmpd is installed and running on the node.
Uses _exec_ssh_command (the node's SSH session) to inspect the node;
raises when the node cannot be reached there.
Returns a SNMPConfigDict or None.
"""
try:
from napalm_device_types.models import SNMPConfigDict
except ImportError:
return None
running = (
self._exec_ssh_command("systemctl is-active snmpd 2>/dev/null || true").strip()
== "active"
)
if not running:
return None
community = "public"
port = 161
try:
conf = self._exec_ssh_command(
"grep -E '^[[:space:]]*(ro|rw)?community' /etc/snmp/snmpd.conf "
"2>/dev/null | head -5"
)
for line in conf.splitlines():
parts = line.split()
if not parts:
continue
kw = parts[0].lower()
if kw in ("rocommunity", "rwcommunity") and len(parts) >= 2:
community = parts[1]
break
elif kw == "com2sec" and len(parts) >= 4:
community = parts[3]
break
except Exception as exc:
logger.debug("Failed to parse snmpd.conf: %s", exc)
return SNMPConfigDict(running=True, community=community, port=port, version="2c")
# ------------------------------------------------------------------
# Fixes (napalm-device-types SnmpAgentMixin, EnsurePackageMixin): the
# caller's values. The node's shell runs as root.
# ------------------------------------------------------------------
# apt's proxy (napalm-device-types AptProxyMixin): the transports. The node
# is logged in as root, so every command runs as root.
def _install_snmp_agent(self) -> dict:
return self._step(
"DEBIAN_FRONTEND=noninteractive apt-get install -y snmpd snmp", "net-snmp installed"
)
def _write_snmp_agent_config(self, settings: dict) -> dict:
return self._write_root_file(_SNMPD_CONF, render_snmpd_conf(settings))
def _allow_snmp_sources(self, settings: dict) -> dict:
sources = [_net(s) for s in settings.get("allowed_sources", [])]
if not sources:
return {"ok": True, "output": "no sources given; firewall unchanged"}
if self._rc("command -v ufw")[1] != 0:
return {"ok": True, "output": "no ufw; pve-firewall rules are the operator's"}
rules = " && ".join(f"ufw allow from {s} to any port 161 proto udp" for s in sources)
return self._step(rules, f"udp/161 open for {', '.join(sources)}")
def _start_snmp_agent(self) -> dict:
return self._step(
"systemctl enable snmpd && systemctl restart snmpd && systemctl is-active snmpd",
"snmpd enabled and running",
)
def _refuse_clustered_node(self) -> None:
_, status = self._rc(_CLUSTER_MEMBER_CHECK)
if status == 0:
raise CommandErrorException(
"set_hostname refused: the node is part of a cluster; rename a cluster"
" member by Proxmox's own procedure, not in place"
)
if status != 1:
raise CommandErrorException(
"set_hostname refused: could not tell whether the node is part of a cluster"
)
def set_hostname(self, new_hostname: str) -> None:
"""Set the system hostname on the Proxmox node.
Performs all steps required for a clean rename on a Debian/Proxmox host:
1. ``/etc/hostname`` — short hostname only.
2. ``/etc/hosts`` — old hostname replaced by new (short or FQDN).
3. ``/etc/mailname`` — FQDN, if the file exists.
4. Postfix ``myhostname`` — updated via ``postconf -e`` if Postfix is
installed.
5. Runtime hostname — applied immediately via ``hostname(1)`` so SSH
and the Proxmox API see the new name without a reboot.
6. ``/etc/pve/nodes/<old>`` → ``/etc/pve/nodes/<new>`` rename so
VM/CT configs are found after the reboot under the new node name.
7. Proxmox node TLS certificate — regenerated via
``pvenode cert create --overwrite``.
The Proxmox *node name* (web UI, ``/etc/pve/nodes/<name>/``) only
changes after a reboot. Accepts a bare hostname or an FQDN.
Raises CommandErrorException, before changing anything, on a cluster
member (a corosync.conf exists): its rename is the cluster's procedure.
"""
import base64 as _b64
self._refuse_clustered_node()
if "." in new_hostname:
short_hostname, domain = new_hostname.split(".", 1)
fqdn = new_hostname
else:
short_hostname = new_hostname
domain = None
fqdn = new_hostname
# Derive old short hostname for substitution in /etc/hosts
old_short = (
self._exec_ssh_command("cat /etc/hostname 2>/dev/null || hostname -s 2>/dev/null")
.strip()
.split(".")[0]
)
# ── 1. /etc/hostname ─────────────────────────────────────────────
hostname_b64 = _b64.b64encode(f"{short_hostname}\n".encode()).decode()
self._exec_ssh_command(f"echo {hostname_b64} | base64 -d > /etc/hostname")
# ── 2. /etc/hosts ────────────────────────────────────────────────
# Read the file, substitute in Python (safe for all characters),
# write back via base64 to avoid shell-escaping issues.
if old_short and old_short != short_hostname:
hosts_raw = self._exec_ssh_command("cat /etc/hosts 2>/dev/null")
hosts_new = _rename_in_hosts(hosts_raw, old_short, short_hostname, domain)
hosts_b64 = _b64.b64encode(hosts_new.encode()).decode()
self._exec_ssh_command(
f"echo {hosts_b64} | base64 -d > /tmp/_netork_hosts"
f" && mv /tmp/_netork_hosts /etc/hosts"
f" && chmod 644 /etc/hosts"
)
# ── 3. /etc/mailname ─────────────────────────────────────────────
mailname_b64 = _b64.b64encode(f"{fqdn}\n".encode()).decode()
self._exec_ssh_command(
f"[ -f /etc/mailname ] && echo {mailname_b64} | base64 -d > /etc/mailname || true"
)
# ── 4. Postfix myhostname ─────────────────────────────────────────
self._exec_ssh_command(
f"command -v postconf >/dev/null 2>&1 && postconf -e 'myhostname = {fqdn}' || true"
)
# ── 5. Apply hostname at runtime ─────────────────────────────────
self._exec_ssh_command(f"hostname '{short_hostname}'")
# ── 6. Migrate /etc/pve/nodes/<old> → /etc/pve/nodes/<new> ──────
# Proxmox stores VM and CT configs under /etc/pve/nodes/<nodename>/.
# This rename MUST happen before the reboot while pve-cluster is
# running and pmxcfs is mounted — pmxcfs supports the rename live.
# Without this step the node boots under the new hostname, finds an
# empty /etc/pve/nodes/<new>/ and all VMs appear missing.
if old_short and old_short != short_hostname:
pve_old = f"/etc/pve/nodes/{old_short}"
pve_new = f"/etc/pve/nodes/{short_hostname}"
migrate_out = self._exec_ssh_command(
f"if [ -d '{pve_old}' ] && [ ! -e '{pve_new}' ]; then"
f" mv '{pve_old}' '{pve_new}'"
f" && echo 'migrated {pve_old} -> {pve_new}';"
f"elif [ -d '{pve_new}' ]; then"
f" echo 'target already exists, skipping migration';"
f"else"
f" echo 'source {pve_old} not found, skipping migration';"
f"fi"
)
logger.info("Proxmox node dir migration: %s", migrate_out)
# ── 7. Regenerate Proxmox node TLS certificate ───────────────────
# Use pvenode cert create --overwrite rather than pvecm updatecerts -f.
# pvecm updatecerts -f restarts pve-cluster which briefly unmounts the
# cluster filesystem (/etc/pve) and can crash running VMs.
# pvenode cert create --overwrite only touches the node's own cert and
# restarts pveproxy (safe while VMs are running).
cert_out = self._exec_ssh_command(
"pvenode cert create --overwrite 1 2>&1"
" || { systemctl restart pveproxy 2>&1; echo 'restarted pveproxy'; }"
" || true"
)
logger.info("Proxmox cert regeneration: %s", cert_out[:200])
logger.info(
"Proxmox set_hostname: %s → %s (fqdn: %s). "
"Reboot required for node name to update in web UI / cluster.",
old_short,
short_hostname,
fqdn,
)
# ------------------------------------------------------------------ #
# _send_command — generic SSH command helper used by netOrk core
# ------------------------------------------------------------------ #
def _send_command(self, command: str) -> str:
"""Execute *command* on the node and return its output.
Delegates to _exec_ssh_command so that netOrk's generic helpers
(e.g. the reboot action) work without knowing the driver internals.
"""
return self._exec_ssh_command(command)
def get_disk_smart(self) -> dict:
"""Return SMART health data for all disks on this Proxmox node.
Combines the disk list (model, size, wearout) with per-disk SMART
data (health, temperature, percentage used).
Returns a dict keyed by device path, e.g. {"/dev/nvme0n1": {...}}.
"""
import re as _re
result: dict = {}
try:
disks = self._node_api().disks.list.get() or []
except Exception as exc:
logger.debug("Failed to list disks: %s", exc)
return result
for disk in disks:
dev = disk.get("devpath") or disk.get("dev")
if not dev:
continue
entry: dict = {
"model": disk.get("model", ""),
"serial": disk.get("serial", ""),
"type": disk.get("type", ""),
"size": disk.get("size", 0),
"health": disk.get("health", "unknown").lower(),
"wearout": disk.get("wearout"), # NVMe wear indicator 0-100
"temperature": None,
"percentage_used": None,
"available_spare": None,
"reallocated_sectors": None,
"power_on_hours": None,
}
try:
smart = self._node_api().disks.smart.get(disk=dev) or {}
# health from SMART endpoint may be more accurate
if smart.get("health"):
entry["health"] = smart["health"].lower()
text = smart.get("text", "")
# Parse temperature
m = _re.search(r"Temperature[^:]*:\s*(\d+)\s*Celsius", text)
if m:
entry["temperature"] = int(m.group(1))
# NVMe-specific
m = _re.search(r"Percentage Used:\s*(\d+)%", text)
if m:
entry["percentage_used"] = int(m.group(1))
m = _re.search(r"Available Spare:\s*(\d+)%", text)
if m:
entry["available_spare"] = int(m.group(1))
m = _re.search(r"Power On Hours:\s*([\d,]+)", text)
if m:
entry["power_on_hours"] = int(m.group(1).replace(",", ""))
# HDD-specific SMART attributes
for attr in smart.get("attributes", []):
name = attr.get("name", "").lower()
raw = attr.get("raw", "")
try:
raw_int = int(str(raw).split()[0])
except (ValueError, TypeError):
raw_int = None
if "temperature" in name and raw_int is not None:
entry["temperature"] = raw_int
elif "reallocated" in name and "sector" in name and raw_int is not None:
entry["reallocated_sectors"] = raw_int
elif "power_on" in name and raw_int is not None:
entry["power_on_hours"] = raw_int
except Exception as exc:
logger.debug("Failed to fetch SMART data for %s: %s", dev, exc)
result[dev] = entry
return result
def get_system_config(self) -> dict[str, Any]:
"""Return system-level configuration for this Proxmox node.
Collected from ``/cluster/status`` and the node config API:
* ``cluster_name`` (str | None) — Proxmox cluster name; ``None`` when
the node is standalone (not part of a cluster).
* ``cluster_nodes`` (list[str]) — hostnames of all online cluster nodes.
* ``hostname`` (str) — this node's name as reported by the cluster.
* ``timezone`` (str | None) — e.g. ``"Europe/Berlin"``.
* ``ntp_servers`` (list[str]).
* ``ssh_port`` (int) — always 22 for Proxmox nodes.
* ``ssh_password_auth`` (bool) — ``False`` as a safe default.
"""
cfg: dict[str, Any] = {
"cluster_name": None,
"cluster_nodes": [],
"hostname": self._node_name,
"timezone": None,
"ntp_servers": [],
"ssh_port": 22,
# A flag, not a password.
"ssh_password_auth": False, # nosec B105
}
# Cluster name and node list from /cluster/status
try:
status = self._api.cluster.status.get() or []
for entry in status:
if entry.get("type") == "cluster":
cfg["cluster_name"] = entry.get("name")
elif entry.get("type") == "node" and entry.get("online"):
cfg["cluster_nodes"].append(entry.get("name", ""))
except Exception as exc:
logger.debug("Failed to fetch cluster status for system config: %s", exc)
# Timezone from node time API
try:
time_cfg = self._node_api().time.get() or {}
cfg["timezone"] = time_cfg.get("timezone") or None
except Exception as exc:
logger.debug("Failed to fetch node time config: %s", exc)
return cfg