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.
409 lines
17 KiB
Python
409 lines
17 KiB
Python
"""What the Proxmox VE and the Proxmox Backup Server drivers share.
|
|
|
|
Both products speak the same REST dialect (``/api2/json``, ``/nodes/{node}/...``),
|
|
authenticate the same way (``user@realm`` with a password, or an API token
|
|
``user@realm!name``) and run on Debian, where the driver opens its own SSH
|
|
session as root for what the API does not offer. They differ in the service
|
|
proxmoxer talks to, its port (PVE 8006, PBS 8007) and how the node is found.
|
|
|
|
Optional args
|
|
-------------
|
|
verify_ssl : bool
|
|
Verify TLS certificates (default: True). ``ssl_verify`` and ``verify`` are
|
|
accepted as well.
|
|
port : int
|
|
API port (default: the service's, 8006 for PVE, 8007 for PBS).
|
|
realm : str
|
|
Realm a bare username logs in to (default: ``pam``).
|
|
token_name : str
|
|
API token name (e.g. ``root@pam!netork``).
|
|
token_value : str
|
|
API token secret. With both token_name and token_value, the token is used
|
|
instead of the password.
|
|
ssh_username, ssh_password, ssh_private_key_str : str
|
|
The node's SSH login; the API login's username and password otherwise.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import io
|
|
import logging
|
|
from typing import Any
|
|
|
|
from napalm.base.exceptions import ConnectionException
|
|
from napalm_device_types import CommandResult
|
|
from napalm_device_types.channel import run_on_transport
|
|
from napalm_device_types.ssh_host_keys import HostKeyCheck
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
_JsonDict = dict[str, Any]
|
|
|
|
#: The API port of each proxmoxer service this package drives.
|
|
DEFAULT_PORTS = {"PVE": 8006, "PBS": 8007}
|
|
|
|
|
|
class ProxmoxBase:
|
|
"""Connection, SSH session and node helpers of a Proxmox product's driver.
|
|
|
|
A concrete driver sets :attr:`SERVICE`, says how it finds its node
|
|
(:meth:`_resolve_node`) and constructs the proxmoxer client
|
|
(:meth:`_proxmox_api`), so its own module names the client class.
|
|
"""
|
|
|
|
#: The proxmoxer service: ``"PVE"`` or ``"PBS"``.
|
|
SERVICE = "PVE"
|
|
|
|
def __init__(
|
|
self,
|
|
hostname: str,
|
|
username: str,
|
|
password: str,
|
|
timeout: int = 60,
|
|
optional_args: _JsonDict | None = None,
|
|
) -> None:
|
|
self.hostname = hostname
|
|
self.username = username
|
|
self.password = password
|
|
self.timeout = timeout
|
|
self.optional_args: _JsonDict = optional_args or {}
|
|
|
|
self._port: int = self.optional_args.get("port", DEFAULT_PORTS[self.SERVICE])
|
|
verify: Any = self.optional_args.get(
|
|
"verify_ssl",
|
|
self.optional_args.get("ssl_verify", self.optional_args.get("verify", True)),
|
|
)
|
|
self._verify_ssl: bool = verify
|
|
self._realm: str = self.optional_args.get("realm", "pam")
|
|
self._token_name: str | None = self.optional_args.get("token_name")
|
|
self._token_value: str | None = self.optional_args.get("token_value")
|
|
|
|
self._ssh_username: str | None = self.optional_args.get("ssh_username")
|
|
self._ssh_password: str | None = self.optional_args.get("ssh_password")
|
|
self._ssh_key: str | None = self.optional_args.get("ssh_private_key_str")
|
|
|
|
self._api: Any = None # proxmoxer.ProxmoxAPI
|
|
self._node_name: str = ""
|
|
# paramiko.SSHClient; paramiko is imported lazily (see _node_ssh).
|
|
self._ssh_client: Any = None
|
|
|
|
# ------------------------------------------------------------------ #
|
|
# Connection management
|
|
# ------------------------------------------------------------------ #
|
|
|
|
def _proxmox_api(self, **kwargs: Any) -> Any:
|
|
"""The proxmoxer client for *kwargs*; the concrete driver's module names the class."""
|
|
raise NotImplementedError
|
|
|
|
def _resolve_node(self) -> str:
|
|
"""Find the node this connection talks to and set ``_node_name``.
|
|
|
|
API errors propagate, so that ``open()`` fails with the real cause.
|
|
"""
|
|
raise NotImplementedError
|
|
|
|
def _api_kwargs(self) -> _JsonDict:
|
|
# Use the HTTPS backend for proper REST API support.
|
|
# The openssh backend tunnels all kwargs through to
|
|
# openssh_wrapper.CommandBaseSession, which does not
|
|
# accept password/verify_ssl/token params.
|
|
# Proxmox authenticates against "<user>@<realm>" and rejects a bare
|
|
# username outright. A caller who typed a realm keeps it; one who
|
|
# did not gets self._realm, which is what the documented `realm`
|
|
# optional_arg is for -- it was read in __init__ and then never
|
|
# used, so the option had no effect and a bare username failed.
|
|
user = self.username or ""
|
|
if user and "@" not in user:
|
|
user = f"{user}@{self._realm}"
|
|
|
|
kwargs: _JsonDict = {
|
|
"host": self.hostname,
|
|
"user": user,
|
|
"password": self.password,
|
|
"port": self._port,
|
|
"verify_ssl": self._verify_ssl,
|
|
"backend": "https",
|
|
"service": self.SERVICE,
|
|
}
|
|
|
|
if self._token_name and self._token_value:
|
|
kwargs.pop("password", None)
|
|
kwargs["token_value"] = self._token_value
|
|
# token_name may be in "<user>!<tokenid>" format (e.g.
|
|
# "root@pam!netork"). proxmoxer expects them split:
|
|
# user="root@pam", token_name="netork"
|
|
user_part, _, token_id = self._token_name.partition("!")
|
|
if token_id:
|
|
kwargs["user"] = user_part
|
|
kwargs["token_name"] = token_id
|
|
else:
|
|
kwargs["token_name"] = self._token_name
|
|
return kwargs
|
|
|
|
def open(self) -> None:
|
|
"""Open the connection to the Proxmox API."""
|
|
try:
|
|
self._api = self._proxmox_api(**self._api_kwargs())
|
|
# Validate the connection: finding the node needs a working login.
|
|
self._resolve_node()
|
|
except Exception as exc:
|
|
raise ConnectionException(f"Cannot connect to {self.hostname}: {exc}") from exc
|
|
|
|
def close(self) -> None:
|
|
"""Close the connection."""
|
|
self._api = None
|
|
if self._ssh_client:
|
|
try:
|
|
self._ssh_client.close()
|
|
except Exception:
|
|
logger.debug("%s: closing the SSH session: ignored", self.hostname, exc_info=True)
|
|
self._ssh_client = None
|
|
|
|
def is_alive(self) -> _JsonDict:
|
|
"""Return connection liveness.
|
|
|
|
Probes ``GET /version``, the cheapest endpoint that proves the session
|
|
still authenticates. It used to call ``_resolve_node()``, which returns
|
|
early without touching the API whenever a node was configured via
|
|
optional_args — so a dead connection reported itself alive.
|
|
"""
|
|
alive = False
|
|
if self._api:
|
|
try:
|
|
self._api.version.get()
|
|
alive = True
|
|
except Exception:
|
|
logger.debug("%s: liveness probe failed", self.hostname, exc_info=True)
|
|
return {"is_alive": alive}
|
|
|
|
# ------------------------------------------------------------------ #
|
|
# Internal API helpers
|
|
# ------------------------------------------------------------------ #
|
|
|
|
def _node_api(self) -> Any:
|
|
"""Return the API resource for the current node."""
|
|
return self._api.nodes(self._node_name)
|
|
|
|
def _get_node_network(self) -> list[_JsonDict]:
|
|
"""Return the node's network interface list from the Proxmox API."""
|
|
try:
|
|
return self._node_api().network.get() or []
|
|
except Exception as exc:
|
|
logger.debug("Failed to fetch node network: %s", exc)
|
|
return []
|
|
|
|
def _exec_ssh_command(self, command: str) -> str:
|
|
"""Run *command* in the node's shell over SSH and return what it printed.
|
|
|
|
Stdout only: stderr is not output (a command that wants it says
|
|
``2>&1``). The exit status is not checked; a caller that needs it asks
|
|
for it (``_rc``). The node has no API endpoint that runs a shell command
|
|
(``/nodes/{node}/execute`` runs a batch of API calls), so this is the
|
|
one way, the same session ``_run_node_command`` uses (see
|
|
NAPALM/napalm-device-types#35 for the shared transport).
|
|
|
|
:raises ConnectionException: when the command could not run: no SSH
|
|
credential, a refused login or host key (``SshHostKeyMismatch``),
|
|
an unreachable node, a timeout.
|
|
"""
|
|
try:
|
|
_, stdout, stderr = self._node_ssh().exec_command(command, timeout=self.timeout)
|
|
out: str = stdout.read().decode(errors="replace")
|
|
err: str = stderr.read().decode(errors="replace").strip()
|
|
except ConnectionException:
|
|
raise
|
|
except _ssh_errors() as exc:
|
|
raise ConnectionException(
|
|
f"Cannot run a command on {self.hostname} over SSH: {exc}"
|
|
) from exc
|
|
if err:
|
|
logger.debug("%s: stderr of a node command: %s", self.hostname, err[-300:])
|
|
return out.strip()
|
|
|
|
def run_command(
|
|
self,
|
|
command: str,
|
|
*,
|
|
privileged: bool = False,
|
|
timeout: float = 60,
|
|
stdin: bytes | None = None,
|
|
) -> CommandResult:
|
|
"""Run *command* on an exec channel of the node's SSH session (``CommandChannelMixin``).
|
|
|
|
stdout, stderr and the exit status come back apart; *stdin*, if given, is
|
|
written and then closed. *privileged* needs nothing more: the node is
|
|
logged in as root, as for every other command this driver runs there.
|
|
|
|
:raises ConnectionException: when the command could not run, or did not
|
|
finish within *timeout* seconds.
|
|
"""
|
|
try:
|
|
transport = self._node_ssh().get_transport()
|
|
return run_on_transport(transport, command, stdin=stdin, timeout=timeout)
|
|
except ConnectionException:
|
|
raise
|
|
except _ssh_errors() as exc:
|
|
raise ConnectionException(
|
|
f"Cannot run a command on {self.hostname} over SSH: {exc}"
|
|
) from exc
|
|
|
|
def _node_ssh(self) -> Any: # paramiko.SSHClient; paramiko is imported lazily
|
|
"""The SSH session to the node on port 22, opened once.
|
|
|
|
Its host key is the one the caller expects for port 22, or on first use
|
|
whichever the node presents; either way it is reported (netork#1167).
|
|
|
|
:raises ConnectionException: without a password or a usable key.
|
|
"""
|
|
import paramiko
|
|
|
|
if self._ssh_client is None:
|
|
# A key is tried first; paramiko falls back to the password. Only
|
|
# these: not the keys in the process's own ~/.ssh, nor an agent.
|
|
connect_kwargs: _JsonDict = {
|
|
"username": self._ssh_username or self.username,
|
|
"timeout": self.timeout,
|
|
"look_for_keys": False,
|
|
"allow_agent": False,
|
|
}
|
|
password = self._ssh_password or self.password
|
|
if password:
|
|
connect_kwargs["password"] = password
|
|
pkey = _load_private_key(self._ssh_key) if self._ssh_key else None
|
|
if pkey is not None:
|
|
connect_kwargs["pkey"] = pkey
|
|
if not password and pkey is None:
|
|
# An API-token-only node: nothing to log in with, so no connection.
|
|
raise ConnectionException(
|
|
f"no SSH credential for {self.hostname}: set ssh_password or "
|
|
"ssh_private_key_str"
|
|
)
|
|
client = paramiko.SSHClient()
|
|
try:
|
|
HostKeyCheck(self.optional_args, self.hostname, 22).connect(
|
|
client, **connect_kwargs
|
|
)
|
|
except Exception:
|
|
client.close()
|
|
raise
|
|
self._ssh_client = client
|
|
return self._ssh_client
|
|
|
|
# ------------------------------------------------------------------ #
|
|
# Node info helpers
|
|
# ------------------------------------------------------------------ #
|
|
|
|
def _get_version_info(self) -> _JsonDict:
|
|
"""Return the product's version info from the API."""
|
|
try:
|
|
return self._api.version.get() or {}
|
|
except Exception as exc:
|
|
logger.debug("Failed to fetch version info: %s", exc)
|
|
return {}
|
|
|
|
def _get_node_status(self) -> _JsonDict:
|
|
"""Return the node's status from the Proxmox API."""
|
|
try:
|
|
return self._node_api().status.get() or {}
|
|
except Exception as exc:
|
|
logger.debug("Failed to fetch node status: %s", exc)
|
|
return {}
|
|
|
|
def _get_node_subscription(self) -> _JsonDict:
|
|
"""Return subscription status for this node."""
|
|
try:
|
|
return self._node_api().subscription.get() or {}
|
|
except Exception as exc:
|
|
logger.debug("Failed to fetch node subscription: %s", exc)
|
|
return {}
|
|
|
|
def _get_node_dns(self) -> _JsonDict:
|
|
"""Return DNS configuration for this node."""
|
|
try:
|
|
return self._node_api().dns.get() or {}
|
|
except Exception as exc:
|
|
logger.debug("Failed to fetch node DNS: %s", exc)
|
|
return {}
|
|
|
|
def _get_node_time(self) -> _JsonDict:
|
|
"""Return time configuration for this node."""
|
|
try:
|
|
return self._node_api().time.get() or {}
|
|
except Exception as exc:
|
|
logger.debug("Failed to fetch node time: %s", exc)
|
|
return {}
|
|
|
|
def _hardware(self) -> tuple[str, str, str]:
|
|
"""The physical machine's vendor, model and serial number, from the Linux DMI
|
|
sysfs entries over SSH; empty strings where they cannot be read."""
|
|
# Physical hardware info from Linux DMI sysfs.
|
|
# Read each field separately to avoid shell quoting issues with printf.
|
|
# Field priority for model:
|
|
# product_name — human-readable name on most vendors (e.g. "NUC6CAYH",
|
|
# "ThinkCentre M910x")
|
|
# product_version — sometimes the marketing name on Lenovo; on Intel NUC
|
|
# it is the board part number (less useful as model name)
|
|
# We prefer product_name; fall back to product_version only when
|
|
# product_name looks like a raw type code (all uppercase + digits, no spaces).
|
|
vendor = ""
|
|
model = ""
|
|
serial = ""
|
|
try:
|
|
dmi_cmd = (
|
|
"v=$(cat /sys/class/dmi/id/sys_vendor 2>/dev/null); "
|
|
"n=$(cat /sys/class/dmi/id/product_name 2>/dev/null); "
|
|
"r=$(cat /sys/class/dmi/id/product_version 2>/dev/null); "
|
|
"s=$(cat /sys/class/dmi/id/product_serial 2>/dev/null); "
|
|
'printf \'%s\\n%s\\n%s\\n%s\\n\' "$v" "$n" "$r" "$s"'
|
|
)
|
|
lines = self._exec_ssh_command(dmi_cmd).splitlines()
|
|
if len(lines) >= 4:
|
|
vendor = lines[0].strip()
|
|
product_name = lines[1].strip()
|
|
product_version = lines[2].strip()
|
|
serial = lines[3].strip()
|
|
|
|
_bad = {"none", "n/a", "not specified", "to be filled by o.e.m."}
|
|
pv_usable = (
|
|
product_version
|
|
and product_version.lower() not in _bad
|
|
and product_version != product_name
|
|
# Only prefer product_version when it contains a space —
|
|
# that indicates a human-readable marketing name like
|
|
# "ThinkCentre M910x" rather than a part code like "J26843-409".
|
|
and " " in product_version
|
|
)
|
|
model = product_version if pv_usable else product_name
|
|
except Exception as exc:
|
|
logger.debug("Failed to read DMI info via SSH: %s", exc)
|
|
return vendor, model, serial
|
|
|
|
# ------------------------------------------------------------------ #
|
|
# CLI passthrough
|
|
# ------------------------------------------------------------------ #
|
|
|
|
def cli(self, commands: list[str], encoding: str = "text") -> dict[str, str]:
|
|
"""Execute a list of shell commands and return their outputs."""
|
|
return {cmd: self._exec_ssh_command(cmd) for cmd in commands}
|
|
|
|
|
|
def _load_private_key(text: str) -> Any: # paramiko.PKey; paramiko is imported lazily
|
|
"""The SSH private key in *text*, whatever its type, or None when it cannot be read."""
|
|
import paramiko
|
|
|
|
for key_class in (paramiko.Ed25519Key, paramiko.ECDSAKey, paramiko.RSAKey):
|
|
try:
|
|
return key_class.from_private_key(io.StringIO(text))
|
|
except (paramiko.SSHException, ValueError):
|
|
continue
|
|
logger.warning("The SSH private key could not be read; logging in with the password")
|
|
return None
|
|
|
|
|
|
def _ssh_errors() -> tuple[type[Exception], ...]:
|
|
"""What a command that could not run raises: the socket's errors, timeouts
|
|
included, and paramiko's (a refused login, a closed session)."""
|
|
import paramiko
|
|
|
|
return (OSError, paramiko.SSHException)
|