napalm-proxmox
NAPALM drivers for Proxmox VE nodes
(proxmox) and for Proxmox Backup Server (proxmox_backup).
The Proxmox VE driver is described first; the backup server's is
below.
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
pip install napalm-proxmox
Or directly from source:
git clone https://git.netork.io/NAPALM/napalm-proxmox.git
cd napalm-proxmox
pip install -e .
Usage
Password authentication
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
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:
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, the ones DHCP gave apart (dhcp_ntp_servers), 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 configured source commented out (DHCP's sourcedir stays), 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
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:
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
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.