# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] ### Changed - The floor on napalm-device-types is 4.23.0, the first release with what this driver uses. - Python 3.12 is the floor (`requires-python = ">=3.12"`): netOrk runs every driver on 3.12, so 3.10 and 3.11 are no longer tested (NAPALM/driver-standard#6). ### Added - `get_clusters()` reports quorum `votes` per node (`/cluster/config/nodes`), the guests HA manages in `ha_resources` (`/cluster/ha/resources`, the CRM state and node from `/cluster/ha/status/current`, the ids of the PVE 9 HA rules that name each from `/cluster/ha/rules`, `[]` on PVE 8), the vzdump jobs in `backup_jobs` (`/cluster/backup`; a pool job lists the pool's guests from `/pools?poolid=`, or `/pools/{pool}` before PVE 8.1; old `starttime`/`dow` jobs get the schedule PVE itself derives) and per guest and storage the newest backup in `backups` (each storage with backup content read once if shared, on each node if local; PBS included). Each is best-effort: one that cannot be read is None and the rest of the report stands. - `get_vm_migration_preflight(name)`: a VM's nodes and blockers from `GET .../qemu/{vmid}/migrate` in plain words, a local ISO in a CD drive as a blocking resource, the cloud-init drive left out; a container's candidates are the online members, its local volumes and unshared bind mounts read from its config. An offline member is refused as `"node offline"` for both. - `migrate_vm(name, target_node, online=True, target_storage=None, timeout=3600)`: `POST .../{qemu|lxc}/{vmid}/migrate` (`online` for a running VM, `with-local-disks` when it has local disks, restart mode for a running container), followed to the end; a failure raises with the task log's `ERROR:` lines. A target that is not another cluster member is refused before the API is called. A guest HA manages is followed through the HA manager until it is on the target. - `set_node_maintenance(node, enabled)`: `ha-manager crm-command node-maintenance` over the driver's SSH session, for a cluster member only and quoted; raises RuntimeError when SSH is not available. Needs the shapes and contracts of the next napalm-device-types release for type checking (runtime imports none). - `get_clusters()`: the cluster the node belongs to, always exactly one, read from `/cluster/status`, `/cluster/resources`, each online node's status and network, SDN vnets/zones and the HA manager. Every member is listed, an offline one with `status` `"offline"` and no capacity; `maintenance` is None when the HA manager cannot be read. Storages are grouped by name with the nodes they are available on (size: one node's figure for a shared storage, the sum over its nodes for a local one); bridges are merged across nodes, VLAN aware only if they are on every node; a vnet is on its zone's nodes. A standalone node is a cluster of one without a name. `create_vm_from_cloud_init()` takes `node` and raises ValueError, before creating anything, for a node other than its own (NetOrk/netork#484, NetOrk/netork#1822). Needs the cluster models and `get_clusters()` contract of napalm-device-types. - `get_network_targets()` names each bridge's physical NICs in `uplinks`, read from `bridge_ports`/`ovs_ports`, one group per bridge port: a bond's slaves together, a NIC alone, without internal ports (`OVSIntPort`) and VLAN subinterfaces. Left out when a port is missing from the node's network config or of a kind it cannot place (NetOrk/netork#1325). Needs the `uplinks` field of napalm-device-types' `NetworkTargetDict`. - `shutdown_host()`: the node shuts itself down through the API (`POST /nodes/{node}/status command=shutdown`), and `begin_stop_vm(name)`: a guest's clean shutdown, returning once Proxmox took it instead of waiting for the task — the contracts `HostShutdownMixin` and `VmStopRequestMixin` of napalm-device-types (NetOrk/netork#1636). ### Fixed - `get_ipv6_neighbors_table()` reports an unknown age as `-1.0`, as `get_arp_table()` already did (napalm-device-types' `ARP_AGE_UNKNOWN`), instead of `0.0`, which means "confirmed just now" (NetOrk/netork#1327). - `set_vlan()` finds the node's switch uplink again. Since 0.8.0 every call failed with "no LLDP-detected switch uplink found", whatever LLDP reported (#37). - `configure_snmp_agent()` completes: its "configure" step reported a failure with empty output although `/etc/snmp/snmpd.conf` was written, so the firewall and start steps never ran (#30). - `create_vm_from_cloud_init(ssh_public_keys=...)` installs every key, one per line, instead of only the first; a key containing `/` or `+` is no longer refused by Proxmox (#23). - `get_lldp_neighbors()` lists every neighbour of a port: a second neighbour on the same port no longer overwrites the first, and a neighbour that sends no system name is listed with an empty `hostname` instead of being dropped (#22). - `set_hostname()` renames only the node's own names in `/etc/hosts`: other hosts whose names start with the old one (`pve-backup`) and comments stay as they are, and the old FQDN becomes the new one instead of a mix of both (#21). - `set_hostname()` refuses a node that is part of a cluster (a `/etc/pve/corosync.conf` or `/etc/corosync/corosync.conf` exists) with a `CommandErrorException`, before changing anything: it moved `/etc/pve/nodes/` while the cluster still knew the node as ``. Also refused when the check cannot be read. A single node renames as before (#21). - `apply_updates()` reports a failed upgrade as `success: False`, with apt-get's exit status in `error`; it reported success whatever apt-get did (#20). - `get_users()` lists the node's root and regular login accounts (uid 1000 and up) instead of its system accounts (`daemon`, `bin`, …), and gives a Proxmox user level 15 when the ACL grants it the Administrator role on `/`, directly or through a group; `root@pam` is always 15. Before, practically every Proxmox user was level 1 (#19). - `get_ntp_stats()` reports chrony's sources, Proxmox VE's default, instead of always returning an empty list: offset in ms, the poll interval in seconds, the offset's standard deviation as `jitter`; chrony reports no delay, so `delay` is 0.0. On ntpd, a peer without tally mark is no longer dropped (#18). - The SSH login to the node takes an Ed25519 or ECDSA key in `ssh_private_key_str`, not only RSA, and uses the key even when a password is set too (the password stays the fallback). A key that cannot be read is logged as a warning and the password used (#17). - `destroy_vm()` returns once Proxmox has deleted the VM, not as soon as the delete was queued, and raises when the delete fails (#15). - `ping()` fills `results` with each reply's address and round-trip time; it was always empty (#12). - A failed cloud-image download in `create_vm_from_cloud_init()` says why (wget's own message, such as "No space left on device") and removes its partial `.tmp` file instead of leaving it to fill the node's disk (#3). - A `create_vm_from_cloud_init()` that fails once the VM shell exists (disk import, storage, NIC or snippet configuration, start) raises `VMProvisionIncomplete`, a `RuntimeError` with the VMID and node of the VM it left behind and the failure as its cause, so the caller can remove it with `destroy_vm()`. Failures there that were a `ValueError` (no snippet storage, a NIC without a bridge) are its cause now. Needs `VMProvisionIncomplete` from napalm-device-types (#28). - `create_vm_from_cloud_init()` quotes the image URL and every path built from it in the commands it runs as root on the node (download, checksum, unpack, disk import). A URL with a quote, `$(…)`, `;` or a space no longer reaches the shell: the node's cache file name keeps only the characters Proxmox keeps in a file name, the others become `_`. A checksum algorithm other than md5, sha1, sha224, sha256, sha384 or sha512 is refused with a `ValueError` before anything runs on the node (#43). - Commands on the node (ARP, IPv6 neighbours, packages, users, NTP, SNMP config, services, kernel facts, `cli()`, …) raise `ConnectionException` when they cannot run: no SSH password or key (a node reached with an API token only), a refused login, an unreachable node, a timeout; a changed host key raises `SshHostKeyMismatch` as before. They returned empty output, so "could not look" read as "nothing there": `get_snmp_config()` answered None on token-only nodes and the getters empty lists. Only what a command prints on stdout is its output; stderr no longer stands in when stdout is empty. Each command goes straight to SSH: the driver first posted it to `/nodes/{node}/execute`, which runs API calls, not a shell, and always failed (#17). - The SSH login to the node uses only the credentials it is given (`ssh_private_key_str`, `ssh_password` or the API password): paramiko no longer also tries the keys in the running process's `~/.ssh` or an SSH agent it can reach (#48). - `create_vm_from_cloud_init()` quotes the snippet storage's path and the snippet's file name in the command that writes the cloud-init snippets as root on the node, and refuses a snippet name that is not one plain file name (#47). ## [0.8.0] - 2026-10-23 The first release on PyPI. It collects everything since 0.1.0. ### Changed - The driver follows the NAPALM driver standard (https://git.netork.io/NAPALM/driver-standard): CI on Gitea runs ruff, mypy, the tests on Python 3.10–3.13 and at the lowest declared versions, bandit, pip-audit and a build check, and a release tag publishes to PyPI. The package now ships `py.typed`. **Python 3.9 is no longer supported**; napalm-device-types never ran on it. - Exceptions the driver deliberately ignores (closing the node's SSH session, the `is_alive()` probe) are now logged at debug level. - The project links point at git.netork.io. ### Added - apt's proxy (napalm-device-types' `AptProxyMixin`, NetOrk/netork#1397): `get_package_proxy()`, `get_package_proxy_report()`, `check_package_proxy(url, expect)` and the fix `configure_package_proxy(url)`, as on any Debian host. The node is logged in as root, so the file is written and other proxy lines are commented out over the exec path. Requires napalm-device-types 4.22.0; version 0.7.0. - `get_service_packages()` (napalm-device-types' `ServicePackagesMixin`, NetOrk/netork#1236): which installed packages each systemd unit of the node is made of — the one shipping its unit file and the one shipping its `ExecStart` binary. Read-only, over the exec path. Requires napalm-device-types 4.20.0; version 0.6.0. ### Security - The node's SSH session (the fallback for node commands and the provisioning steps) verifies its host key (NetOrk/netork#1167): the key the caller expects for port 22 in `optional_args["ssh_host_keys"]`, else the first one; every key seen goes to `optional_args["ssh_host_key_observer"]`. A changed key is refused before any login: a provisioning step fails, a best-effort read returns nothing. Both paths now share one session (`_node_ssh`). Replaces paramiko's `AutoAddPolicy`. Requires napalm-device-types 4.19.0; version 0.5.0. ### Changed - **Breaking:** `get_device_warnings` is gone; the node reports facts and the caller names the warnings (netOrk #1111). lldpd and the pending updates were already facts (`get_packages`, `get_available_updates`). The subscription is now `get_licenses()` (napalm-device-types 4.14 `LicenseMixin`): one `pve-subscription` entry with the API's status as a `LicenseStatus` (`notfound` → `none`, `new` and `suspended` → `unknown`), its message as `detail`, product name and due date when subscribed. The old check compared against `NotFound` while the API answers `notfound`, so it never fired. Requires napalm-device-types 4.14.0; version 0.4.0. - **Breaking:** `run_device_action` (`fix_snmp`, `install_lldpd`) is gone. The driver implements napalm-device-types 4.13's fix templates: `configure_snmp_agent(settings)` with the caller's community and allowed sources (one `rocommunity` line each, ufw only for those sources, no fixed temp file), `get_management_peer()`, and `install_package(name)` as the contract says, so `ensure_package` comes from the base package. Every step reads its exit status. Requires napalm-device-types 4.13.0; version 0.3.0. ### Added - `get_system_identity()` (napalm-device-types 4.9 `SystemIdentityMixin`): the node's SMBIOS system UUID, product serial and board serial over the exec path, vendor placeholders empty. netOrk matches a server to its BMC on these. Requires napalm-device-types 4.9.0; version 0.2.0. - FreeBSD and OpenBSD guests: `create_vm_from_cloud_init(guest_os=...)` with `GUEST_AGENTS` from napalm-device-types 3.0. A BSD guest gets OS type `other` and a network-config v2 snippet of its own (`cicustom network=`), because FreeBSD's nuageinit skips runcmd on the v1 Proxmox generates. OpenBSD's agent runs over ISA serial behind `serial0`, as the image keeps its console on com0. An unknown `guest_os` is refused before anything is created. - Packed cloud images (FreeBSD's `.qcow2.xz`) are unpacked on the node after the packed file's checksum is verified; only the unpacked file is cached. Proxmox's `download-url` unpacks ISOs only, so they always go over SSH. ### Fixed - `get_vm_status` no longer reports a loopback address as the VM's IP when the agent lists loopback under another name than `lo` (`lo0` on the BSDs, listed first by OpenBSD). - `destroy_vm` reads the VM's cloud-init snippets before deleting the VM, and removes all of them; it read them afterwards, when the config was gone (#15). - Cloud images for `create_vm_from_cloud_init` are downloaded by Proxmox itself when the node has an active storage with content type `import` (Proxmox 8.2+): `download-url` with checksum verification, then `import-from` as the root disk. The image no longer passes through the node's root filesystem. Files are named `netork--.` and reused; Ubuntu's `.img` is stored as `.qcow2`. Without such a storage, or for an image type Proxmox cannot import, the SSH download into `/var/lib/vz/template/netork-images` is used as before. - `HypervisorDriver` contract methods `start_vm`, `stop_vm`, `reboot_vm`, `suspend_vm` and `get_vm_config`. They accept a VM's name or vmid, raise `ValueError`/`RuntimeError` instead of returning a result dict, and wait for the Proxmox task to finish. `power_vm` is unchanged. - Snapshot methods `get_vm_snapshots`, `create_vm_snapshot`, `delete_vm_snapshot`, `rollback_vm_snapshot` for VMs and containers (containers never save RAM state). - `reboot_host()` restarts the node through the API instead of SSH. ### Changed - `get_vms()` reports `vmid` as a string (`"100"`), following napalm-device-types 2.0. Ordering stays numeric. ## [0.1.0] - 2024-01-01 ### Added - Initial release of the Proxmox VE NAPALM driver - Support for classic Linux networking (`/etc/network/interfaces`, Linux bridges) - Support for Proxmox SDN (zones: VLAN, QinQ, VXLAN, EVPN; VNets and subnets) - Support for Open vSwitch (OVS) bridges, bonds, and internal ports - Password and API token authentication via `proxmoxer` - Implemented NAPALM methods: - `open`, `close`, `is_alive` - `get_facts` - `get_interfaces`, `get_interfaces_ip`, `get_interfaces_counters` - `get_environment` (CPU, memory, temperature sensors) - `get_arp_table` (via `/proc/net/arp`) - `get_mac_address_table` (Linux bridge fdb + OVS appctl) - `get_vlans` (SDN VNet tags + `bridge vlan show`) - `get_network_instances` (SDN zones as NAPALM network instances) - `get_ntp_servers`, `get_ntp_stats` - `get_snmp_information` - `get_users` - `get_config`, `load_merge_candidate`, `load_replace_candidate` - `compare_config`, `commit_config`, `discard_config`, `rollback` - `get_lldp_neighbors`, `get_lldp_neighbors_detail` - `get_ipv6_neighbors_table` - `ping`, `traceroute`, `cli` - `get_route_to` - 149 unit tests with ~79% code coverage - Full type annotations