Branch master was renamed to main.
christianmanivong 449230c624
driver / standard (push) Successful in 16s
driver / lint (push) Successful in 14s
driver / types (push) Successful in 56s
driver / test (3.12) (push) Successful in 1m5s
driver / lowest (push) Successful in 28s
driver / test (3.13) (push) Successful in 54s
driver / build (push) Successful in 24s
driver / security (push) Successful in 52s
CI / driver (push) Successful in 2m28s
driver / publish (push) Skipped
Merge pull request 'feat(zabbix): a native Zabbix agent on both drivers through ZabbixAgentMixin (NetOrk/netork#2571)' (#69) from feat/zabbix-agent-native into main
2026-11-17 04:32:23 +00:00
2026-05-29 09:24:39 +02:00
2026-05-29 09:24:39 +02:00

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.

S
Description
No description provided
Readme
1.2 MiB
0 Stars 1 Watchers 0 Forks
2026-11-03 04:24:56 +00:00
Languages
Python 100%