Files
napalm-proxmox/napalm_proxmox/pbs_backups.py
T
Christian Manivong 2b2cd9b867
driver / lint (pull_request) Successful in 14s
driver / standard (pull_request) Successful in 16s
driver / types (pull_request) Successful in 1m5s
driver / test (3.13) (pull_request) Successful in 1m4s
driver / test (3.12) (pull_request) Successful in 1m10s
driver / lowest (pull_request) Successful in 31s
driver / build (pull_request) Successful in 30s
driver / security (pull_request) Successful in 1m0s
CI / driver (pull_request) Successful in 2m20s
driver / publish (pull_request) Skipped
feat(pbs): Proxmox Backup Server as entry point proxmox_backup (#52)
A second driver in this package, ProxmoxBackupDriver. Its API and web UI
are on 8007, not on PVE's 8006, and its node is always localhost; open()
proves the login with GET /version, so a bad token fails there.

Roles: BackupServerDriver (napalm-device-types 4.25.0) first, then
StorageDriver for the disks and ZFS pools the server manages. It reads
datastores, the backup groups of every namespace with their newest
snapshot, a group's snapshots, the GC, verify, prune, sync and tape jobs
with how their last run ended, and the remotes without their secrets;
it starts garbage collection and jobs, verifies, protects and deletes
snapshots, and follows the tasks. As a host it reports facts,
interfaces, CPU and memory, disks, pools, its pbs-subscription and the
same packages, updates, host readers and sshd hardening as a PVE node.

A privilege-separated token without an ACL entry gets an empty list from
PBS, not a refusal, so every read checks /access/permissions and raises
PermissionError. A removable datastore that is not mounted is reported
as unmounted and left out of the group listing.

The fixture is what a PBS 4.2 answered, sanitised; groups, snapshots and
jobs it did not have yet follow the API schema.
2026-11-02 22:29:21 +01:00

315 lines
12 KiB
Python

"""The backup-server role of the Proxmox Backup Server driver.
Datastores, backup groups with their snapshots, the jobs that keep them
(garbage collection, verify, prune, sync, tape) and the remotes, read through
the PBS REST API, plus the actions on them.
A privilege-separated API token without an ACL entry does not get a 403 for a
listing: PBS filters the list by privilege and answers ``[]``. An empty list
therefore says nothing until ``/access/permissions`` shows the privilege, so
every read checks it first.
"""
from __future__ import annotations
from typing import Any
from napalm_device_types import (
BackupDatastoreDict,
BackupGroupDict,
BackupJobKind,
BackupRemoteDict,
BackupRunState,
BackupServerJobDict,
BackupSnapshotDict,
BackupSnapshotRefDict,
BackupTaskDict,
BackupTaskStatusDict,
)
from proxmoxer.core import ResourceException
_JsonDict = dict[str, Any]
#: Where "run this job now" is, per kind; ``{id}`` is the job, for GC the datastore.
_RUN_PATHS: dict[str, str] = {
"gc": "admin/datastore/{id}/gc",
"verify": "admin/verify/{id}/run",
"prune": "admin/prune/{id}/run",
"sync": "admin/sync/{id}/run",
"tape": "tape/backup/{id}",
}
#: Where each kind's jobs are listed with the state of their last run.
_JOB_LISTS: dict[BackupJobKind, str] = {
"gc": "admin/gc",
"verify": "admin/verify",
"prune": "admin/prune",
"sync": "admin/sync",
"tape": "tape/backup",
}
def run_state(text: str | None) -> tuple[BackupRunState | None, str | None]:
"""A job's ``last-run-state`` or a task's ``exitstatus``: the state and the error."""
if not text:
return None, None
if text == "OK":
return "ok", None
if text.startswith("WARNINGS"):
return "warning", text
return "error", text
def _granted(rights: dict[str, dict[str, Any]], privilege: str, path: str) -> bool:
"""Whether *privilege* holds on *path*, given on the path itself or propagated
from a parent (``/access/permissions``: privilege -> propagate flag)."""
for granted_on, privileges in rights.items():
if privilege not in privileges:
continue
if granted_on == path:
return True
parent = granted_on.rstrip("/") + "/"
if path.startswith(parent) and privileges[privilege]:
return True
return False
def _maintenance(config: _JsonDict, mount_status: str | None) -> str | None:
for part in str(config.get("maintenance-mode") or "").split(","):
key, _, value = part.partition("=")
if key == "type" and value:
return value
return "unmounted" if mount_status == "notmounted" else None
def _datastore(usage: _JsonDict, config: _JsonDict) -> BackupDatastoreDict:
"""One datastore from its ``status/datastore-usage`` row and its configuration."""
if usage.get("backend-type") == "s3":
backend = "s3"
elif config.get("backing-device"):
backend = "removable"
else:
backend = "local"
# A removable datastore's path is relative to wherever it is mounted.
path = config.get("path")
full = usage.get("estimated-full-date")
return {
"name": usage["store"],
"path": path if isinstance(path, str) and path.startswith("/") else None,
"backend": backend,
"total": usage.get("total"),
"used": usage.get("used"),
"available": usage.get("avail"),
"estimated_full": full if isinstance(full, int) and full > 0 else None,
"maintenance": _maintenance(config, usage.get("mount-status")),
"comment": config.get("comment"),
}
def _snapshot(raw: _JsonDict) -> BackupSnapshotDict:
state = (raw.get("verification") or {}).get("state")
return {
"time": int(raw["backup-time"]),
"size": raw.get("size"),
"verify": state if state in ("ok", "failed") else None,
"protected": bool(raw.get("protected")),
"comment": raw.get("comment"),
}
def _job(kind: BackupJobKind, raw: _JsonDict) -> BackupServerJobDict:
state, error = run_state(raw.get("last-run-state"))
if state is None and raw.get("last-run-upid") and not raw.get("last-run-endtime"):
state = "running"
sync = kind == "sync"
enabled = not raw.get("disable") if kind == "prune" else bool(raw.get("schedule"))
return {
"id": raw["store"] if kind == "gc" else raw["id"],
"kind": kind,
"datastore": raw.get("store"),
"namespace": raw.get("ns"),
"schedule": raw.get("schedule"),
"enabled": enabled,
"last_run": raw.get("last-run-endtime"),
"last_state": state,
"last_error": error,
"next_run": raw.get("next-run"),
"remote": raw.get("remote") if sync else None,
"direction": (raw.get("sync-direction") or "pull") if sync else None,
"comment": raw.get("comment"),
}
def _snapshot_params(snapshot: BackupSnapshotRefDict) -> _JsonDict:
params: _JsonDict = {
"backup-type": snapshot["group_type"],
"backup-id": snapshot["group_id"],
"backup-time": snapshot["time"],
}
if snapshot["namespace"]:
params["ns"] = snapshot["namespace"]
return params
class ProxmoxBackupServerMixin:
"""``BackupServerDriver`` for Proxmox Backup Server."""
_api: Any
_node_name: str
# ------------------------------------------------------------------ #
# Plumbing
# ------------------------------------------------------------------ #
def _pbs(self, method: str, path: str, **params: Any) -> Any:
"""One API call. A 400 or 404 is the caller's mistake (no such datastore,
job, snapshot or task): ValueError. Everything else propagates."""
try:
return getattr(self._api, method)(path, **params)
except ResourceException as exc:
if exc.status_code in (400, 404):
raise ValueError(f"{method.upper()} {path}: {exc}") from exc
raise
def _require(self, privilege: str, path: str) -> None:
rights = self._pbs("get", "access/permissions") or {}
if not _granted(rights, privilege, path):
raise PermissionError(
f"the API login lacks {privilege} on {path}; the server would answer "
"with an empty list rather than refuse"
)
@staticmethod
def _task(upid: Any, what: str) -> BackupTaskDict:
if not isinstance(upid, str) or not upid:
raise RuntimeError(f"{what}: the server returned no task id")
return {"task": upid}
# ------------------------------------------------------------------ #
# Read
# ------------------------------------------------------------------ #
def get_backup_datastores(self) -> list[BackupDatastoreDict]:
self._require("Datastore.Audit", "/datastore")
configs = {c["name"]: c for c in self._pbs("get", "config/datastore") or []}
return [
_datastore(usage, configs.get(usage["store"], {}))
for usage in self._pbs("get", "status/datastore-usage") or []
]
def get_backup_groups(self, datastore: str = "") -> list[BackupGroupDict]:
"""The groups of *datastore*, or of every datastore whose content can be
read: a removable one that is not mounted is left out of the listing
(``get_backup_datastores`` reports it as ``"unmounted"``), and raises
ValueError when asked for by name."""
self._require("Datastore.Audit", "/datastore")
stores = (
[datastore]
if datastore
else [
d["store"]
for d in self._pbs("get", "admin/datastore") or []
if d.get("mount-status") != "notmounted"
]
)
groups: list[BackupGroupDict] = []
for store in stores:
for ns in self._pbs("get", f"admin/datastore/{store}/namespace") or []:
groups.extend(self._groups_in(store, ns.get("ns") or ""))
return groups
def _groups_in(self, store: str, namespace: str) -> list[BackupGroupDict]:
params = {"ns": namespace} if namespace else {}
snapshots: dict[tuple[str, str], list[BackupSnapshotDict]] = {}
for raw in self._pbs("get", f"admin/datastore/{store}/snapshots", **params) or []:
key = (raw["backup-type"], raw["backup-id"])
snapshots.setdefault(key, []).append(_snapshot(raw))
groups: list[BackupGroupDict] = []
for raw in self._pbs("get", f"admin/datastore/{store}/groups", **params) or []:
own = snapshots.get((raw["backup-type"], raw["backup-id"]), [])
groups.append(
{
"datastore": store,
"namespace": namespace,
"type": raw["backup-type"],
"id": raw["backup-id"],
"owner": raw.get("owner"),
"count": int(raw.get("backup-count") or 0),
"newest": max(own, key=lambda s: s["time"]) if own else None,
"oldest_time": min(s["time"] for s in own) if own else None,
"comment": raw.get("comment"),
}
)
return groups
def get_backup_snapshots(
self, datastore: str, namespace: str, group_type: str, group_id: str
) -> list[BackupSnapshotDict]:
self._require("Datastore.Audit", "/datastore")
params: _JsonDict = {"backup-type": group_type, "backup-id": group_id}
if namespace:
params["ns"] = namespace
raw = self._pbs("get", f"admin/datastore/{datastore}/snapshots", **params) or []
return sorted((_snapshot(s) for s in raw), key=lambda s: s["time"], reverse=True)
def get_backup_jobs(self) -> list[BackupServerJobDict]:
self._require("Datastore.Audit", "/datastore")
jobs: list[BackupServerJobDict] = []
for kind, path in _JOB_LISTS.items():
jobs.extend(_job(kind, raw) for raw in self._pbs("get", path) or [])
return jobs
def get_backup_remotes(self) -> list[BackupRemoteDict]:
self._require("Remote.Audit", "/remote")
return [
{
"name": raw["name"],
"host": raw["host"],
"port": raw.get("port"),
"fingerprint": raw.get("fingerprint"),
"auth_id": raw.get("auth-id"),
"comment": raw.get("comment"),
}
for raw in self._pbs("get", "config/remote") or []
]
# ------------------------------------------------------------------ #
# Actions
# ------------------------------------------------------------------ #
def start_garbage_collection(self, datastore: str) -> BackupTaskDict:
return self.run_backup_job("gc", datastore)
def run_backup_job(self, kind: BackupJobKind, job_id: str) -> BackupTaskDict:
if kind not in _RUN_PATHS:
raise ValueError(f"unknown job kind {kind!r}; one of {', '.join(_RUN_PATHS)}")
path = _RUN_PATHS[kind].format(id=job_id)
return self._task(self._pbs("post", path), f"{kind} job {job_id}")
def verify_backup_snapshot(self, snapshot: BackupSnapshotRefDict) -> BackupTaskDict:
path = f"admin/datastore/{snapshot['datastore']}/verify"
return self._task(self._pbs("post", path, **_snapshot_params(snapshot)), "verify")
def set_backup_snapshot_protected(
self, snapshot: BackupSnapshotRefDict, protected: bool
) -> None:
path = f"admin/datastore/{snapshot['datastore']}/protected"
self._pbs("put", path, **_snapshot_params(snapshot), protected=int(protected))
def delete_backup_snapshot(self, snapshot: BackupSnapshotRefDict) -> None:
path = f"admin/datastore/{snapshot['datastore']}/snapshots"
self._pbs("delete", path, **_snapshot_params(snapshot))
def get_backup_task(self, task: str) -> BackupTaskStatusDict:
base = f"nodes/{self._node_name}/tasks/{task}"
status = self._pbs("get", f"{base}/status") or {}
log = self._pbs("get", f"{base}/log", limit=0) or []
running = status.get("status") == "running"
state, error = ("running", None) if running else run_state(status.get("exitstatus"))
return {
"task": task,
"running": running,
"state": state,
"error": error,
"log": [str(line.get("t", "")) for line in log],
}