# napalm-proxmox [NAPALM](https://napalm.readthedocs.io/) drivers for [Proxmox VE](https://www.proxmox.com/en/proxmox-virtual-environment/overview) nodes (`proxmox`) and for [Proxmox Backup Server](https://www.proxmox.com/en/proxmox-backup-server/overview) (`proxmox_backup`). The Proxmox VE driver is described first; the backup server's is [below](#proxmox-backup-server). It supports all three networking domains of Proxmox VE: | Domain | Description | |--------|-------------| | **Classic Linux** | `/etc/network/interfaces`, Linux bridges, VLANs | | **SDN** | Zones (VLAN, QinQ, VXLAN, EVPN), VNets, subnets | | **OVS** | Open vSwitch bridges, bonds, and internal ports | ## Requirements - Python ≥ 3.12 - NAPALM ≥ 5.0.0 - napalm-device-types ≥ 4.22.0 - proxmoxer ≥ 2.0.0 - netaddr ≥ 0.9.0 - requests ≥ 2.31.0 ## Installation ```bash pip install napalm-proxmox ``` Or directly from source: ```bash git clone https://git.netork.io/NAPALM/napalm-proxmox.git cd napalm-proxmox pip install -e . ``` ## Usage ### Password authentication ```python from napalm import get_network_driver driver = get_network_driver("proxmox") device = driver( hostname="pve1.example.com", username="root", password="secret", optional_args={ "realm": "pam", # default: "pam" "port": 8006, # default: 8006 "verify_ssl": True, # default: True }, ) with device: facts = device.get_facts() print(facts) # {'vendor': 'Proxmox Server Solutions GmbH', 'model': 'PowerEdge R640', # 'hostname': 'pve1', 'os_version': 'Proxmox VE 8.2.4', ...} interfaces = device.get_interfaces() interfaces_ip = device.get_interfaces_ip() vlans = device.get_vlans() network_instances = device.get_network_instances() ``` ### API token authentication ```python device = driver( hostname="pve1.example.com", username="napalm", password="", optional_args={ "token_name": "napalm@pam!napalm-token", "token_value": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", }, ) ``` ### Targeting a specific node In a multi-node cluster the driver auto-detects the node by matching the hostname against the cluster's node list. You can also pin a specific node: ```python device = driver( hostname="pve-cluster.example.com", # cluster VIP username="root", password="secret", optional_args={"node": "pve2"}, ) ``` ## Supported NAPALM methods | Method | Notes | |--------|-------| | `open` / `close` | Password + API token auth | | `is_alive` | Checks `/api2/json/version` | | `get_facts` | vendor, model, hostname, os_version, uptime, interface_list, fqdn | | `get_interfaces` | eth, bridge, OVS bridge/bond; speed, MTU, MAC, status | | `get_interfaces_ip` | IPv4/IPv6 from classic ifaces + SDN subnet gateways | | `get_interfaces_counters` | From `node/netstat` RRD data | | `get_environment` | CPU %, memory (bytes), hardware temperature sensors | | `get_arp_table` | Reads `/proc/net/arp` over SSH | | `get_mac_address_table` | `bridge fdb show` (Linux) + `ovs-appctl fdb/show` (OVS) | | `get_vlans` | SDN VNet tags + `bridge vlan show` | | `get_network_instances` | SDN zones (VLAN→L2VPN, EVPN→L3VRF) + default instance | | `get_ntp_servers` | chrony's configured sources, as `get_time_sync` reads them | | `get_ntp_stats` | Parses `chronyc` / `ntpq -pn` output | | `get_snmp_information` | Parses `/etc/snmp/snmpd.conf` | | `get_users` | Proxmox access/users API + local `/etc/passwd` | | `get_config` | `/etc/network/interfaces` + SDN config; sanitize support | | `load_merge_candidate` / `load_replace_candidate` | String or file | | `compare_config` | Unified diff | | `commit_config` | Writes `/etc/network/interfaces` + `ifreload -a` | | `discard_config` / `rollback` | Revert candidate | | `get_lldp_neighbors` | `lldpctl -f keyvalue` over SSH (napalm-device-types' parser); raises when lldpctl fails | | `get_lldp_neighbors_detail` | Full LLDP detail, capabilities in NAPALM's names | | `get_ipv6_neighbors_table` | `ip -6 neigh show` | | `ping` | Linux `ping` over SSH | | `traceroute` | `traceroute -n` over SSH | | `cli` | Arbitrary commands over SSH (stdout) | | `get_route_to` | `ip route show` over SSH | | `get_scheduled_jobs` | cron, `/etc/cron.d`, user crontabs, run-parts, anacron, systemd timers, as root over SSH (napalm-device-types' `PosixScheduledJobsMixin`); `pve-*` units, `pvesr.timer` and `/etc/cron.d/vzdump` are `platform` | | `manage_scheduled_job(key, action, digest=)` | enable, disable, run now; a `/etc/cron.d/vzdump` line only runs | | `put_scheduled_job(spec)` / `delete_scheduled_job(key, digest=)` | an application's own job, as a systemd timer | | `get_time_sync` | chrony's sources and whether it is synchronised, the zone from `timedatectl`, in one round trip over SSH (napalm-device-types' `PosixTimeSyncMixin`); the zone from `GET /nodes/{node}/time` only where the host names none | | `configure_time_sync(ntp_servers=, timezone=)` | servers to `/etc/chrony/sources.d/netork.sources`, every other source commented out, then a reload or a restart of chrony; the zone through `PUT /nodes/{node}/time` (the token needs `Sys.Modify` on `/nodes/{node}`), so `/etc/timezone` and the web UI follow. Only this node: in a cluster each node keeps its own clock | **Not implemented** (raise `NotImplementedError`): `get_bgp_config`, `get_bgp_neighbors`, `get_bgp_neighbors_detail`, `get_optics`, `get_probes_config`, `get_probes_results`, `get_firewall_policies` ## Optional arguments | Argument | Type | Default | Description | |----------|------|---------|-------------| | `port` | int | `8006` | Proxmox API port | | `verify_ssl` | bool | `True` | Verify TLS certificate | | `realm` | str | `"pam"` | PAM realm for password auth | | `node` | str | *auto* | Override target node name | | `token_name` | str | `None` | API token identifier (`user@realm!tokenid`) | | `token_value` | str | `None` | API token secret | | `ssh_username` | str | *username* | Login for the node's SSH (port 22) | | `ssh_password` | str | *password* | SSH password; the API password when not set | | `ssh_private_key_str` | str | `None` | SSH private key (Ed25519, ECDSA or RSA), tried before the password | What the API does not offer (ARP, LLDP, packages, SNMP config, `cli`, …) runs in the node's shell over SSH. Without an SSH password or key — a node reached with an API token only — those calls raise `ConnectionException` instead of reading as empty. ## Proxmox Backup Server ```python driver = get_network_driver("proxmox_backup") device = driver( hostname="pbs1.example.com", username="", password="", optional_args={ "token_name": "root@pam!monitoring", "token_value": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "ssh_private_key_str": open("id_ed25519").read(), # optional, see below }, ) ``` **The API and web UI listen on 8007**, not on Proxmox VE's 8006; `port` defaults to 8007 here. The node is always `localhost`: a backup server has no cluster. The optional arguments are the ones above, except `node`. Roles (napalm-device-types): `BackupServerDriver` first, `StorageDriver` second for the disks and ZFS pools the server manages itself. | Method | Source | |--------|--------| | `get_backup_datastores` | `/config/datastore` + `/status/datastore-usage`: usage, estimated full date, backend (`local`, `s3`, `removable`), maintenance or `unmounted` | | `get_backup_groups` / `get_backup_snapshots` | `/admin/datastore/{store}/{namespace,groups,snapshots}`, every namespace; a group carries its newest snapshot with its verify state | | `get_backup_jobs` | `/admin/{gc,verify,prune,sync}`, `/tape/backup`, with the state of the last run | | `get_backup_remotes` | `/config/remote`, without secrets | | `start_garbage_collection`, `run_backup_job`, `verify_backup_snapshot` | start a task; `get_backup_task` follows it | | `set_backup_snapshot_protected`, `delete_backup_snapshot` | on one snapshot | | `get_facts`, `get_interfaces`, `get_interfaces_ip`, `get_environment` | the API; host name, DMI and MAC addresses over SSH | | `get_disks`, `get_disk_pools` | `/nodes/localhost/disks/{list,zfs}` | | `get_licenses` | `pbs-subscription` | | packages, updates, services, kernel, listening sockets, sshd hardening, `reboot_host`, `shutdown_host` | as on Proxmox VE | | scheduled jobs | as on Proxmox VE; `proxmox-backup*` units are `platform`. Verify, prune, sync and GC jobs are `get_backup_jobs`, not scheduled jobs | | `get_time_sync`, `configure_time_sync`, `get_ntp_servers` | as on Proxmox VE, the zone through `/nodes/localhost/time` (writing it needs `Sys.Modify` on `/system/time`) | **API token rights.** Reading needs the role `Audit` on `/` (`Sys.Audit`, `Datastore.Audit`); the remotes need `Remote.Audit` on `/remote` as well, which `Audit` does not include. A privilege-separated token needs an ACL entry of its own: ```bash proxmox-backup-manager acl update / Audit --auth-id 'root@pam!monitoring' ``` Without it PBS does not refuse a listing, it answers with an empty one. The driver therefore checks `/access/permissions` before every read and raises `PermissionError`, so a token without rights does not read as a server without backups. The actions need `DatastoreAdmin` on `/datastore` (GC, verify, prune, protect, delete) and `Sys.Modify` / `Sys.PowerManagement` on `/system` (services, reboot). A removable datastore that is not mounted is reported as `maintenance: "unmounted"` and left out of `get_backup_groups()`; asked for by name, it raises `ValueError`. ## Development ```bash python3 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" # Run tests with coverage pytest --cov=napalm_proxmox --cov-report=term-missing # Lint ruff check napalm_proxmox ``` ## Architecture ``` napalm_proxmox/ ├── __init__.py # Exports ProxmoxDriver and ProxmoxBackupDriver ├── _base.py # What both share: connection, token split, SSH session, node helpers ├── host_mixin.py # Both as Debian hosts: apt, packages, subscription, host readers' transports ├── driver.py # ProxmoxDriver (proxmox) ├── backup_driver.py # ProxmoxBackupDriver (proxmox_backup) ├── pbs_backups.py # The backup-server role: datastores, groups, jobs, remotes, actions ├── pbs_host.py # The backup server as a host: facts, interfaces, disks, ZFS pools └── utils.py # MAC normalisation, CIDR parsing, ARP/OVS parsers tests/ ├── conftest.py # Shared fixtures and mock API payloads ├── test_connection.py # open / close / is_alive ├── test_get_facts.py # get_facts ├── test_interfaces.py # get_interfaces, get_interfaces_ip, get_interfaces_counters ├── test_environment.py # get_environment ├── test_sdn.py # get_vlans, get_network_instances ├── test_ovs_and_arp.py # get_arp_table, get_mac_address_table, ARP/OVS utils ├── test_misc.py # NTP statistics, SNMP, users, config, ping, traceroute, CLI, LLDP ├── test_time_sync.py # get_time_sync / configure_time_sync on both drivers ├── test_utils.py # Unit tests for napalm_proxmox.utils ├── fixtures/pbs_api.json # What a Proxmox Backup Server 4.2 answered (sanitised) ├── pbs_fake.py # A proxmoxer stand-in answering from that recording └── test_pbs_*.py # The backup server driver ``` ## License Apache License 2.0 — see [LICENSE](LICENSE).