Files
napalm-proxmox/CHANGELOG.md
T
christianmanivong 8521cff935
driver / standard (pull_request) Successful in 20s
driver / lint (pull_request) Successful in 17s
driver / test (3.12) (pull_request) Successful in 1m25s
driver / types (pull_request) Successful in 1m27s
driver / test (3.13) (pull_request) Successful in 1m11s
driver / lowest (pull_request) Successful in 35s
driver / build (pull_request) Successful in 35s
driver / security (pull_request) Successful in 1m16s
CI / driver (pull_request) Successful in 3m4s
driver / publish (pull_request) Skipped
Merge remote-tracking branch 'origin/main' into feat/ssh-hardening
2026-11-02 12:07:33 +01:00

17 KiB
Raw Blame History

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

  • The node's sshd can be hardened: OpenSshServerMixin (napalm-device-types) gives harden_ssh_server and exempt_from_ssh_penalties, so netOrk's SSH algorithm fix works on a Proxmox node as on a plain Linux host. A node runs Debian's stock OpenSSH with an sshd_config.d include, so the change is a drop-in there (#50).
  • run_command(command, *, privileged=False, timeout=60, stdin=None), the public command channel: an exec channel on the node's SSH session with stdout, stderr and the exit status kept apart. privileged needs nothing more on a node logged in as root; a command that cannot run or outlasts its timeout raises ConnectionException.

Changed

  • The floor on napalm-device-types is 4.24.0, the first release with what this driver uses (its shared lldpctl parser).
  • 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_lldp_neighbors() and get_lldp_neighbors_detail() raise when lldpctl fails (lldpd not running, lldpctl missing) or the node gives no answer, with lldpctl's message; they used to return no neighbours, the same answer as a node without any (#44). Capabilities carry NAPALM's names (telephone, wlan-access-point, docsis-cable-device) instead of lldpd's symbols (tel, wlan, docsis). lldpd is read with lldpctl -f keyvalue through napalm-device-types' shared parser, so a neighbour named by its chassis MAC also carries it as mac, and an interface name with a dot stays whole.
  • 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/<old> while the cluster still knew the node as <old>. 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-<url hash>-<name>.<qcow2|raw|vmdk> 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