feat(pbs): Proxmox Backup Server as entry point proxmox_backup (#52) #53

Merged
christianmanivong merged 2 commits from feat/proxmox-backup into main 2026-11-02 21:35:53 +00:00
Owner

Closes #52. Part of NetOrk/netork#1918 (Proxmox Backup Server support).

What

A second driver in this package: proxmox_backup = "napalm_proxmox:ProxmoxBackupDriver". API and web UI on 8007, node always localhost. Roles: BackupServerDriver (napalm-device-types 4.25.0, already on PyPI) first, StorageDriver second.

Two commits:

  1. refactor — what both products share moves out of ProxmoxDriver: _base.py (connection with proxmoxer service PVE/PBS and its port, token split, SSH session, run_command, node helpers, DMI) and host_mixin.py (packages, APT updates, subscription, reboot/shutdown via API, root file writes, the host readers' transports). The PVE driver behaves as before: tests/test_connection_args.py pins what it hands proxmoxer; it now names service="PVE" explicitly. get_packages is split; PVE's get_facts and get_packages leave the quality baseline. This commit is green on its own (538 tests, ratchet).
  2. feat — backup_driver.py, pbs_backups.py (datastores, groups, snapshots, jobs, remotes, actions, tasks) and pbs_host.py (facts, interfaces, environment, disks, ZFS pools).

Found on the real server (PBS 4.2)

  • A privilege-separated token without an ACL entry gets [], not 403, for datastores and jobs — and Audit on / does not include Remote.Audit (four remotes listed as []). Every read checks /access/permissions first and raises PermissionError.
  • A removable datastore that is not mounted answers 400 for its content. It is reported as maintenance: "unmounted" and left out of get_backup_groups(); asked for by name it raises ValueError.
  • disks/list runs smartctl and can outlast proxmoxer's default 5 s timeout.
  • The API carries no MAC address for an interface; it is read over SSH (and stays empty without it).

Fixtures

tests/fixtures/pbs_api.json is what the server answered, sanitised (addresses, domain, serials, server id, UUIDs, certificate fingerprint, guest name replaced; the sanitiser refuses to write a recorded error as an answer). Groups, snapshots and jobs it did not have yet follow the PBS API schema (pbs.proxmox.com/docs/api-viewer), marked as such in the tests.

Checks

  • pytest: 599 passed; coverage 82 % (floor 68), new modules 98–100 %.
  • ruff format --check, ruff check: clean. mypy --strict on the new modules: clean.
  • napalm-standard check: meets the standard; ratchet: within the baseline (shrunk only).

Follow-up filed: NAPALM/napalm-device-types#85 (PackageDict lacks source_package, source_version, upgrade_version; get_packages casts until then).

Release 0.9.0 after merge, then the netOrk side (NetOrk/netork#1919).

Closes #52. Part of NetOrk/netork#1918 (Proxmox Backup Server support). ## What A second driver in this package: `proxmox_backup = "napalm_proxmox:ProxmoxBackupDriver"`. **API and web UI on 8007**, node always `localhost`. Roles: `BackupServerDriver` (napalm-device-types 4.25.0, already on PyPI) first, `StorageDriver` second. Two commits: 1. **refactor** — what both products share moves out of `ProxmoxDriver`: `_base.py` (connection with proxmoxer `service` PVE/PBS and its port, token split, SSH session, `run_command`, node helpers, DMI) and `host_mixin.py` (packages, APT updates, subscription, reboot/shutdown via API, root file writes, the host readers' transports). The PVE driver behaves as before: `tests/test_connection_args.py` pins what it hands proxmoxer; it now names `service="PVE"` explicitly. `get_packages` is split; PVE's `get_facts` and `get_packages` leave the quality baseline. This commit is green on its own (538 tests, ratchet). 2. **feat** — `backup_driver.py`, `pbs_backups.py` (datastores, groups, snapshots, jobs, remotes, actions, tasks) and `pbs_host.py` (facts, interfaces, environment, disks, ZFS pools). ## Found on the real server (PBS 4.2) - A privilege-separated token **without an ACL entry gets `[]`**, not 403, for datastores and jobs — and `Audit` on `/` does not include `Remote.Audit` (four remotes listed as `[]`). Every read checks `/access/permissions` first and raises `PermissionError`. - A **removable datastore that is not mounted** answers 400 for its content. It is reported as `maintenance: "unmounted"` and left out of `get_backup_groups()`; asked for by name it raises `ValueError`. - `disks/list` runs smartctl and can outlast proxmoxer's default 5 s timeout. - The API carries no MAC address for an interface; it is read over SSH (and stays empty without it). ## Fixtures `tests/fixtures/pbs_api.json` is what the server answered, sanitised (addresses, domain, serials, server id, UUIDs, certificate fingerprint, guest name replaced; the sanitiser refuses to write a recorded error as an answer). Groups, snapshots and jobs it did not have yet follow the PBS API schema (`pbs.proxmox.com/docs/api-viewer`), marked as such in the tests. ## Checks - `pytest`: 599 passed; coverage 82 % (floor 68), new modules 98–100 %. - `ruff format --check`, `ruff check`: clean. `mypy --strict` on the new modules: clean. - `napalm-standard check`: meets the standard; `ratchet`: within the baseline (shrunk only). Follow-up filed: NAPALM/napalm-device-types#85 (`PackageDict` lacks `source_package`, `source_version`, `upgrade_version`; `get_packages` casts until then). Release 0.9.0 after merge, then the netOrk side (NetOrk/netork#1919).
christianmanivong added the
prio
P2
enhancement
labels 2026-11-02 21:29:41 +00:00
christianmanivong added 2 commits 2026-11-02 21:29:41 +00:00
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.
feat(pbs): Proxmox Backup Server as entry point proxmox_backup (#52)
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
2b2cd9b867
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.
christianmanivong merged commit c040dfdaa2 into main 2026-11-02 21:35:53 +00:00
christianmanivong deleted branch feat/proxmox-backup 2026-11-02 21:35:53 +00:00
Sign in to join this conversation.