Files
napalm-proxmox/napalm_proxmox/host_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

309 lines
13 KiB
Python

"""What a Proxmox VE node and a Proxmox Backup Server share as Debian hosts.
The transports for napalm-device-types' host readers (kernel facts, service
packages, system identity, listening sockets, systemd services, host status,
apt's proxy), packages and APT updates, the subscription, root file writes,
and restarting or shutting the host down. All of it is the same on both
products: the same ``/nodes/{node}/apt``, ``/subscription`` and ``/status``
endpoints, and root's shell over the driver's own SSH session.
"""
from __future__ import annotations
import base64
import ipaddress
import logging
import re
import shlex
from typing import TYPE_CHECKING, Any, cast
from napalm_device_types import APT_UPGRADABLE_COMMAND, parse_apt_upgradable
from napalm_device_types.models import (
FixStepOutcomeDict,
LicenseDict,
LicenseStatus,
PackageDict,
)
logger = logging.getLogger(__name__)
_JsonDict = dict[str, Any]
#: The subscription API's status (lower-cased) as a napalm-device-types
#: ``LicenseStatus``; "new" and "suspended" have none of their own.
_SUBSCRIPTION_STATUS: dict[str, LicenseStatus] = {
"notfound": "none",
"active": "active",
"invalid": "invalid",
"expired": "expired",
}
_PACKAGE_NAME = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_.+:~-]*$")
class ProxmoxHostMixin:
"""The Debian host under a Proxmox product."""
#: ``source`` of every package ``get_packages`` reports.
PACKAGE_SOURCE = "pve"
#: ``name`` of the subscription ``get_licenses`` reports.
SUBSCRIPTION_LICENSE = "pve-subscription"
_node_name: str
if TYPE_CHECKING: # pragma: no cover - the driver's (napalm_proxmox._base)
def _exec_ssh_command(self, command: str) -> str: ...
def _node_api(self) -> Any: ...
def _get_node_subscription(self) -> _JsonDict: ...
def _run_kernel_facts_command(self, command: str) -> str:
"""The transport for ``KernelFactsMixin.get_kernel_facts``: the exec path."""
return self._exec_ssh_command(command)
def _run_service_packages_command(self, command: str) -> str:
"""The transport for ``ServicePackagesMixin.get_service_packages``: the exec path."""
return str(self._exec_ssh_command(command))
def _run_system_identity_command(self, command: str, *, privileged: bool) -> str:
"""The transport for ``SystemIdentityMixin.get_system_identity``: the exec path,
which runs as root either way."""
return str(self._exec_ssh_command(command))
def _run_listening_sockets_command(self, command: str, *, privileged: bool) -> str:
"""The transport for ``ListeningSocketsMixin.get_listening_sockets``:
the exec path, which runs as root either way."""
return str(self._exec_ssh_command(command))
def get_packages(self) -> list[PackageDict]:
"""Return installed Debian packages with available-update info.
Installed list comes from ``dpkg-query`` via SSH (the Proxmox API
``/apt/installed`` endpoint is not implemented on PVE 8.x).
Available updates come from the Proxmox API ``/apt/update``.
"""
upgradable = self._upgradable_versions()
# Installed packages via SSH dpkg-query
raw = self._exec_ssh_command(
"dpkg-query -W -f="
"'${Package}\\t${Version}\\t${db:Status-Status}\\t${Installed-Size}"
"\\t${source:Package}\\t${source:Version}\\n'"
" 2>/dev/null"
)
result = []
for line in raw.splitlines():
pkg = parse_dpkg_line(line, self.PACKAGE_SOURCE)
if pkg is not None:
pkg["upgrade_version"] = upgradable.get(pkg["name"], "")
result.append(pkg)
# PackageDict has no source_package, source_version and upgrade_version
# yet (NAPALM/napalm-device-types#85); every reader of these
# packages relies on them, so they stay.
return cast(list[PackageDict], result)
def _upgradable_versions(self) -> dict[str, str]:
"""The candidate version of every upgradable package, from ``/apt/update``."""
upgradable: dict[str, str] = {}
try:
for upd in self._node_api().apt.update.get():
pkg = upd.get("Package", "")
if pkg:
upgradable[pkg] = upd.get("Version", "")
except Exception as exc:
logger.debug("Failed to fetch available APT updates: %s", exc)
return upgradable
def get_licenses(self) -> list[LicenseDict]:
"""The node's subscription, as the API reports it.
A fact for the caller: whether running without one is a problem is not
the driver's to say. An unreadable subscription reports nothing.
"""
sub = self._get_node_subscription()
raw = str(sub.get("status", ""))
if not raw:
return []
lic: LicenseDict = {
"name": self.SUBSCRIPTION_LICENSE,
"status": _SUBSCRIPTION_STATUS.get(raw.lower(), "unknown"),
"detail": str(sub.get("message") or raw),
}
if sub.get("productname"):
lic["edition"] = sub["productname"]
if sub.get("nextduedate"):
lic["expires"] = sub["nextduedate"]
return [lic]
def _run_service_command(self, command: str, *, privileged: bool, timeout: int) -> str:
"""The transport for ``SystemdServicesMixin``: the exec path, as root.
*privileged* needs nothing more on a node the driver reaches as root, and
the exec path keeps its own timeout.
"""
return str(self._exec_ssh_command(command))
def get_available_updates(self) -> list[_JsonDict]:
"""Return the node's upgradable packages, with origin and security status.
``apt list --upgradable`` over the exec path names each candidate's suite
(``trixie-security``); the APT API names only an Origin ("Debian",
"Proxmox") and is the fallback, with the security status unknown.
:raises Exception: when neither answers -- never an empty list for
"could not read".
"""
updates: list[_JsonDict]
try:
raw = self._exec_ssh_command(APT_UPGRADABLE_COMMAND) or ""
updates = [dict(u) for u in parse_apt_upgradable(raw)]
except ValueError as exc:
logger.debug("apt list over the exec path failed, using the API: %s", exc)
updates = self._updates_from_api()
return sorted(updates, key=lambda u: u["name"])
def _updates_from_api(self) -> list[_JsonDict]:
return [
{
"name": upd["Package"],
"current_version": upd.get("OldVersion", ""),
"new_version": upd.get("Version", ""),
"origin": upd.get("Origin"),
"security": None,
}
for upd in self._node_api().apt.update.get()
if upd.get("Package")
]
def refresh_available_updates(self) -> _JsonDict:
"""Resynchronise the node's package index (``POST nodes/{n}/apt/update``)."""
try:
task = self._node_api().apt.update.post()
except Exception as exc:
return {"success": False, "output": str(exc)}
return {"success": True, "output": f"Package index refresh started ({task})"}
def _run_host_status_command(self, command: str) -> str:
"""The transport for ``HostStatusMixin.get_host_status``: the exec path."""
return str(self._exec_ssh_command(command))
def apply_updates(self, packages: list[str]) -> _JsonDict:
"""Upgrade the given packages via ``apt-get install`` over SSH."""
for pkg in packages:
if not re.match(r"^[a-zA-Z0-9_\-\+\.]+$", pkg):
raise ValueError(f"Invalid package name: {pkg!r}")
pkg_args = " ".join(packages)
output, status = self._rc(
f"DEBIAN_FRONTEND=noninteractive apt-get install --only-upgrade -y {pkg_args}"
)
if status == 0:
return {"success": True, "output": output}
error = (
f"apt-get exited with status {status}"
if status >= 0
else "apt-get's exit status could not be read"
)
return {"success": False, "output": output, "error": error}
def _rc(self, command: str) -> tuple[str, int]:
"""Run *command* and return its output and exit status (-1 when unknown)."""
out = self._exec_ssh_command(f"{{ {command}; }} 2>&1; echo __PVE_RC=$?")
text, _, tail = out.rpartition("__PVE_RC=")
try:
return text.strip(), int(tail.strip())
except ValueError:
return out.strip(), -1
def _step(self, command: str, done: str) -> FixStepOutcomeDict:
output, status = self._rc(command)
return {"ok": status == 0, "output": done if status == 0 else output[-300:]}
def _run_apt_command(self, command: str) -> str:
return str(self._exec_ssh_command(command))
def _run_apt_root_command(self, command: str, done: str) -> FixStepOutcomeDict:
return self._step(command, done)
def _write_apt_file(self, path: str, content: str) -> FixStepOutcomeDict:
return self._write_root_file(path, content)
def _write_root_file(self, path: str, content: str) -> FixStepOutcomeDict:
"""Write *content* to *path* as root, mode 644, through a temporary file."""
encoded = base64.b64encode(content.encode()).decode()
# No ``exit`` here: it would end the shell before ``_rc`` reads the status.
return self._step(
f'umask 077 && t=$(mktemp) && echo {encoded} | base64 -d > "$t" && '
f'install -m 644 -o root -g root "$t" {shlex.quote(path)}; '
's=$?; rm -f "$t"; [ "$s" -eq 0 ]',
f"wrote {path}",
)
def install_package(self, name: str, version: str = "") -> None:
"""apt-get install *name* (``PackageManagementMixin``); raises when apt fails."""
if not _PACKAGE_NAME.match(name) or (version and not _PACKAGE_NAME.match(version)):
raise ValueError(f"not a package name: {name!r}")
target = f"{name}={version}" if version else name
output, status = self._rc(f"DEBIAN_FRONTEND=noninteractive apt-get install -y {target}")
if status != 0:
raise RuntimeError(f"apt-get install {target} failed: {output[-300:]}")
def get_management_peer(self) -> str | None:
"""The address the node sees the SSH connection come from (``SSH_CONNECTION``)."""
out = self._exec_ssh_command('printf "%s\\n" "$SSH_CONNECTION"').split()
try:
return str(ipaddress.ip_address(out[0])) if out else None
except ValueError:
return None
def reboot_host(self) -> None:
"""Restart the node through the API (no SSH involved)."""
try:
self._node_api().status.post(command="reboot")
except Exception as exc:
raise RuntimeError(f"Reboot of node {self._node_name!r} refused: {exc}") from exc
def shutdown_host(self) -> None:
"""Shut the node down through the API; on PVE its guests stop as on any shutdown."""
try:
self._node_api().status.post(command="shutdown")
except Exception as exc:
raise RuntimeError(f"Shutdown of node {self._node_name!r} refused: {exc}") from exc
def parse_dpkg_line(line: str, source: str) -> _JsonDict | None:
"""One installed package from a line of the ``dpkg-query`` format above, or
None for a line that is not an installed package."""
parts = line.strip().split("\t")
if len(parts) < 2 or not parts[0]:
return None
name, version = parts[0], parts[1]
status = parts[2] if len(parts) > 2 else "installed"
if status != "installed":
return None
size_kb, source_package_field, source_version_field = (parts[3:] + ["", "", ""])[:3]
# Debian source package (differs from the binary for split packages,
# e.g. openssh-server → openssh). Needed for accurate OSV matching.
source_package = source_package_field or name
# And its version, which is a different number from this package's.
#
# OSV states Debian ranges in *source* versions, so a consumer given
# the source package and only the binary version compares two
# unrelated numbers: libldb2 is 2:2.11.0+samba4.22.11+dfsg-… while
# its source, samba, is 2:4.22.11+dfsg-…. Reporting the source
# without its version is worse than reporting neither, because it
# looks usable. Every package on all three Proxmox nodes was in that
# state — the format string never asked for the field.
#
# dpkg leaves it empty when it equals `Version`, and so does an
# older dpkg that does not know the field at all.
source_version = source_version_field or version
return {
"name": name,
"version": version,
"installed": True,
"description": "",
"size": int(size_kb) * 1024 if size_kb.isdigit() else 0,
"source": source,
"source_package": source_package,
"source_version": source_version,
}