Proxmox Backup Server: second entry point proxmox_backup (API on :8007) on a base shared with PVE #52

Closed
opened 2026-11-02 19:11:21 +00:00 by christianmanivong · 0 comments
Owner

Part of NetOrk/netork#1918 (Proxmox Backup Server support). Priority: P2 (important and urgent). Needs NAPALM/napalm-device-types#82 released first.

What

A second driver in this package: ProxmoxBackupDriver, entry point proxmox_backup, for Proxmox Backup Server. The web UI and API are on :8007, not :8006. The PVE driver proxmox keeps its name and behaviour.

[project.entry-points."napalm.drivers"]
proxmox = "napalm_proxmox:ProxmoxDriver"
proxmox_backup = "napalm_proxmox:ProxmoxBackupDriver"

Bases: BackupServerDriver, StorageDriver (in that order), plus the OS mixins the PVE driver already uses where they hold for a PBS host: KernelFactsMixin, ServicePackagesMixin, ListeningSocketsMixin, SystemIdentityMixin, SystemdServicesMixin, HostStatusMixin, LicenseMixin, SnmpAgentMixin, EnsurePackageMixin, AptProxyMixin, OpenSshServerMixin. FULL_UPGRADE = True.

Steps

  1. Pin PVE first. Tests for what the shared part does today (connect with password and with user@realm!token, bare username gets the realm, SSH only with the given credentials, apt update list, services). They stay green through step 2.
  2. Extract the common base (e.g. napalm_proxmox/_base.py): proxmoxer with service="PVE" | "PBS", port default per service (8006 / 8007), token split (user@realm!name), _node_api(), _node_ssh(), _exec_ssh_command(), run_command, apt-update and services API calls. ProxmoxDriver keeps _resolve_node() via /cluster/status; the PBS driver's node is always localhost.
  3. PBS reads: facts (/version, /nodes/localhost/status), interfaces (/nodes/localhost/network, same shape as PVE), disks (disks/list, disks/smart) and ZFS pools (disks/zfs) for the storage role, datastores (/config/datastore + /status/datastore-usage + /admin/gc), groups (/admin/datastore/{store}/groups per namespace, newest snapshot's verify state from snapshots), jobs (/admin/{verify,prune,sync}, /admin/gc, /tape/backup), remotes (/config/remote), updates (apt/update), repositories (apt/repositories), subscription (/nodes/localhost/subscription → get_licenses, name pbs-subscription), NTP (time).
  4. PBS actions: GC, run verify/prune/sync job, snapshot verify / protect / delete, services, reboot/shutdown (POST /nodes/localhost/status), full upgrade over SSH as for PVE.
  5. Fingerprints: PORT_SPECS = [PortSpec("https", 8007, …)], HTTP_FINGERPRINT with proxmox backup server mandatory, SSH_FINGERPRINT debian.
  6. PVE side for the link: get_clusters() fills ClusterStorageDict.backup_server for pbs storages from /storage (server, port, datastore, namespace, fingerprint).

Token permissions (README)

  • Read: role Audit on / (Sys.Audit, Datastore.Audit). With privilege separation, the token needs its own ACL entry.
  • Actions: DatastoreAdmin on /datastore (GC, verify, prune, protect, delete), Sys.Modify / Sys.PowerManagement on /system (services, reboot). Updates, kernel facts, listening sockets and sshd go over SSH as root, as on PVE.

Test-First

  • Recorded API responses from a real PBS (sanitised: no hostnames, IPs, fingerprints, serials) as fixtures; parsers only see plain dicts.
  • Token root@pam!netork → proxmoxer gets user="root@pam", token_name="netork", service="PBS", port 8007 unless port is given.
  • A datastore without estimated-full-date → estimated_full=None, not 0; an S3 datastore reports backend="s3".
  • A group whose newest snapshot has no verification → verify state None; "failed" → "failed".
  • A job that never ran → last_run=None, last_state=None.
  • A failed read raises; it does not return an empty list (the "failed read returns empty" class of bug found in the driver-standard rollout).
  • roles_of(ProxmoxBackupDriver) → backup, storage; the entry point resolves.
  • Every PVE test from step 1 still green.

Release: minor bump (0.9.0), CHANGELOG, tag, PyPI.

Part of NetOrk/netork#1918 (Proxmox Backup Server support). Priority: P2 (important and urgent). Needs NAPALM/napalm-device-types#82 released first. ## What A second driver in this package: `ProxmoxBackupDriver`, entry point `proxmox_backup`, for Proxmox Backup Server. **The web UI and API are on :8007, not :8006.** The PVE driver `proxmox` keeps its name and behaviour. ```toml [project.entry-points."napalm.drivers"] proxmox = "napalm_proxmox:ProxmoxDriver" proxmox_backup = "napalm_proxmox:ProxmoxBackupDriver" ``` Bases: `BackupServerDriver, StorageDriver` (in that order), plus the OS mixins the PVE driver already uses where they hold for a PBS host: `KernelFactsMixin`, `ServicePackagesMixin`, `ListeningSocketsMixin`, `SystemIdentityMixin`, `SystemdServicesMixin`, `HostStatusMixin`, `LicenseMixin`, `SnmpAgentMixin`, `EnsurePackageMixin`, `AptProxyMixin`, `OpenSshServerMixin`. `FULL_UPGRADE = True`. ## Steps 1. **Pin PVE first.** Tests for what the shared part does today (connect with password and with `user@realm!token`, bare username gets the realm, SSH only with the given credentials, apt update list, services). They stay green through step 2. 2. **Extract the common base** (e.g. `napalm_proxmox/_base.py`): proxmoxer with `service="PVE" | "PBS"`, port default per service (8006 / 8007), token split (`user@realm!name`), `_node_api()`, `_node_ssh()`, `_exec_ssh_command()`, `run_command`, apt-update and services API calls. `ProxmoxDriver` keeps `_resolve_node()` via `/cluster/status`; the PBS driver's node is always `localhost`. 3. **PBS reads:** facts (`/version`, `/nodes/localhost/status`), interfaces (`/nodes/localhost/network`, same shape as PVE), disks (`disks/list`, `disks/smart`) and ZFS pools (`disks/zfs`) for the storage role, datastores (`/config/datastore` + `/status/datastore-usage` + `/admin/gc`), groups (`/admin/datastore/{store}/groups` per namespace, newest snapshot's verify state from `snapshots`), jobs (`/admin/{verify,prune,sync}`, `/admin/gc`, `/tape/backup`), remotes (`/config/remote`), updates (`apt/update`), repositories (`apt/repositories`), subscription (`/nodes/localhost/subscription` → `get_licenses`, name `pbs-subscription`), NTP (`time`). 4. **PBS actions:** GC, run verify/prune/sync job, snapshot verify / protect / delete, services, reboot/shutdown (`POST /nodes/localhost/status`), full upgrade over SSH as for PVE. 5. **Fingerprints:** `PORT_SPECS = [PortSpec("https", 8007, …)]`, `HTTP_FINGERPRINT` with `proxmox backup server` mandatory, `SSH_FINGERPRINT` debian. 6. **PVE side for the link:** `get_clusters()` fills `ClusterStorageDict.backup_server` for `pbs` storages from `/storage` (server, port, datastore, namespace, fingerprint). ## Token permissions (README) - Read: role `Audit` on `/` (Sys.Audit, Datastore.Audit). With privilege separation, the token needs its own ACL entry. - Actions: `DatastoreAdmin` on `/datastore` (GC, verify, prune, protect, delete), `Sys.Modify` / `Sys.PowerManagement` on `/system` (services, reboot). Updates, kernel facts, listening sockets and sshd go over SSH as root, as on PVE. ## Test-First - [ ] Recorded API responses from a real PBS (sanitised: no hostnames, IPs, fingerprints, serials) as fixtures; parsers only see plain dicts. - [ ] Token `root@pam!netork` → proxmoxer gets `user="root@pam"`, `token_name="netork"`, `service="PBS"`, port 8007 unless `port` is given. - [ ] A datastore without `estimated-full-date` → `estimated_full=None`, not 0; an S3 datastore reports `backend="s3"`. - [ ] A group whose newest snapshot has no `verification` → verify state `None`; `"failed"` → `"failed"`. - [ ] A job that never ran → `last_run=None`, `last_state=None`. - [ ] A failed read raises; it does not return an empty list (the "failed read returns empty" class of bug found in the driver-standard rollout). - [ ] `roles_of(ProxmoxBackupDriver)` → backup, storage; the entry point resolves. - [ ] Every PVE test from step 1 still green. Release: minor bump (0.9.0), CHANGELOG, tag, PyPI.
christianmanivong added the
prio
P2
enhancement
labels 2026-11-02 19:11:21 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: NAPALM/napalm-proxmox#52