Files
napalm-proxmox/README.md
T
Christian Manivong 410d34bdee
driver / standard (pull_request) Successful in 14s
driver / lint (pull_request) Successful in 14s
driver / types (pull_request) Successful in 56s
driver / test (3.12) (pull_request) Successful in 1m2s
driver / test (3.13) (pull_request) Successful in 59s
driver / lowest (pull_request) Successful in 32s
driver / build (pull_request) Successful in 31s
driver / security (pull_request) Successful in 1m11s
CI / driver (pull_request) Successful in 2m41s
driver / publish (pull_request) Skipped
feat(time-sync): servers and zone on Proxmox VE and Backup Server
netOrk keeps one list of NTP servers and a time zone per site and aligns
a device that differs (NetOrk/netork#2360, #2365). Both drivers now
implement napalm-device-types' TimeSyncMixin (4.35.0) and write both
values.

Neither API keeps time servers: /nodes/{node}/time knows only the zone,
and both products run chrony on Debian. The servers are therefore
PosixTimeSyncMixin's, over the driver's existing SSH session
(run_command, root): read from chrony's configuration, written to
/etc/chrony/sources.d/netork.sources with every other source commented
out, then a reload or a restart of chrony.

The zone is read with them from the host (timedatectl: the zone the
clock really runs in), and from GET /nodes/{node}/time only where the
host names none. It is written through PUT /nodes/{node}/time rather
than timedatectl set-timezone: Proxmox's own call validates the name and
keeps /etc/timezone, which its web UI and API show, in step with
/etc/localtime.

One device is one node: in a PVE cluster every node has its own clock,
and only the node this connection resolved is read and written.

get_ntp_servers() read GET /nodes/{node}/ntp, a path Proxmox VE does not
have, so it always reported no servers. It now reports what
get_time_sync() reads, on the backup server too.
2026-11-11 15:18:08 +01:00

258 lines
11 KiB
Markdown

# 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).