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
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.
258 lines
11 KiB
Markdown
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).
|