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
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.
315 lines
12 KiB
Python
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],
|
|
}
|