Files
napalm-proxmox/CHANGELOG.md
T
Christian Manivong dffb19e3df
driver / standard (pull_request) Successful in 17s
driver / lint (pull_request) Successful in 14s
driver / types (pull_request) Successful in 1m4s
driver / test (3.12) (pull_request) Successful in 1m8s
driver / test (3.13) (pull_request) Successful in 1m4s
driver / lowest (pull_request) Successful in 39s
driver / build (pull_request) Successful in 33s
driver / security (pull_request) Successful in 1m21s
CI / driver (pull_request) Successful in 3m1s
driver / publish (pull_request) Skipped
fix(vm-provision): quote the cloud-init snippet path in its root command
_write_snippet put the snippet storage's path and the snippet's file
name unquoted into the command that writes the snippet as root on the
node; a space, ; or $(...) in either was acted on by the shell. Both now
go through shlex.quote, and a file name that is not one plain name
(a path, a shell character) is refused before anything runs.

Closes #47
2026-11-02 09:25:45 +01:00

248 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/<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