feat(vm-provision): let Proxmox download cloud images into an import storage

Provisioning downloaded every cloud image over SSH into
/var/lib/vz/template/netork-images, on the node's root filesystem. On a
small root that fills up and takes Proxmox down with it (netOrk #480).

When the node has an active storage with content type "import" (Proxmox
8.2+), Proxmox now does it itself: download-url with checksum
verification into that storage, then import-from as the root disk. The
file is named after a hash of the full URL and reused when present.
Proxmox takes the format from the extension and has no ".img", so
Ubuntu's qcow2 .img is stored as .qcow2 -- a wrong guess fails at import
instead of attaching a qcow2 container as a raw disk.

Without an import storage, or for an image type Proxmox cannot import,
the SSH download is used as before.

CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- 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

napalm_proxmox/config_mixin.py

@@ -0,0 +1,145 @@
+# Copyright 2025 The NetOrk Project Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Configuration management NAPALM methods for Proxmox VE nodes."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+_JsonDict = dict[str, Any]
+
+
+class ProxmoxConfigMixin:
+    """Mixin providing configuration-management NAPALM methods."""
+
+    def get_config(
+        self,
+        retrieve: str = "all",
+        full: bool = False,
+        sanitized: bool = False,
+        format: str = "text",
+    ) -> _JsonDict:
+        """Return the node network configuration.
+
+        ``running`` config is the contents of ``/etc/network/interfaces``
+        (and the SDN config directory).  ``startup`` is identical (PVE
+        applies on boot).  ``candidate`` is what was loaded via
+        ``load_merge_candidate`` / ``load_replace_candidate`` but not yet
+        committed.
+        """
+        configs: _JsonDict = {"running": "", "candidate": "", "startup": ""}
+
+        if retrieve in ("running", "all", "startup"):
+            raw = self._exec_ssh_command(
+                "cat /etc/network/interfaces 2>/dev/null || true"
+            )
+            # Append SDN config if available
+            sdn_raw = self._exec_ssh_command(
+                "cat /etc/pve/sdn/vnets.cfg 2>/dev/null || true"
+            )
+            running = raw
+            if sdn_raw:
+                running += "\n# === SDN VNets ===\n" + sdn_raw
+            if sanitized:
+                running = re.sub(r"password\s+\S+", "password ****", running)
+            configs["running"] = running
+            self._running_config = running
+            if retrieve == "startup":
+                configs["startup"] = running
+            elif retrieve == "all":
+                configs["startup"] = running
+
+        if retrieve in ("candidate", "all"):
+            configs["candidate"] = self._candidate_config
+
+        return configs
+
+    def load_merge_candidate(
+        self,
+        filename: str | None = None,
+        config: str | None = None,
+    ) -> None:
+        """Load a candidate configuration (merge mode)."""
+        if filename:
+            with open(filename) as fh:
+                config = fh.read()
+        if config is None:
+            raise ValueError("Either filename or config must be provided")
+        # In merge mode we append / overlay
+        self._candidate_config = config
+
+    def load_replace_candidate(
+        self,
+        filename: str | None = None,
+        config: str | None = None,
+    ) -> None:
+        """Load a candidate configuration (replace mode)."""
+        if filename:
+            with open(filename) as fh:
+                config = fh.read()
+        if config is None:
+            raise ValueError("Either filename or config must be provided")
+        self._candidate_config = config
+
+    def compare_config(self) -> str:
+        """Return a unified diff between running and candidate config."""
+        import difflib
+
+        if not self._running_config:
+            self.get_config(retrieve="running")
+        running_lines = self._running_config.splitlines(keepends=True)
+        candidate_lines = self._candidate_config.splitlines(keepends=True)
+        diff = difflib.unified_diff(
+            running_lines,
+            candidate_lines,
+            fromfile="running",
+            tofile="candidate",
+        )
+        return "".join(diff)
+
+    def commit_config(self, message: str = "", revert_in: int | None = None) -> None:
+        """Commit the candidate configuration to the Proxmox node.
+
+        This writes the candidate config to ``/etc/network/interfaces``
+        via the Proxmox node/network PUT API (which applies it live).
+
+        .. note::
+            Full programmatic apply requires the Proxmox API to accept raw
+            interface configs.  This implementation uses ``pvesh`` via exec
+            which requires the node exec endpoint to be available.
+        """
+        if not self._candidate_config:
+            return
+        # Write via exec endpoint
+        escaped = self._candidate_config.replace("'", "'\\''")
+        self._exec_ssh_command(
+            f"printf '%s' '{escaped}' > /etc/network/interfaces && "
+            "ifreload -a 2>&1 || ifup -a 2>&1 || true"
+        )
+        self._running_config = self._candidate_config
+        self._candidate_config = ""
+
+    def discard_config(self) -> None:
+        """Discard the candidate configuration."""
+        self._candidate_config = ""
+
+    def rollback(self) -> None:
+        """Revert to the stored running configuration."""
+        if self._running_config:
+            self._candidate_config = self._running_config
+            self.commit_config()
+        self._candidate_config = ""

napalm_proxmox/interfaces_mixin.py

@@ -0,0 +1,268 @@
+# Copyright 2025 The NetOrk Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Interface-related NAPALM getters for Proxmox VE nodes."""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from napalm_proxmox import utils
+
+logger = logging.getLogger(__name__)
+
+_JsonDict = dict[str, Any]
+
+
+class ProxmoxInterfaceMixin:
+    """Mixin providing interface-related NAPALM getters."""
+
+    def get_interfaces(self) -> dict[str, _JsonDict]:
+        """Return a dict of interfaces keyed by interface name."""
+        result: dict[str, _JsonDict] = {}
+        for iface in self._get_node_network():
+            name = iface.get("iface", "")
+            if not name:
+                continue
+
+            active = iface.get("active", 0)
+            autostart = iface.get("autostart", 0)
+
+            result[name] = {
+                "is_up": bool(active),
+                "is_enabled": bool(autostart) or bool(active),
+                "description": iface.get("comments", "").strip(),
+                "last_flapped": -1.0,
+                "speed": utils.speed_mbps(iface),
+                "mtu": int(iface.get("mtu") or 1500),
+                "mac_address": utils.normalize_mac(iface.get("hwaddr", "")),
+            }
+        return result
+
+    def get_interfaces_ip(self) -> dict[str, _JsonDict]:
+        """Return IP addresses per interface."""
+        result: dict[str, _JsonDict] = {}
+        for iface in self._get_node_network():
+            name = iface.get("iface", "")
+            if not name:
+                continue
+            addrs = utils.addresses_from_node_network(iface)
+            if addrs:
+                result[name] = addrs
+
+        for vnet in self._get_sdn_vnets():
+            vnet_id = vnet.get("vnet", "")
+            if not vnet_id:
+                continue
+            for subnet in self._get_sdn_subnets(vnet_id):
+                cidr = subnet.get("cidr", "")
+                gateway = subnet.get("gateway", "")
+                if gateway and cidr:
+                    ip, plen = utils.parse_cidr(cidr)
+                    if "." in gateway:
+                        result.setdefault(vnet_id, {}).setdefault("ipv4", {})[gateway] = {
+                            "prefix_length": plen
+                        }
+                    else:
+                        result.setdefault(vnet_id, {}).setdefault("ipv6", {})[gateway] = {
+                            "prefix_length": plen
+                        }
+        return result
+
+    def get_interfaces_counters(self) -> dict[str, _JsonDict]:
+        """Return per-interface traffic counters."""
+        result: dict[str, _JsonDict] = {}
+        try:
+            rrd_data = self._node_api().netstat.get() or []
+        except Exception as exc:
+            logger.debug("Failed to fetch netstat counters: %s", exc)
+            rrd_data = []
+
+        latest: dict[str, _JsonDict] = {}
+        for entry in rrd_data:
+            iface = entry.get("dev", "")
+            if iface:
+                latest[iface] = entry
+
+        for iface, data in latest.items():
+            result[iface] = {
+                "tx_errors": int(data.get("tx_errs", 0) or 0),
+                "rx_errors": int(data.get("rx_errs", 0) or 0),
+                "tx_discards": int(data.get("tx_drop", 0) or 0),
+                "rx_discards": int(data.get("rx_drop", 0) or 0),
+                "tx_octets": int(data.get("tx_bytes", 0) or 0),
+                "rx_octets": int(data.get("rx_bytes", 0) or 0),
+                "tx_unicast_packets": int(data.get("tx_packets", 0) or 0),
+                "rx_unicast_packets": int(data.get("rx_packets", 0) or 0),
+                "tx_multicast_packets": 0,
+                "rx_multicast_packets": 0,
+                "tx_broadcast_packets": 0,
+                "rx_broadcast_packets": 0,
+            }
+        return result
+
+    def get_ipv6_neighbors_table(self) -> list[_JsonDict]:
+        """Return the IPv6 neighbour table, read via ``ip -6 neigh show``.
+
+        The IPv6 counterpart to :meth:`get_arp_table`. Proxmox exposes no REST
+        endpoint for it, so it goes through the node exec helper like the ARP
+        table does.
+
+        Entries in FAILED state are dropped: they record an address the kernel
+        could not resolve, so there is no neighbour to report.
+        """
+        raw = self._exec_ssh_command("ip -6 neigh show 2>/dev/null || true")
+        if not raw:
+            return []
+
+        entries: list[_JsonDict] = []
+        for line in raw.splitlines():
+            parts = line.split()
+            # "<ip> dev <iface> lladdr <mac> <STATE>" — an entry without lladdr
+            # never resolved and carries no neighbour.
+            if len(parts) < 6 or "lladdr" not in parts:
+                continue
+            state = parts[-1].upper()
+            if state == "FAILED":
+                continue
+            try:
+                iface = parts[parts.index("dev") + 1]
+                mac = parts[parts.index("lladdr") + 1]
+            except (ValueError, IndexError):
+                continue
+            entries.append(
+                {
+                    "interface": iface,
+                    "mac": utils.normalize_mac(mac),
+                    "ip": parts[0],
+                    # `ip neigh` reports no age; NAPALM's shape requires the key.
+                    "age": 0.0,
+                    "state": state,
+                }
+            )
+        return entries
+
+    def get_arp_table(self, vrf: str = "") -> list[_JsonDict]:
+        """Return ARP table.
+
+        Proxmox does not expose ARP via the REST API directly.  We attempt
+        to read it via the node's ``/proc/net/arp`` through the Proxmox
+        exec endpoint.  If that is unavailable, an empty list is returned.
+        """
+        raw = self._exec_ssh_command("cat /proc/net/arp")
+        if not raw:
+            return []
+
+        entries = []
+        for line in raw.splitlines():
+            line = line.strip()
+            if not line or line.startswith("IP"):
+                continue
+            parts = line.split()
+            if len(parts) < 6:
+                continue
+            ip_addr, _, flags, mac, _, iface = (
+                parts[0], parts[1], parts[2], parts[3], parts[4], parts[5]
+            )
+            if mac in ("00:00:00:00:00:00", ""):
+                continue
+            if vrf and iface != vrf:
+                continue
+            entries.append(
+                {
+                    "interface": iface,
+                    "mac": utils.normalize_mac(mac),
+                    "ip": ip_addr,
+                    "age": -1.0,
+                }
+            )
+        return entries
+
+    def get_mac_address_table(self) -> list[_JsonDict]:
+        """Return MAC address table from Linux bridges and OVS bridges."""
+        result: list[_JsonDict] = []
+        network = self._get_node_network()
+
+        linux_bridges = [
+            iface["iface"]
+            for iface in network
+            if iface.get("type") in ("bridge",) and iface.get("iface")
+        ]
+        for bridge in linux_bridges:
+            raw = self._exec_ssh_command(
+                f"bridge fdb show br {bridge} 2>/dev/null || true"
+            )
+            for line in raw.splitlines():
+                parts = line.split()
+                if len(parts) < 3:
+                    continue
+                mac_str = parts[0]
+                if not re.match(r"([0-9a-f]{2}:){5}[0-9a-f]{2}", mac_str):
+                    continue
+                dev = ""
+                vlan_id = 1
+                for i, tok in enumerate(parts):
+                    if tok == "dev" and i + 1 < len(parts):
+                        dev = parts[i + 1]
+                    if tok == "vlan" and i + 1 < len(parts):
+                        try:
+                            vlan_id = int(parts[i + 1])
+                        except ValueError:
+                            pass
+                result.append(
+                    {
+                        "mac": utils.normalize_mac(mac_str),
+                        "interface": dev or bridge,
+                        "vlan": vlan_id,
+                        "static": "permanent" in line,
+                        "active": True,
+                        "moves": 0,
+                        "last_move": 0.0,
+                    }
+                )
+
+        ovs_bridges = [
+            iface["iface"]
+            for iface in network
+            if iface.get("type") in ("OVSBridge",) and iface.get("iface")
+        ]
+        for bridge in ovs_bridges:
+            raw = self._exec_ssh_command(
+                f"ovs-appctl fdb/show {bridge} 2>/dev/null || true"
+            )
+            for line in raw.splitlines():
+                parts = line.split()
+                if len(parts) < 4:
+                    continue
+                try:
+                    _port = int(parts[0])
+                    vlan_id = int(parts[1])
+                    mac_str = parts[2]
+                except (ValueError, IndexError):
+                    continue
+                result.append(
+                    {
+                        "mac": utils.normalize_mac(mac_str),
+                        "interface": bridge,
+                        "vlan": vlan_id,
+                        "static": False,
+                        "active": True,
+                        "moves": 0,
+                        "last_move": 0.0,
+                    }
+                )
+
+        return result

napalm_proxmox/lldp_mixin.py

@@ -0,0 +1,107 @@
+# Copyright 2025 The NetOrk Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""LLDP-related NAPALM getters for Proxmox VE nodes."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+_JsonDict = dict[str, Any]
+
+
+class ProxmoxLLDPMixin:
+    """Mixin providing LLDP NAPALM methods."""
+
+    def get_lldp_neighbors(self) -> dict[str, list[_JsonDict]]:
+        """Return LLDP neighbours (requires lldpd on the Proxmox node)."""
+        result: dict[str, list[_JsonDict]] = {}
+        raw = self._exec_ssh_command(
+            "lldpcli show neighbors summary 2>/dev/null || true"
+        )
+        current_iface = ""
+        for line in raw.splitlines():
+            m_iface = re.match(r"^\s*Interface:\s+(\S+?),?\s", line)
+            if m_iface:
+                current_iface = m_iface.group(1)
+                result.setdefault(current_iface, [])
+                continue
+            m_sys = re.match(r"^\s*SysName:\s+(.+)", line)
+            m_port = re.match(r"^\s*PortID:\s+\S+\s+(.+)", line)
+            if m_sys and current_iface:
+                hostname = m_sys.group(1).strip()
+                if result[current_iface]:
+                    result[current_iface][-1]["hostname"] = hostname
+                else:
+                    result[current_iface].append({"hostname": hostname, "port": ""})
+            if m_port and current_iface and result[current_iface]:
+                result[current_iface][-1]["port"] = m_port.group(1).strip()
+        return result
+
+    def get_lldp_neighbors_detail(self, interface: str = "") -> dict[str, list[_JsonDict]]:
+        """Return detailed LLDP neighbour information."""
+        result: dict[str, list[_JsonDict]] = {}
+        raw = self._exec_ssh_command(
+            "lldpcli show neighbors details 2>/dev/null || true"
+        )
+        current_iface = ""
+        current_entry: _JsonDict = {}
+
+        def _flush():
+            if current_iface and current_entry:
+                result.setdefault(current_iface, []).append(current_entry.copy())
+
+        for line in raw.splitlines():
+            m_iface = re.match(r"^\s*Interface:\s+(\S+?),?\s", line)
+            if m_iface:
+                _flush()
+                current_iface = m_iface.group(1)
+                if interface and current_iface != interface:
+                    current_iface = ""
+                current_entry = {
+                    "parent_interface": "",
+                    "remote_chassis_id": "",
+                    "remote_system_name": "",
+                    "remote_port": "",
+                    "remote_port_description": "",
+                    "remote_system_description": "",
+                    "remote_system_capab": [],
+                    "remote_system_enable_capab": [],
+                }
+                continue
+            if not current_iface:
+                continue
+            for key, pattern in (
+                ("remote_chassis_id", r"ChassisID:\s+\S+\s+(.+)"),
+                ("remote_system_name", r"SysName:\s+(.+)"),
+                ("remote_port", r"PortID:\s+\S+\s+(.+)"),
+                ("remote_port_description", r"PortDescr:\s+(.+)"),
+                ("remote_system_description", r"SysDescr:\s+(.+)"),
+            ):
+                m = re.match(rf"^\s*{pattern}", line)
+                if m:
+                    current_entry[key] = m.group(1).strip()
+
+            m_cap = re.match(r"^\s*Capability:\s+(\S+),\s+(\w+)", line)
+            if m_cap:
+                cap = m_cap.group(1).lower()
+                enabled = m_cap.group(2).lower() == "on"
+                current_entry["remote_system_capab"].append(cap)
+                if enabled:
+                    current_entry["remote_system_enable_capab"].append(cap)
+
+        _flush()
+        return result

napalm_proxmox/routing_mixin.py

@@ -0,0 +1,225 @@
+# Copyright 2025 The NetOrk Project Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Routing-related NAPALM getters for Proxmox VE nodes."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import napalm.base.constants as C
+
+
+_JsonDict = dict[str, Any]
+
+
+class ProxmoxRoutingMixin:
+    """Mixin providing routing NAPALM methods (get_route_to, ping, traceroute)."""
+
+    def ping(
+        self,
+        destination: str,
+        source: str = C.PING_SOURCE,
+        ttl: int = C.PING_TTL,
+        timeout: int = C.PING_TIMEOUT,
+        size: int = C.PING_SIZE,
+        count: int = C.PING_COUNT,
+        vrf: str = C.PING_VRF,
+        source_interface: str = C.PING_SOURCE_INTERFACE,
+    ) -> _JsonDict:
+        """Execute ping on the Proxmox node and return results."""
+        cmd_parts = [
+            f"ping -c {count}",
+            f"-W {timeout}",
+            f"-s {size}",
+            f"-t {ttl}",
+        ]
+        if source:
+            cmd_parts.append(f"-I {source}")
+        elif source_interface:
+            cmd_parts.append(f"-I {source_interface}")
+        cmd_parts.append(destination)
+        cmd = " ".join(cmd_parts)
+
+        raw = self._exec_ssh_command(f"{cmd} 2>&1 || true")
+        if not raw:
+            return {"error": "Ping command not available via exec endpoint"}
+
+        # Detect common failure strings before parsing statistics
+        _error_patterns = (
+            "Name or service not known",
+            "Network is unreachable",
+            "connect: No route to host",
+            "unknown host",
+        )
+        for _pat in _error_patterns:
+            if _pat.lower() in raw.lower():
+                return {"error": raw.strip()}
+
+        # Parse statistics line: "5 packets transmitted, 5 received, 0% packet loss"
+        m_stat = re.search(
+            r"(\d+) packets transmitted,\s+(\d+) received.*?([\d.]+)% packet loss",
+            raw,
+        )
+        if not m_stat:
+            return {"error": raw.strip()}
+
+        sent = int(m_stat.group(1))
+        received = int(m_stat.group(2))
+        loss = sent - received
+
+        # RTT line: "rtt min/avg/max/mdev = 0.123/0.456/0.789/0.100 ms"
+        m_rtt = re.search(
+            r"rtt min/avg/max/mdev = ([\d.]+)/([\d.]+)/([\d.]+)/([\d.]+)",
+            raw,
+        )
+        rtt_min = float(m_rtt.group(1)) if m_rtt else 0.0
+        rtt_avg = float(m_rtt.group(2)) if m_rtt else 0.0
+        rtt_max = float(m_rtt.group(3)) if m_rtt else 0.0
+        rtt_std = float(m_rtt.group(4)) if m_rtt else 0.0
+
+        # Individual probe lines
+        probes = []
+        for m_probe in re.finditer(
+            r"icmp_seq=\d+.*?time=([\d.]+) ms.*?from ([\d.a-fA-F:]+)", raw
+        ):
+            probes.append(
+                {"ip_address": m_probe.group(2), "rtt": float(m_probe.group(1))}
+            )
+
+        return {
+            "success": {
+                "probes_sent": sent,
+                "packet_loss": loss,
+                "rtt_min": rtt_min,
+                "rtt_max": rtt_max,
+                "rtt_avg": rtt_avg,
+                "rtt_stddev": rtt_std,
+                "results": probes,
+            }
+        }
+
+    def traceroute(
+        self,
+        destination: str,
+        source: str = "",
+        ttl: int = 255,
+        timeout: int = 2,
+        vrf: str = "",
+    ) -> _JsonDict:
+        """Execute traceroute on the Proxmox node and return results."""
+        cmd_parts = [f"traceroute -m {ttl}", f"-w {timeout}", "-n"]
+        if source:
+            cmd_parts.append(f"-s {source}")
+        cmd_parts.append(destination)
+        raw = self._exec_ssh_command(" ".join(cmd_parts) + " 2>&1 || true")
+
+        if not raw:
+            return {"error": "traceroute not available via exec endpoint"}
+
+        hops: _JsonDict = {}
+        for line in raw.splitlines():
+            m = re.match(
+                r"^\s*(\d+)\s+([\d.a-fA-F:]+|\*)\s+([\d.]+|[\d.]+\s+ms|\*)",
+                line,
+            )
+            if not m:
+                continue
+            hop_id = int(m.group(1))
+            ip_addr = m.group(2)
+            if ip_addr == "*":
+                continue
+            # Parse RTT probes: each hop can have up to 3
+            rtts = re.findall(r"([\d.]+)\s+ms", line)
+            probes_dict = {}
+            for idx, rtt in enumerate(rtts, start=1):
+                probes_dict[idx] = {
+                    "rtt": float(rtt),
+                    "ip_address": ip_addr,
+                    "host_name": ip_addr,
+                }
+            if probes_dict:
+                hops[hop_id] = {"probes": probes_dict}
+
+        if not hops:
+            return {"error": raw.strip()}
+        return {"success": hops}
+
+    def get_bgp_config(self, group: str = "", neighbor: str = "") -> _JsonDict:
+        raise NotImplementedError("BGP configuration is not managed via Proxmox API")
+
+    def get_bgp_neighbors(self) -> _JsonDict:
+        raise NotImplementedError("BGP is not managed via Proxmox API")
+
+    def get_bgp_neighbors_detail(self, neighbor_address: str = "") -> _JsonDict:
+        raise NotImplementedError("BGP is not managed via Proxmox API")
+
+    def get_route_to(
+        self, destination: str = "", protocol: str = "", longer: bool = False
+    ) -> _JsonDict:
+        """Return routing table entries for the given destination."""
+        cmd = f"ip route show {destination} 2>/dev/null || true"
+        raw = self._exec_ssh_command(cmd)
+        routes: _JsonDict = {}
+        for line in raw.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            parts = line.split()
+            if not parts:
+                continue
+            prefix = parts[0]
+            next_hop = ""
+            out_iface = ""
+            proto = "static"
+            for i, tok in enumerate(parts):
+                if tok == "via" and i + 1 < len(parts):
+                    next_hop = parts[i + 1]
+                if tok == "dev" and i + 1 < len(parts):
+                    out_iface = parts[i + 1]
+                if tok == "proto" and i + 1 < len(parts):
+                    proto = parts[i + 1]
+
+            if protocol and protocol.lower() not in proto.lower():
+                continue
+
+            routes.setdefault(prefix, []).append(
+                {
+                    "protocol": proto,
+                    "current_active": True,
+                    "last_active": True,
+                    "age": -1,
+                    "next_hop": next_hop,
+                    "outgoing_interface": out_iface,
+                    "selected_next_hop": True,
+                    "preference": 1,
+                    "inactive_reason": "",
+                    "routing_table": "default",
+                    "protocol_attributes": {},
+                }
+            )
+        return routes
+
+    def get_optics(self) -> _JsonDict:
+        raise NotImplementedError("Optics not available via Proxmox API")
+
+    def get_probes_config(self) -> _JsonDict:
+        raise NotImplementedError
+
+    def get_probes_results(self) -> _JsonDict:
+        raise NotImplementedError
+
+    def get_firewall_policies(self) -> _JsonDict:
+        raise NotImplementedError("Use the Proxmox firewall API directly")

napalm_proxmox/sdn_mixin.py

@@ -0,0 +1,445 @@
+# Copyright 2025 The NetOrk Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""SDN, VLAN and network-instance NAPALM getters for Proxmox VE nodes."""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from napalm.base.exceptions import ConnectionException
+from proxmoxer.core import ResourceException
+
+from napalm_proxmox import utils
+
+logger = logging.getLogger(__name__)
+
+_JsonDict = dict[str, Any]
+
+
+class ProxmoxSDNMixin:
+    """Mixin providing SDN, VLAN and network-instance NAPALM methods."""
+
+    def _get_sdn_zones(self) -> list[_JsonDict]:
+        try:
+            return self._api.cluster.sdn.zones.get() or []  # type: ignore[union-attr]
+        except Exception as exc:
+            logger.debug("Failed to fetch SDN zones: %s", exc)
+            return []
+
+    def _get_sdn_vnets(self) -> list[_JsonDict]:
+        try:
+            return self._api.cluster.sdn.vnets.get() or []  # type: ignore[union-attr]
+        except Exception as exc:
+            logger.debug("Failed to fetch SDN VNets: %s", exc)
+            return []
+
+    def _get_sdn_subnets(self, vnet: str) -> list[_JsonDict]:
+        try:
+            return self._api.cluster.sdn.vnets(vnet).subnets.get() or []
+        except Exception as exc:
+            logger.debug("Failed to fetch SDN subnets for %s: %s", vnet, exc)
+            return []
+
+    def get_vlans(self) -> dict[str, _JsonDict]:
+        """Return VLAN table.
+
+        For OVS+SDN nodes: reads SDN VNets for VLAN IDs/names, then maps
+        OVSIntPort (access ports with ovs_tag) → untagged membership, and
+        OVSPort / OVSBridge (trunk ports) → tagged membership.
+
+        Without OVS ports, VLAN membership is derived from the ``tag=`` values
+        in each VM's and container's ``netN`` config (:meth:`_get_vm_vlan_tags`).
+        """
+        result: dict[str, _JsonDict] = {}
+        node_network = self._get_node_network()
+
+        for vnet in self._get_sdn_vnets():
+            tag = vnet.get("tag")
+            vnet_id = vnet.get("vnet", "")
+            if tag is None:
+                continue
+            try:
+                tag_int = int(tag)
+            except (ValueError, TypeError):
+                continue
+            result[str(tag_int)] = {
+                "name": vnet_id,
+                "tagged": [],
+                "untagged": [],
+            }
+
+        trunk_ports: list[str] = []
+        access_by_vlan: dict[str, list[str]] = {}
+
+        for iface in node_network:
+            ovs_type = iface.get("ovs_type", "")
+            iface_name = iface.get("iface", "")
+            if not iface_name:
+                continue
+            if ovs_type == "OVSIntPort":
+                ovs_tag = iface.get("ovs_tag")
+                if ovs_tag is not None:
+                    vid = str(int(ovs_tag))
+                    access_by_vlan.setdefault(vid, []).append(iface_name)
+            elif ovs_type in ("OVSPort", "OVSBridge"):
+                trunk_ports.append(iface_name)
+
+        if trunk_ports or access_by_vlan:
+            for vid, vlan_entry in result.items():
+                vlan_entry["tagged"] = list(trunk_ports)
+                vlan_entry["untagged"] = list(access_by_vlan.get(vid, []))
+            return result
+
+        for entry in result.values():
+            entry.setdefault("tagged", [])
+            entry.setdefault("untagged", [])
+
+        for tag, bridges in self._get_vm_vlan_tags().items():
+            entry = result.setdefault(tag, {"name": "", "tagged": [], "untagged": []})
+            for bridge in bridges:
+                if bridge not in entry["untagged"]:
+                    entry["untagged"].append(bridge)
+
+        # Deliberately unfiltered. This used to drop entries with no member
+        # ports, which hid every configured SDN VNet that no VM happened to be
+        # attached to — and contradicted the OVS branch above, which returns
+        # empty-membership VLANs. A VNet exists on the node whether or not
+        # anything currently uses it, and netOrk's VLAN discovery reads this.
+        return result
+
+    def _get_vm_vlan_tags(self) -> dict[str, set[str]]:
+        """Return ``{vlan_tag: {bridge_names}}`` derived from VM/container net configs.
+
+        Scans every QEMU VM and LXC container on this node for ``netN`` config
+        entries of the form ``bridge=vmbrX,tag=N,...`` and groups the bridges
+        each VLAN tag is used on.
+        """
+        tags: dict[str, set[str]] = {}
+        net_re = re.compile(r"^net\d+$")
+
+        def _collect(vmid: int, config: _JsonDict) -> None:
+            for key, val in config.items():
+                if not net_re.match(key):
+                    continue
+                bridge = ""
+                tag: int | None = None
+                for part in str(val).split(","):
+                    if "=" not in part:
+                        continue
+                    k, v = part.split("=", 1)
+                    k = k.strip().lower()
+                    if k == "bridge":
+                        bridge = v.strip()
+                    elif k == "tag":
+                        try:
+                            tag = int(v.strip())
+                        except ValueError:
+                            pass
+                if tag is not None and bridge:
+                    tags.setdefault(str(tag), set()).add(bridge)
+
+        try:
+            for vm in (self._node_api().qemu.get() or []):
+                vmid = int(vm.get("vmid", 0))
+                try:
+                    config = self._node_api().qemu(vmid).config.get() or {}
+                    _collect(vmid, config)
+                except Exception as exc:
+                    logger.debug("_get_vm_vlan_tags: QEMU %s config failed: %s", vmid, exc)
+        except Exception as exc:
+            logger.warning("_get_vm_vlan_tags: failed to list QEMU VMs: %s", exc)
+
+        try:
+            for ct in (self._node_api().lxc.get() or []):
+                vmid = int(ct.get("vmid", 0))
+                try:
+                    config = self._node_api().lxc(vmid).config.get() or {}
+                    _collect(vmid, config)
+                except Exception as exc:
+                    logger.debug("_get_vm_vlan_tags: LXC %s config failed: %s", vmid, exc)
+        except Exception as exc:
+            logger.warning("_get_vm_vlan_tags: failed to list LXC containers: %s", exc)
+
+        return tags
+
+    def get_network_instances(self, name: str = "") -> dict[str, _JsonDict]:
+        """Return SDN zones as network instances."""
+        result: dict[str, _JsonDict] = {}
+
+        result["default"] = {
+            "name": "default",
+            "type": "DEFAULT_INSTANCE",
+            "state": {"route_distinguisher": None},
+            "interfaces": {"interface": {}},
+        }
+
+        for iface in self._get_node_network():
+            iface_name = iface.get("iface", "")
+            if iface_name:
+                result["default"]["interfaces"]["interface"][iface_name] = {}
+
+        for zone in self._get_sdn_zones():
+            zone_id = zone.get("zone", zone.get("name", ""))
+            if not zone_id:
+                continue
+            if name and zone_id != name:
+                continue
+            instance = utils.sdn_zone_to_network_instance(zone)
+            for vnet in self._get_sdn_vnets():
+                if vnet.get("zone") == zone_id:
+                    vnet_id = vnet.get("vnet", "")
+                    if vnet_id:
+                        instance["interfaces"]["interface"][vnet_id] = {}
+            result[zone_id] = instance
+
+        if name:
+            return {k: v for k, v in result.items() if k == name}
+        return result
+
+    def _is_physical_uplink(self, iface_name: str, network: dict) -> bool:
+        """Return True if *iface_name* is a physical Ethernet port usable as uplink.
+
+        Rules:
+        - Must not match any known virtual interface name prefix.
+        - Must appear in the Proxmox node network config (runtime-only virtual
+          interfaces such as ``fwpr*`` or ``tap*`` will not be listed there).
+        - Must have a physical-compatible type:
+          - ``"eth"``     — regular physical NIC
+          - ``"OVSPort"`` — physical NIC attached directly to an OVS bridge
+          - ``""``        — untyped (e.g. OVS bond slave, still physical)
+        """
+        if any(iface_name.startswith(p) for p in self._VIRTUAL_IFACE_PREFIXES):
+            return False
+        iface_info = network.get(iface_name)
+        if iface_info is None:
+            return False
+        return iface_info.get("type", "") in ("eth", "OVSPort", "")
+
+    def _find_switch_uplink(self) -> str | None:
+        """Return the name of the physical interface connected to a switch.
+
+        Detection order:
+        1. LLDP detailed: physical port whose neighbour advertises Bridge
+           capability.
+        2. LLDP basic fallback: first physical port with any LLDP neighbour.
+        """
+        network = {
+            iface["iface"]: iface
+            for iface in self._get_node_network()
+            if iface.get("iface")
+        }
+
+        try:
+            for iface_name, neighbour_list in self.get_lldp_neighbors_detail().items():
+                if not self._is_physical_uplink(iface_name, network):
+                    continue
+                for nb in neighbour_list:
+                    caps = nb.get("remote_system_capab", [])
+                    if any("bridge" in str(c).lower() for c in caps):
+                        return iface_name
+        except Exception as exc:
+            logger.debug("LLDP detailed neighbor discovery failed: %s", exc)
+
+        try:
+            for iface_name, neighbour_list in self.get_lldp_neighbors().items():
+                if self._is_physical_uplink(iface_name, network) and neighbour_list:
+                    return iface_name
+        except Exception as exc:
+            logger.debug("LLDP basic neighbor discovery failed: %s", exc)
+
+        return None
+
+    def _get_ovs_bridge_for_port(self, port_name: str) -> str | None:
+        """Return the OVS bridge name that *port_name* belongs to, or ``None``.
+
+        Checks (in order):
+        1. Port listed in an OVSBridge's ``ovs_ports``.
+        2. Port is a slave of an OVSBond which has an ``ovs_bridge`` reference.
+        3. Port itself carries an ``ovs_bridge`` field.
+        """
+        network = self._get_node_network()
+        by_name: dict[str, _JsonDict] = {
+            iface["iface"]: iface for iface in network if iface.get("iface")
+        }
+
+        for iface in network:
+            if iface.get("type") == "OVSBridge":
+                ports = (iface.get("ovs_ports") or "").split()
+                if port_name in ports:
+                    return iface["iface"]
+
+        for iface in network:
+            if iface.get("type") == "OVSBond":
+                slaves = (iface.get("slaves") or "").split()
+                if port_name in slaves:
+                    bridge = iface.get("ovs_bridge", "")
+                    if bridge:
+                        return bridge
+
+        port_info = by_name.get(port_name, {})
+        return port_info.get("ovs_bridge") or None
+
+    def _is_cluster_master(self) -> bool:
+        """Return ``True`` if this node is the Corosync quorum coordinator.
+
+        The coordinator is the online cluster node with the lowest ``nodeid``.
+        On standalone (non-clustered) nodes this always returns ``True``.
+        """
+        try:
+            status = self._api.cluster.status.get() or []
+            node_entries = [e for e in status if e.get("type") == "node"]
+            if not node_entries:
+                return True
+            online_nodes = [n for n in node_entries if n.get("online", 0)]
+            if not online_nodes:
+                return True
+            min_id = min(int(n.get("nodeid", 9999)) for n in online_nodes)
+            for n in online_nodes:
+                if (
+                    n.get("name") == self._node_name
+                    and int(n.get("nodeid", 9999)) == min_id
+                ):
+                    return True
+            return False
+        except Exception as exc:
+            logger.warning("Cannot determine cluster status, assuming standalone: %s", exc)
+            return True
+
+    def _get_sdn_zone_for_bridge(self, bridge_name: str) -> str | None:
+        """Return the SDN zone ID whose ``bridge`` field matches *bridge_name*.
+
+        In Proxmox SDN each zone is linked to exactly one OVS bridge via the
+        ``bridge`` property.  We look for that mapping so the VNet is always
+        created in the correct zone instead of guessing by type order.
+
+        Falls back to the first zone if no bridge match is found.
+        """
+        try:
+            zones = self._get_sdn_zones()
+            for zone in zones:
+                if zone.get("bridge") == bridge_name:
+                    return zone.get("zone")
+            if zones:
+                return zones[0].get("zone")
+        except Exception as exc:
+            logger.debug("Failed to get SDN zone for bridge: %s", exc)
+        return None
+
+    def set_vlan(self, vlan_id: int, config) -> None:
+        """Create (or update) a VLAN via an SDN VNet on this Proxmox node.
+
+        Pre-flight checks (all must pass to proceed):
+
+        1. Finds the physical uplink port connected to a switch via LLDP.
+           Physical ports are those with type ``eth``, ``OVSPort``, or ``""``
+           in the Proxmox network config (excludes runtime virtuals like
+           ``fwpr*``, ``tap*``, etc.).
+        2. Verifies that uplink is part of an OVS bridge or OVS bond.
+        3. Confirms this node is the Corosync quorum master (lowest node-id).
+           Non-master nodes return silently — the master handles VNet creation.
+
+        The SDN VNet is named ``vlan{vid:04d}`` (e.g. ``vlan0007`` for VID 7).
+        If the VNet already exists its alias is updated.  After creating /
+        updating the VNet the SDN configuration is reloaded via
+        ``PUT /cluster/sdn``.
+
+        Args:
+            vlan_id: VLAN identifier (1-4094).
+            config:  Dict that may contain ``"name"`` for the VLAN alias.
+        """
+        name: str = (
+            (config.get("name") or f"VLAN{vlan_id}") if config else f"VLAN{vlan_id}"
+        )
+        vnet_id = f"vlan{vlan_id:04d}"
+
+        uplink = self._find_switch_uplink()
+        if uplink is None:
+            raise ConnectionException(
+                f"set_vlan({vlan_id}): no LLDP-detected switch uplink found"
+                f" on node {self._node_name!r}"
+            )
+
+        ovs_bridge = self._get_ovs_bridge_for_port(uplink)
+        if ovs_bridge is None:
+            raise ConnectionException(
+                f"set_vlan({vlan_id}): uplink {uplink!r} is not part of an OVS bridge"
+            )
+
+        if not self._is_cluster_master():
+            return
+
+        zone = self._get_sdn_zone_for_bridge(ovs_bridge)
+        if not zone:
+            raise ConnectionException(
+                f"set_vlan({vlan_id}): no SDN zone found for bridge {ovs_bridge!r}"
+            )
+
+        try:
+            self._api.cluster.sdn.vnets.post(
+                vnet=vnet_id,
+                zone=zone,
+                tag=vlan_id,
+                alias=name,
+            )
+        except ResourceException as exc:
+            err_str = str(exc).lower()
+            if "already exists" in err_str or "duplicate" in err_str or "500" in err_str:
+                try:
+                    self._api.cluster.sdn.vnets(vnet_id).put(alias=name)
+                except Exception as exc:
+                    logger.debug("Best-effort VNet alias update failed: %s", exc)
+            else:
+                raise ConnectionException(
+                    f"set_vlan({vlan_id}): failed to create VNet {vnet_id!r}: {exc}"
+                ) from exc
+
+        try:
+            self._api.cluster.sdn.put()
+        except Exception as exc:
+            logger.debug("Best-effort SDN reload failed (may not be needed on older PVE): %s", exc)
+
+    def delete_vlan(self, vlan_id: int) -> None:
+        """Delete the SDN VNet corresponding to *vlan_id*.
+
+        The VNet is identified by the canonical name ``vlan{vid:04d}``.
+        Only the Corosync quorum master performs the deletion — non-master
+        nodes return silently.
+
+        After deletion the SDN configuration is reloaded via
+        ``PUT /cluster/sdn``.
+
+        Args:
+            vlan_id: VLAN identifier to delete.
+        """
+        if not self._is_cluster_master():
+            return
+
+        vnet_id = f"vlan{vlan_id:04d}"
+        try:
+            self._api.cluster.sdn.vnets(vnet_id).delete()
+        except ResourceException as exc:
+            err_str = str(exc).lower()
+            if "does not exist" in err_str or "404" in str(exc):
+                return
+            raise ConnectionException(
+                f"delete_vlan({vlan_id}): failed to delete VNet {vnet_id!r}: {exc}"
+            ) from exc
+
+        try:
+            self._api.cluster.sdn.put()
+        except Exception as exc:
+            logger.debug("Best-effort SDN reload after delete failed: %s", exc)

napalm_proxmox/system_mixin.py

@@ -0,0 +1,870 @@
+# Copyright 2025 The NetOrk Project Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""System-level NAPALM getters for Proxmox VE nodes (environment, NTP, SNMP, users, packages, services, updates, disk SMART)."""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from napalm_proxmox import utils
+
+logger = logging.getLogger(__name__)
+
+_JsonDict = dict[str, Any]
+
+
+class ProxmoxSystemMixin:
+    """Mixin providing system-level NAPALM methods."""
+
+    # ------------------------------------------------------------------ #
+    # get_environment
+    # ------------------------------------------------------------------ #
+
+    def get_environment(self) -> _JsonDict:
+        """Return environment status (CPU, memory, temperature)."""
+        status = self._get_node_status()
+        env: _JsonDict = {
+            "fans": {},
+            "temperature": {},
+            "power": {},
+            "cpu": {},
+            "memory": {"available_ram": 0, "used_ram": 0},
+        }
+
+        # CPU
+        cpu_usage = status.get("cpu", 0.0)
+        env["cpu"]["0"] = {"%usage": round(float(cpu_usage) * 100, 2)}
+
+        # Memory (Proxmox reports in bytes)
+        mem = status.get("memory", {})
+        total = int(mem.get("total", 0) or 0)
+        used = int(mem.get("used", 0) or 0)
+        env["memory"]["available_ram"] = total
+        env["memory"]["used_ram"] = used
+
+        # Temperature (from node sensors if available)
+        try:
+            sensors = self._node_api().hardware.sensors.get() or []
+        except Exception as exc:
+            logger.debug("Failed to fetch hardware sensors: %s", exc)
+            sensors = []
+        for sensor in sensors:
+            name = sensor.get("name", "unknown")
+            value = sensor.get("value", None)
+            if value is not None:
+                try:
+                    temp_c = float(value)
+                    env["temperature"][name] = {
+                        "temperature": temp_c,
+                        "is_alert": temp_c >= 80.0,
+                        "is_critical": temp_c >= 95.0,
+                    }
+                except (TypeError, ValueError):
+                    pass
+
+        return env
+
+    # ------------------------------------------------------------------ #
+    # get_ntp_servers / get_ntp_stats
+    # ------------------------------------------------------------------ #
+
+    def get_ntp_servers(self) -> dict[str, _JsonDict]:
+        """Return configured NTP servers."""
+        ntp = self._get_node_ntp()
+        servers: dict[str, _JsonDict] = {}
+        # Proxmox reports a comma-separated or space-separated server list
+        raw = ntp.get("server", "") or ntp.get("servers", "")
+        for srv in re.split(r"[\s,]+", raw):
+            srv = srv.strip()
+            if srv:
+                servers[srv] = {}
+        return servers
+
+    def get_ntp_stats(self) -> list[_JsonDict]:
+        """Return NTP synchronisation statistics from chronyc/ntpq output."""
+        raw = self._exec_ssh_command(
+            "chronyc -n tracking 2>/dev/null || ntpq -pn 2>/dev/null || true"
+        )
+        stats: list[_JsonDict] = []
+        for line in raw.splitlines():
+            line = line.strip()
+            # ntpq -pn format: *remote  refid  st  t  when  poll  reach  delay  offset  jitter
+            m = re.match(
+                r"^([\*\+\-\s])([\d.]+)\s+([\d.]+)\s+(\d+)\s+\S+\s+(\S+)\s+(\d+)\s+(\d+)\s+([\d.]+)\s+([-\d.]+)\s+([\d.]+)",
+                line,
+            )
+            if m:
+                synced = m.group(1).strip() == "*"
+                stats.append(
+                    {
+                        "remote": m.group(2),
+                        "referenceid": m.group(3),
+                        "synchronized": synced,
+                        "stratum": int(m.group(4)),
+                        "type": "",
+                        "when": m.group(5),
+                        "hostpoll": int(m.group(6)),
+                        "reachability": int(m.group(7)),
+                        "delay": float(m.group(8)),
+                        "offset": float(m.group(9)),
+                        "jitter": float(m.group(10)),
+                    }
+                )
+        return stats
+
+    # ------------------------------------------------------------------ #
+    # get_snmp_information
+    # ------------------------------------------------------------------ #
+
+    def get_snmp_information(self) -> _JsonDict:
+        """Return SNMP information.
+
+        Proxmox does not expose SNMP configuration via the REST API.
+        We read /etc/snmp/snmpd.conf via exec if available.
+        """
+        raw = self._exec_ssh_command(
+            "cat /etc/snmp/snmpd.conf 2>/dev/null || true"
+        )
+        communities: dict[str, _JsonDict] = {}
+        location = ""
+        contact = ""
+        for line in raw.splitlines():
+            line = line.strip()
+            if line.startswith("#") or not line:
+                continue
+            # rocommunity <community> [source]
+            m = re.match(r"^(ro|rw)community\s+(\S+)", line)
+            if m:
+                mode = "ro" if m.group(1) == "ro" else "rw"
+                community = m.group(2)
+                communities[community] = {"acl": "N/A", "mode": mode}
+            m_loc = re.match(r"^sysLocation\s+(.+)", line)
+            if m_loc:
+                location = m_loc.group(1).strip()
+            m_con = re.match(r"^sysContact\s+(.+)", line)
+            if m_con:
+                contact = m_con.group(1).strip()
+
+        return {
+            "chassis_id": self._node_name,
+            "community": communities,
+            "contact": contact,
+            "location": location,
+        }
+
+    # ------------------------------------------------------------------ #
+    # get_users
+    # ------------------------------------------------------------------ #
+
+    def get_users(self) -> dict[str, _JsonDict]:
+        """Return users configured on the Proxmox node.
+
+        Reads from both the Proxmox access/users API and local /etc/passwd.
+        """
+        result: dict[str, _JsonDict] = {}
+        try:
+            pve_users = self._api.access.users.get() or []  # type: ignore[union-attr]
+        except Exception as exc:
+            logger.debug("Failed to fetch Proxmox users: %s", exc)
+            pve_users = []
+
+        for user in pve_users:
+            uid = user.get("userid", "")
+            if not uid:
+                continue
+            # Proxmox roles: Administrator -> 15, otherwise 1
+            groups = user.get("groups", "") or ""
+            level = 1
+            try:
+                roles = self._api.access.users(uid).get() or {}  # type: ignore[union-attr]
+                if "Administrator" in str(roles):
+                    level = 15
+            except Exception as exc:
+                logger.debug("Failed to fetch roles for user %s: %s", uid, exc)
+            result[uid] = {
+                "level": level,
+                "password": "",
+                "sshkeys": [],
+            }
+
+        # Merge local OS users from /etc/passwd
+        raw = self._exec_ssh_command("getent passwd 2>/dev/null || cat /etc/passwd")
+        for line in raw.splitlines():
+            parts = line.split(":")
+            if len(parts) < 7:
+                continue
+            uname, _, uid_str, *_ = parts
+            try:
+                uid_int = int(uid_str)
+            except ValueError:
+                continue
+            if uname not in result and uid_int < 1000 or uid_int == 0:
+                result[uname] = {
+                    "level": 15 if uid_int == 0 else 0,
+                    "password": "",
+                    "sshkeys": [],
+                }
+
+        return result
+
+    # ------------------------------------------------------------------ #
+    # Packages (Debian APT)
+    # ------------------------------------------------------------------ #
+
+    def get_packages(self) -> list[_JsonDict]:
+        """Return installed Debian packages with available-update info.
+
+        Installed list comes from ``dpkg-query`` via SSH (the Proxmox API
+        ``/apt/installed`` endpoint is not implemented on PVE 8.x).
+        Available updates come from the Proxmox API ``/apt/update``.
+        """
+        # Available updates from Proxmox API (keyed by package name)
+        upgradable: dict[str, str] = {}
+        try:
+            for upd in self._api.nodes(self._node_name).apt.update.get():
+                pkg = upd.get("Package", "")
+                if pkg:
+                    upgradable[pkg] = upd.get("Version", "")
+        except Exception as exc:
+            logger.debug("Failed to fetch available APT updates: %s", exc)
+
+        # Installed packages via SSH dpkg-query
+        raw = self._exec_ssh_command(
+            "dpkg-query -W -f="
+            "'${Package}\\t${Version}\\t${db:Status-Status}\\t${Installed-Size}"
+            "\\t${source:Package}\\t${source:Version}\\n'"
+            " 2>/dev/null"
+        )
+        result: list[_JsonDict] = []
+        for line in raw.splitlines():
+            parts = line.strip().split("\t")
+            if len(parts) < 2:
+                continue
+            name = parts[0]
+            version = parts[1] if len(parts) > 1 else ""
+            status = parts[2] if len(parts) > 2 else "installed"
+            size_kb = parts[3] if len(parts) > 3 else "0"
+            # Debian source package (differs from the binary for split packages,
+            # e.g. openssh-server → openssh). Needed for accurate OSV matching.
+            source_package = parts[4] if len(parts) > 4 and parts[4] else name
+            # And its version, which is a different number from this package's.
+            #
+            # OSV states Debian ranges in *source* versions, so a consumer given
+            # the source package and only the binary version compares two
+            # unrelated numbers: libldb2 is 2:2.11.0+samba4.22.11+dfsg-… while
+            # its source, samba, is 2:4.22.11+dfsg-…. Reporting the source
+            # without its version is worse than reporting neither, because it
+            # looks usable. Every package on all three Proxmox nodes was in that
+            # state — the format string never asked for the field.
+            #
+            # dpkg leaves it empty when it equals `Version`, and so does an
+            # older dpkg that does not know the field at all.
+            source_version = parts[5] if len(parts) > 5 and parts[5] else version
+            if not name or status != "installed":
+                continue
+            size_bytes = int(size_kb) * 1024 if size_kb.isdigit() else 0
+            result.append({
+                "name": name,
+                "version": version,
+                "installed": True,
+                "description": "",
+                "size": size_bytes,
+                "source": "pve",
+                "source_package": source_package,
+                "source_version": source_version,
+                "upgrade_version": upgradable.get(name, ""),
+            })
+        return result
+
+    # ------------------------------------------------------------------ #
+    # Device warnings
+    # ------------------------------------------------------------------ #
+
+    def get_device_warnings(self) -> list[_JsonDict]:
+        """Return warnings for the Proxmox node.
+
+        Currently detects:
+        - lldpd not installed (LLDP neighbor discovery unavailable)
+        - Available package updates (via Proxmox APT API)
+        - Missing / invalid subscription
+        """
+        warnings: list[_JsonDict] = []
+
+        # 0. LLDP daemon
+        try:
+            lldpd_path = self._exec_ssh_command("command -v lldpd 2>/dev/null").strip()
+            if not lldpd_path:
+                warnings.append({"code": "lldpd_not_installed"})
+        except Exception as exc:
+            logger.debug("Failed to check for lldpd: %s", exc)
+
+        # 1. Available package updates
+        try:
+            updates = self.get_available_updates()
+            if updates:
+                warnings.append({
+                    "code": "updates_available",
+                    "meta": {
+                        "count": len(updates),
+                        "packages": [u["name"] for u in updates],
+                    },
+                })
+        except Exception as exc:
+            logger.debug("Failed to check available updates: %s", exc)
+
+        # 2. Subscription status
+        try:
+            sub = self._get_node_subscription()
+            status = sub.get("status", "")
+            if status in ("NotFound", "Invalid", "Expired"):
+                warnings.append({"code": "no_subscription", "meta": {"status": status}})
+        except Exception as exc:
+            logger.debug("Failed to check subscription status: %s", exc)
+
+        return warnings
+
+    # ------------------------------------------------------------------ #
+    # Services (systemd)
+    # ------------------------------------------------------------------ #
+
+    def get_services(self) -> list[_JsonDict]:
+        """Return systemd services with running and enabled state.
+
+        Uses two ``systemctl`` invocations combined in a single SSH command:
+        - ``list-unit-files`` for the static enabled/disabled state
+        - ``list-units`` for the live running state
+        """
+        raw = self._exec_ssh_command(
+            "{ systemctl list-unit-files --type=service --no-pager --no-legend --full 2>/dev/null;"
+            " echo '---UNITS---';"
+            " systemctl list-units --type=service --all --no-pager --no-legend --full 2>/dev/null;"
+            " } || true"
+        )
+
+        # Parse enabled state from list-unit-files
+        enabled_map: dict[str, bool] = {}
+        section = "files"
+        for line in raw.splitlines():
+            if line.strip() == "---UNITS---":
+                section = "units"
+                continue
+            parts = line.strip().split(None, 1)
+            if len(parts) < 1:
+                continue
+            unit = parts[0].lstrip("\u25cf").strip()
+            if not unit.endswith(".service"):
+                continue
+            name = unit[: -len(".service")]
+            if section == "files":
+                state = parts[1].strip() if len(parts) > 1 else ""
+                enabled_map[name] = state in ("enabled", "enabled-runtime", "static")
+
+        # Parse running state from list-units
+        running_map: dict[str, bool] = {}
+        section = "files"
+        for line in raw.splitlines():
+            if line.strip() == "---UNITS---":
+                section = "units"
+                continue
+            if section != "units":
+                continue
+            parts = line.strip().lstrip("\u25cf").strip().split(None, 4)
+            if len(parts) < 4:
+                continue
+            unit = parts[0]
+            if not unit.endswith(".service"):
+                continue
+            name = unit[: -len(".service")]
+            sub_state = parts[3]
+            running_map[name] = sub_state == "running"
+
+        all_names = sorted(set(enabled_map) | set(running_map))
+        return [
+            {
+                "name": name,
+                "running": running_map.get(name, False),
+                "enabled": enabled_map.get(name, False),
+                "pid": 0,
+            }
+            for name in all_names
+        ]
+
+    def manage_service(self, name: str, action: str) -> _JsonDict:
+        """Start / stop / restart / enable / disable a systemd service."""
+        if not re.match(r'^[a-zA-Z0-9_\-\.@]+$', name):
+            raise ValueError(f"Invalid service name: {name!r}")
+        if action not in ('start', 'stop', 'restart', 'enable', 'disable'):
+            raise ValueError(f"Invalid action: {action!r}")
+        output = self._exec_ssh_command(f"systemctl {action} {name}.service 2>&1 || true")
+        return {"success": True, "output": output}
+
+    # ------------------------------------------------------------------ #
+    # Available updates
+    # ------------------------------------------------------------------ #
+
+    def get_available_updates(self) -> list[_JsonDict]:
+        """Return list of upgradable packages from the Proxmox APT API."""
+        updates: list[_JsonDict] = []
+        try:
+            for upd in self._api.nodes(self._node_name).apt.update.get():
+                pkg = upd.get("Package", "")
+                if not pkg:
+                    continue
+                updates.append({
+                    "name": pkg,
+                    "current_version": upd.get("OldVersion", ""),
+                    "new_version": upd.get("Version", ""),
+                })
+        except Exception as exc:
+            logger.debug("Failed to fetch available updates: %s", exc)
+        return sorted(updates, key=lambda u: u["name"])
+
+    def apply_updates(self, packages: list[str]) -> _JsonDict:
+        """Upgrade the given packages via ``apt-get install`` over SSH."""
+        for pkg in packages:
+            if not re.match(r'^[a-zA-Z0-9_\-\+\.]+$', pkg):
+                raise ValueError(f"Invalid package name: {pkg!r}")
+        pkg_args = " ".join(packages)
+        output = self._exec_ssh_command(
+            f"DEBIAN_FRONTEND=noninteractive apt-get install --only-upgrade -y {pkg_args} 2>&1 || true"
+        )
+        return {"success": True, "output": output}
+
+    # ------------------------------------------------------------------ #
+    # SNMP / Health
+    # ------------------------------------------------------------------ #
+
+    def get_snmp_config(self):
+        """Return SNMP agent config if snmpd is installed and running on the node.
+
+        Uses _exec_ssh_command (Proxmox API exec or SSH) to inspect the node.
+        Returns a SNMPConfigDict or None.
+        """
+        try:
+            from napalm_device_types.models import SNMPConfigDict
+        except ImportError:
+            return None
+
+        running = (
+            self._exec_ssh_command("systemctl is-active snmpd 2>/dev/null || true").strip()
+            == "active"
+        )
+        if not running:
+            return None
+
+        community = "public"
+        port = 161
+        try:
+            conf = self._exec_ssh_command(
+                "grep -E '^[[:space:]]*(ro|rw)?community' /etc/snmp/snmpd.conf 2>/dev/null | head -5"
+            )
+            for line in conf.splitlines():
+                parts = line.split()
+                if not parts:
+                    continue
+                kw = parts[0].lower()
+                if kw in ("rocommunity", "rwcommunity") and len(parts) >= 2:
+                    community = parts[1]
+                    break
+                elif kw == "com2sec" and len(parts) >= 4:
+                    community = parts[3]
+                    break
+        except Exception as exc:
+            logger.debug("Failed to parse snmpd.conf: %s", exc)
+
+        return SNMPConfigDict(running=True, community=community, port=port, version="2c")
+
+    def run_device_action(self, action: str) -> dict:
+        """Execute a named administrative action on the Proxmox node."""
+        if action == "fix_snmp":
+            return self._action_fix_snmp()
+        if action == "install_lldpd":
+            return self._action_install_lldpd()
+        raise NotImplementedError(f"Unknown action: {action!r}")
+
+    def _action_install_lldpd(self) -> dict:
+        """Install, enable and start lldpd on the Proxmox node.
+
+        Proxmox runs Debian/Linux underneath, so this is a plain apt install
+        followed by enabling the systemd service. lldpd's defaults (listen on
+        all interfaces) are sufficient to discover the directly-connected
+        switch via the management bridge (e.g. vmbr0).
+        """
+        lines: list[str] = []
+
+        install_out = self._exec_ssh_command(
+            "DEBIAN_FRONTEND=noninteractive apt-get install -y lldpd 2>&1 | tail -5"
+        )
+        lines.append(f"[install] {install_out.strip()[-200:]}")
+
+        enable_out = self._exec_ssh_command(
+            "systemctl enable --now lldpd 2>&1 || service lldpd start 2>&1 || true"
+        )
+        lines.append(f"[service] {enable_out.strip()[-200:]}")
+
+        verify = self._exec_ssh_command("command -v lldpd 2>/dev/null").strip()
+        success = bool(verify)
+        if success:
+            lines.append("[ok] lldpd installed. Neighbors will appear after a short warm-up period.")
+        else:
+            lines.append("[warn] lldpd does not appear to be installed after the attempt.")
+
+        return {"success": success, "output": "\n".join(lines)}
+
+    def _action_fix_snmp(self) -> dict:
+        """Install, configure and start snmpd on the Proxmox node.
+
+        Proxmox runs Debian/Linux underneath. _exec_ssh_command runs as root
+        (either via Proxmox API execute endpoint or SSH with root credentials),
+        so no sudo is needed.
+        """
+        import base64 as _b64
+        lines: list[str] = []
+
+        # 1. Install snmpd and snmp client tools
+        install_out = self._exec_ssh_command(
+            "DEBIAN_FRONTEND=noninteractive apt-get install -y snmpd snmp 2>&1 | tail -5"
+        )
+        lines.append(f"[install] {install_out.strip()[-200:]}")
+
+        # 2. Detect the IP this connection comes from (for firewall rule)
+        netork_ip = ""
+        try:
+            raw = self._exec_ssh_command(
+                "ss -tnp 2>/dev/null | awk '/sshd/{print $5}' | head -1 | cut -d: -f1"
+            ).strip()
+            if raw and raw not in ("", "0.0.0.0", "::", "127.0.0.1"):
+                netork_ip = raw
+        except Exception as exc:
+            logger.debug("Failed to detect network origin IP: %s", exc)
+
+        # 3. Write snmpd.conf via /tmp (no permission issues)
+        conf_str = (
+            "agentAddress udp:161\n"
+            "rocommunity public\n"
+            "sysLocation    Managed by netOrk\n"
+            "sysContact     netork@localhost\n"
+        )
+        conf_b64 = _b64.b64encode(conf_str.encode()).decode()
+        self._exec_ssh_command(f"echo {conf_b64} | base64 -d > /tmp/netork_snmpd.conf")
+        self._exec_ssh_command(
+            "mv /tmp/netork_snmpd.conf /etc/snmp/snmpd.conf && "
+            "chown root:root /etc/snmp/snmpd.conf && chmod 644 /etc/snmp/snmpd.conf"
+        )
+        verify = self._exec_ssh_command("cat /etc/snmp/snmpd.conf 2>/dev/null").strip()
+        if "agentAddress" in verify and "rocommunity" in verify:
+            lines.append("[config] Wrote /etc/snmp/snmpd.conf - agentAddress udp:161, rocommunity public.")
+        else:
+            lines.append(f"[warn] snmpd.conf write may have failed: {verify[:100]}")
+
+        # 4. Open firewall if ufw is present
+        if netork_ip:
+            try:
+                ufw = self._exec_ssh_command("command -v ufw 2>/dev/null").strip()
+                if ufw:
+                    parts = netork_ip.rsplit(".", 1)
+                    subnet = f"{parts[0]}.0/24" if len(parts) == 2 else netork_ip
+                    fw_out = self._exec_ssh_command(
+                        f"ufw allow from {subnet} to any port 161 proto udp 2>&1"
+                    )
+                    lines.append(f"[firewall/ufw] {fw_out.strip()[:200]}")
+            except Exception as exc:
+                lines.append(f"[firewall] skipped - {exc}")
+
+        # 5. Stop and restart snmpd cleanly (no DBus needed for stop+start)
+        self._exec_ssh_command(
+            "service snmpd stop 2>/dev/null; pkill -9 snmpd 2>/dev/null; true"
+        )
+        import time as _time
+        _time.sleep(1)
+        start_out = self._exec_ssh_command(
+            "service snmpd start 2>&1 || systemctl start snmpd 2>&1 || true"
+        )
+        lines.append(f"[service] {start_out.strip()[-200:]}")
+
+        # 6. Verify via local probe
+        _time.sleep(2)
+        probe_out = self._exec_ssh_command(
+            "snmpget -v2c -cpublic -t2 -r0 -Ov 127.0.0.1 1.3.6.1.2.1.1.1.0 2>&1 || true"
+        ).strip()
+        _snmp_types = ("STRING:", "INTEGER:", "OID:", "Timeticks:", "Hex-STRING:", "IpAddress:")
+        success = any(t in probe_out for t in _snmp_types)
+        if success:
+            lines.append("[ok] SNMP probe successful - community 'public' is working.")
+        else:
+            lines.append(f"[warn] SNMP probe failed - output: {probe_out[:200]}")
+
+        return {"success": success, "output": "\n".join(lines)}
+
+    # ------------------------------------------------------------------ #
+    # set_hostname
+    # ------------------------------------------------------------------ #
+
+    def set_hostname(self, new_hostname: str) -> None:
+        """Set the system hostname on the Proxmox node.
+
+        Performs all steps required for a clean rename on a Debian/Proxmox host:
+
+        1. ``/etc/hostname``  — short hostname only.
+        2. ``/etc/hosts``     — old hostname replaced by new (short or FQDN).
+        3. ``/etc/mailname``  — FQDN, if the file exists.
+        4. Postfix ``myhostname`` — updated via ``postconf -e`` if Postfix is
+           installed.
+        5. Runtime hostname  — applied immediately via ``hostname(1)`` so SSH
+           and the Proxmox API see the new name without a reboot.
+        6. ``/etc/pve/nodes/<old>`` → ``/etc/pve/nodes/<new>`` rename so
+           VM/CT configs are found after the reboot under the new node name.
+        7. Proxmox node TLS certificate — regenerated via
+           ``pvenode cert create --overwrite``.
+
+        **Important**: the Proxmox *node name* (shown in the web UI and stored
+        in ``/etc/pve/nodes/<name>/``) only changes after a full reboot.
+        Until then the web UI still shows the old node name, but the OS-level
+        hostname and the SSL certificate already reflect the new value.
+
+        Accepts a bare hostname (``pve-see``) or an FQDN
+        (``pve-see.see.local``).
+        """
+        import base64 as _b64
+
+        if "." in new_hostname:
+            short_hostname, domain = new_hostname.split(".", 1)
+            fqdn = new_hostname
+        else:
+            short_hostname = new_hostname
+            domain = None
+            fqdn = new_hostname
+
+        # Derive old short hostname for substitution in /etc/hosts
+        old_short = self._exec_ssh_command(
+            "cat /etc/hostname 2>/dev/null || hostname -s 2>/dev/null"
+        ).strip().split(".")[0]
+
+        # ── 1. /etc/hostname ─────────────────────────────────────────────
+        hostname_b64 = _b64.b64encode(f"{short_hostname}\n".encode()).decode()
+        self._exec_ssh_command(f"echo {hostname_b64} | base64 -d > /etc/hostname")
+
+        # ── 2. /etc/hosts ────────────────────────────────────────────────
+        # Read the file, substitute in Python (safe for all characters),
+        # write back via base64 to avoid shell-escaping issues.
+        if old_short and old_short != short_hostname:
+            hosts_raw = self._exec_ssh_command("cat /etc/hosts 2>/dev/null")
+            # Replace whole-word occurrences of the old short hostname.
+            # Both "hostname" and "hostname.domain" forms are covered because
+            # the new value is the full fqdn when a domain was given.
+            import re as _re
+            new_replace = fqdn if domain else short_hostname
+            hosts_new = _re.sub(
+                r"\b" + _re.escape(old_short) + r"\b",
+                new_replace,
+                hosts_raw,
+            )
+            hosts_b64 = _b64.b64encode(hosts_new.encode()).decode()
+            self._exec_ssh_command(
+                f"echo {hosts_b64} | base64 -d > /tmp/_netork_hosts"
+                f" && mv /tmp/_netork_hosts /etc/hosts"
+                f" && chmod 644 /etc/hosts"
+            )
+
+        # ── 3. /etc/mailname ─────────────────────────────────────────────
+        mailname_b64 = _b64.b64encode(f"{fqdn}\n".encode()).decode()
+        self._exec_ssh_command(
+            f"[ -f /etc/mailname ]"
+            f" && echo {mailname_b64} | base64 -d > /etc/mailname"
+            f" || true"
+        )
+
+        # ── 4. Postfix myhostname ─────────────────────────────────────────
+        self._exec_ssh_command(
+            f"command -v postconf >/dev/null 2>&1"
+            f" && postconf -e 'myhostname = {fqdn}'"
+            f" || true"
+        )
+
+        # ── 5. Apply hostname at runtime ─────────────────────────────────
+        self._exec_ssh_command(f"hostname '{short_hostname}'")
+
+        # ── 6. Migrate /etc/pve/nodes/<old> → /etc/pve/nodes/<new> ──────
+        # Proxmox stores VM and CT configs under /etc/pve/nodes/<nodename>/.
+        # This rename MUST happen before the reboot while pve-cluster is
+        # running and pmxcfs is mounted — pmxcfs supports the rename live.
+        # Without this step the node boots under the new hostname, finds an
+        # empty /etc/pve/nodes/<new>/ and all VMs appear missing.
+        if old_short and old_short != short_hostname:
+            pve_old = f"/etc/pve/nodes/{old_short}"
+            pve_new = f"/etc/pve/nodes/{short_hostname}"
+            migrate_out = self._exec_ssh_command(
+                f"if [ -d '{pve_old}' ] && [ ! -e '{pve_new}' ]; then"
+                f"  mv '{pve_old}' '{pve_new}'"
+                f"  && echo 'migrated {pve_old} -> {pve_new}';"
+                f"elif [ -d '{pve_new}' ]; then"
+                f"  echo 'target already exists, skipping migration';"
+                f"else"
+                f"  echo 'source {pve_old} not found, skipping migration';"
+                f"fi"
+            )
+            logger.info("Proxmox node dir migration: %s", migrate_out)
+
+        # ── 7. Regenerate Proxmox node TLS certificate ───────────────────
+        # Use pvenode cert create --overwrite rather than pvecm updatecerts -f.
+        # pvecm updatecerts -f restarts pve-cluster which briefly unmounts the
+        # cluster filesystem (/etc/pve) and can crash running VMs.
+        # pvenode cert create --overwrite only touches the node's own cert and
+        # restarts pveproxy (safe while VMs are running).
+        cert_out = self._exec_ssh_command(
+            "pvenode cert create --overwrite 1 2>&1"
+            " || { systemctl restart pveproxy 2>&1; echo 'restarted pveproxy'; }"
+            " || true"
+        )
+        logger.info("Proxmox cert regeneration: %s", cert_out[:200])
+
+        logger.info(
+            "Proxmox set_hostname: %s → %s (fqdn: %s). "
+            "Reboot required for node name to update in web UI / cluster.",
+            old_short, short_hostname, fqdn,
+        )
+
+    # ------------------------------------------------------------------ #
+    # _send_command — generic SSH command helper used by netOrk core
+    # ------------------------------------------------------------------ #
+
+    def _send_command(self, command: str) -> str:
+        """Execute *command* on the node and return its output.
+
+        Delegates to _exec_ssh_command so that netOrk's generic helpers
+        (e.g. the reboot action) work without knowing the driver internals.
+        """
+        return self._exec_ssh_command(command)
+
+    def get_disk_smart(self) -> dict:
+        """Return SMART health data for all disks on this Proxmox node.
+
+        Combines the disk list (model, size, wearout) with per-disk SMART
+        data (health, temperature, percentage used).
+
+        Returns a dict keyed by device path, e.g. {"/dev/nvme0n1": {...}}.
+        """
+        import re as _re
+
+        result: dict = {}
+        try:
+            disks = self._node_api().disks.list.get() or []
+        except Exception as exc:
+            logger.debug("Failed to list disks: %s", exc)
+            return result
+
+        for disk in disks:
+            dev = disk.get("devpath") or disk.get("dev")
+            if not dev:
+                continue
+            entry: dict = {
+                "model":   disk.get("model", ""),
+                "serial":  disk.get("serial", ""),
+                "type":    disk.get("type", ""),
+                "size":    disk.get("size", 0),
+                "health":  disk.get("health", "unknown").lower(),
+                "wearout": disk.get("wearout"),          # NVMe wear indicator 0-100
+                "temperature": None,
+                "percentage_used": None,
+                "available_spare": None,
+                "reallocated_sectors": None,
+                "power_on_hours": None,
+            }
+            try:
+                smart = self._node_api().disks.smart.get(disk=dev) or {}
+                # health from SMART endpoint may be more accurate
+                if smart.get("health"):
+                    entry["health"] = smart["health"].lower()
+
+                text = smart.get("text", "")
+                # Parse temperature
+                m = _re.search(r"Temperature[^:]*:\s*(\d+)\s*Celsius", text)
+                if m:
+                    entry["temperature"] = int(m.group(1))
+                # NVMe-specific
+                m = _re.search(r"Percentage Used:\s*(\d+)%", text)
+                if m:
+                    entry["percentage_used"] = int(m.group(1))
+                m = _re.search(r"Available Spare:\s*(\d+)%", text)
+                if m:
+                    entry["available_spare"] = int(m.group(1))
+                m = _re.search(r"Power On Hours:\s*([\d,]+)", text)
+                if m:
+                    entry["power_on_hours"] = int(m.group(1).replace(",", ""))
+                # HDD-specific SMART attributes
+                for attr in smart.get("attributes", []):
+                    name = attr.get("name", "").lower()
+                    raw  = attr.get("raw", "")
+                    try:
+                        raw_int = int(str(raw).split()[0])
+                    except (ValueError, TypeError):
+                        raw_int = None
+                    if "temperature" in name and raw_int is not None:
+                        entry["temperature"] = raw_int
+                    elif "reallocated" in name and "sector" in name and raw_int is not None:
+                        entry["reallocated_sectors"] = raw_int
+                    elif "power_on" in name and raw_int is not None:
+                        entry["power_on_hours"] = raw_int
+            except Exception as exc:
+                logger.debug("Failed to fetch SMART data for %s: %s", dev, exc)
+            result[dev] = entry
+
+        return result
+
+    def get_system_config(self) -> dict[str, Any]:
+        """Return system-level configuration for this Proxmox node.
+
+        Collected from ``/cluster/status`` and the node config API:
+
+        * ``cluster_name`` (str | None) — Proxmox cluster name; ``None`` when
+          the node is standalone (not part of a cluster).
+        * ``cluster_nodes`` (list[str]) — hostnames of all online cluster nodes.
+        * ``hostname`` (str) — this node's name as reported by the cluster.
+        * ``timezone`` (str | None) — e.g. ``"Europe/Berlin"``.
+        * ``ntp_servers`` (list[str]).
+        * ``ssh_port`` (int) — always 22 for Proxmox nodes.
+        * ``ssh_password_auth`` (bool) — ``False`` as a safe default.
+        """
+        cfg: dict[str, Any] = {
+            "cluster_name": None,
+            "cluster_nodes": [],
+            "hostname": self._node_name,
+            "timezone": None,
+            "ntp_servers": [],
+            "ssh_port": 22,
+            "ssh_password_auth": False,
+        }
+
+        # Cluster name and node list from /cluster/status
+        try:
+            status = self._api.cluster.status.get() or []
+            for entry in status:
+                if entry.get("type") == "cluster":
+                    cfg["cluster_name"] = entry.get("name")
+                elif entry.get("type") == "node" and entry.get("online"):
+                    cfg["cluster_nodes"].append(entry.get("name", ""))
+        except Exception as exc:
+            logger.debug("Failed to fetch cluster status for system config: %s", exc)
+
+        # Timezone from node time API
+        try:
+            time_cfg = self._node_api().time.get() or {}
+            cfg["timezone"] = time_cfg.get("timezone") or None
+        except Exception as exc:
+            logger.debug("Failed to fetch node time config: %s", exc)
+
+        return cfg

napalm_proxmox/utils.py

@@ -26,28 +26,6 @@ _MAC_RE = re.compile(
 
 
 def normalize_mac(mac: str) -> str:
-    """Return a colon-separated, lower-case MAC address, or '' on failure."""
-    if not mac:
-        return ""
-    try:
-        return str(EUI(mac, dialect=_ColonDialect()))
-    except (AddrFormatError, ValueError):
-        return mac.lower()
-
-
-class _ColonDialect(EUI):
-    """EUI dialect that formats as aa:bb:cc:dd:ee:ff."""
-
-    word_sep = ":"
-    word_fmt = "%.2x"
-
-    def __new__(cls):  # type: ignore[override]
-        from netaddr import mac_unix_expanded
-
-        return mac_unix_expanded
-
-
-def normalize_mac(mac: str) -> str:  # noqa: F811
     """Return lower-case colon-separated MAC or empty string."""
     if not mac:
         return ""

napalm_proxmox/vm_contract_mixin.py

@@ -0,0 +1,193 @@
+"""HypervisorDriver contract methods for Proxmox VE: power actions and VM config.
+
+``power_vm`` stays for callers that already use it; these are what a
+hypervisor-neutral caller talks to. They raise instead of returning a
+``{"success": ...}`` dict, and block until Proxmox reports the task finished.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from napalm_device_types.models import (
+    VMConfigDict,
+    VMDiskDict,
+    VMNICDict,
+    VMPassthroughDict,
+)
+
+_JsonDict = dict[str, Any]
+
+_POWER_TIMEOUT = 120
+_VM_DISK_KEY = re.compile(r"^(scsi|ide|virtio|sata)\d+$|^efidisk\d+$|^tpmstate\d+$")
+_CT_DISK_KEY = re.compile(r"^rootfs$|^mp\d+$")
+_NET_KEY = re.compile(r"^net\d+$")
+_PASSTHROUGH_KEY = re.compile(r"^(hostpci|usb)\d+$")
+_NIC_MODELS = {"virtio", "e1000", "e1000e", "vmxnet3", "rtl8139", "ne2k_pci"}
+_SIZE = re.compile(r"^(\d+(?:\.\d+)?)([KMGT]?)$", re.I)
+_GB_PER_UNIT = {"K": 1 / 1024**2, "M": 1 / 1024, "G": 1, "T": 1024, "": 1}
+
+
+def _options(value: str) -> tuple[str, dict[str, str]]:
+    """Split ``"volume,key=val,..."`` into the leading bare part and its options."""
+    head = ""
+    opts: dict[str, str] = {}
+    for part in str(value).split(","):
+        if "=" in part:
+            k, v = part.split("=", 1)
+            opts[k.strip().lower()] = v.strip()
+        elif not head:
+            head = part.strip()
+    return head, opts
+
+
+def _size_gb(raw: str) -> int:
+    m = _SIZE.match(raw or "")
+    if not m:
+        return 0
+    return int(float(m.group(1)) * _GB_PER_UNIT[m.group(2).upper()])
+
+
+def _boot_order(cfg: _JsonDict) -> list[str]:
+    boot = str(cfg.get("boot", "") or "")
+    if boot.startswith("order="):
+        return [d for d in boot[len("order=") :].split(";") if d]
+    bootdisk = cfg.get("bootdisk")
+    return [bootdisk] if bootdisk else []
+
+
+def _disks(cfg: _JsonDict, vm_type: str, boot_order: list[str]) -> list[VMDiskDict]:
+    key_re = _VM_DISK_KEY if vm_type == "vm" else _CT_DISK_KEY
+    disks: list[VMDiskDict] = []
+    for key in sorted(cfg, key=lambda k: (k != "rootfs", k)):
+        if not key_re.match(key):
+            continue
+        value = str(cfg[key] or "")
+        head, opts = _options(value)
+        if opts.get("media") == "cdrom" or head in ("none", "0", ""):
+            continue
+        disks.append(
+            {
+                "device": key,
+                "storage": head.split(":", 1)[0],
+                "size": _size_gb(opts.get("size", "")),
+                "format": opts.get("format", ""),
+                "bootable": key in boot_order,
+            }
+        )
+    return disks
+
+
+def _nic(key: str, value: str) -> VMNICDict:
+    _, opts = _options(value)
+    model = next((m for m in _NIC_MODELS if m in opts), opts.get("type", ""))
+    mac = opts.get(model, "") if model in _NIC_MODELS else opts.get("hwaddr", "")
+    tag = opts.get("tag", "")
+    return {
+        "device": key,
+        "mac": mac.upper(),
+        "model": model,
+        "bridge": opts.get("bridge", ""),
+        "vlan_id": int(tag) if tag.isdigit() else 0,
+    }
+
+
+def _passthrough(cfg: _JsonDict) -> list[VMPassthroughDict]:
+    return [
+        {"slot": key, "kind": "pci" if key.startswith("hostpci") else "usb", "config": str(val)}
+        for key, val in sorted(cfg.items())
+        if _PASSTHROUGH_KEY.match(key)
+    ]
+
+
+def parse_vm_config(vmid: str, vm_type: str, cfg: _JsonDict) -> VMConfigDict:
+    """Turn a raw ``/qemu/{id}/config`` or ``/lxc/{id}/config`` into a VMConfigDict."""
+    is_vm = vm_type == "vm"
+    cores = int(cfg.get("cores", 1) or 1)
+    sockets = int(cfg.get("sockets", 1) or 1) if is_vm else 1
+    boot_order = _boot_order(cfg)
+    tags = str(cfg.get("tags", "") or "")
+    name_key = "name" if is_vm else "hostname"
+    result: VMConfigDict = {
+        "name": cfg.get(name_key) or f"{'vm' if is_vm else 'ct'}-{vmid}",
+        "vmid": vmid,
+        "vcpus": cores * sockets,
+        "memory": int(cfg.get("memory", 0) or 0),
+        "os_type": cfg.get("ostype", ""),
+        "boot_order": boot_order,
+        "disks": _disks(cfg, vm_type, boot_order),
+        "nics": [_nic(k, str(v)) for k, v in sorted(cfg.items()) if _NET_KEY.match(k)],
+        "description": cfg.get("description", ""),
+        "tags": [t for t in re.split(r"[;,\s]+", tags) if t],
+        "passthrough": _passthrough(cfg),
+    }
+    if is_vm:
+        result["cpu_type"] = str(cfg.get("cpu", "kvm64")).split(",")[0].removeprefix("cputype=")
+        result["sockets"] = sockets
+        result["cores_per_socket"] = cores
+        result["firmware"] = "efi" if cfg.get("bios") == "ovmf" else "bios"
+        if cfg.get("machine"):
+            result["machine"] = cfg["machine"]
+    return result
+
+
+class ProxmoxVMContractMixin:
+    """HypervisorDriver's VM methods on top of the Proxmox node API."""
+
+    def _resolve_vm(self, name: str) -> tuple[int, str]:
+        """Find a guest by vmid or display name; return ``(vmid, "vm"|"container")``."""
+        node = self._node_api()
+        for vm_type, listing in (("vm", node.qemu), ("container", node.lxc)):
+            for guest in listing.get() or []:
+                if str(guest.get("vmid")) == name or guest.get("name") == name:
+                    return int(guest["vmid"]), vm_type
+        raise ValueError(f"No VM or container named or numbered {name!r}")
+
+    def _guest_api(self, vmid: int, vm_type: str) -> Any:
+        node = self._node_api()
+        return node.qemu(vmid) if vm_type == "vm" else node.lxc(vmid)
+
+    def _run_power(self, vmid: int, vm_type: str, action: str) -> None:
+        try:
+            upid = getattr(self._guest_api(vmid, vm_type).status, action).post()
+        except Exception as exc:
+            raise RuntimeError(f"{action} of {vm_type} {vmid} failed: {exc}") from exc
+        if upid:
+            self._wait_for_task(upid, timeout=_POWER_TIMEOUT)
+
+    def start_vm(self, name: str) -> None:
+        self._run_power(*self._resolve_vm(name), "start")
+
+    def stop_vm(self, name: str, force: bool = False) -> None:
+        self._run_power(*self._resolve_vm(name), "stop" if force else "shutdown")
+
+    def reboot_vm(self, name: str, force: bool = False) -> None:
+        vmid, vm_type = self._resolve_vm(name)
+        if not force:
+            self._run_power(vmid, vm_type, "reboot")
+        elif vm_type == "vm":
+            self._run_power(vmid, vm_type, "reset")
+        else:
+            self._run_power(vmid, vm_type, "stop")
+            self._run_power(vmid, vm_type, "start")
+
+    def suspend_vm(self, name: str) -> None:
+        vmid, vm_type = self._resolve_vm(name)
+        if vm_type != "vm":
+            raise RuntimeError(f"Proxmox cannot suspend container {vmid}")
+        self._run_power(vmid, vm_type, "suspend")
+
+    def get_vm_config(self, name: str) -> VMConfigDict:
+        vmid, vm_type = self._resolve_vm(name)
+        cfg = self._guest_api(vmid, vm_type).config.get() or {}
+        return parse_vm_config(str(vmid), vm_type, cfg)
+
+    # -- the node itself --------------------------------------------------------
+
+    def reboot_host(self) -> None:
+        """Restart this Proxmox node through the API (no SSH involved)."""
+        try:
+            self._node_api().status.post(command="reboot")
+        except Exception as exc:
+            raise RuntimeError(f"Reboot of node {self._node_name!r} refused: {exc}") from exc

napalm_proxmox/vm_mixin.py

@@ -0,0 +1,396 @@
+# Copyright 2025 The NetOrk Project Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""VM/container NAPALM getters for Proxmox VE nodes."""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from napalm_proxmox import utils
+
+logger = logging.getLogger(__name__)
+
+_JsonDict = dict[str, Any]
+
+
+class ProxmoxVMMixin:
+    """Mixin providing VM and container NAPALM methods."""
+
+    def get_vm_interfaces(
+        self, vmid: int, vm_type: str
+    ) -> tuple[dict[str, _JsonDict], bool, bool]:
+        """Return network interfaces for a single VM or LXC container.
+
+        Returns a 3-tuple ``(interfaces, agent_running, agent_enabled)``:
+
+        * ``interfaces``    – dict keyed by interface name, each with
+          NAPALM-compatible fields plus ``ipv4``, ``bridge``, and ``tag``.
+        * ``agent_running`` – True if the QEMU Guest Agent responded during
+          this call (always False for LXC).
+        * ``agent_enabled`` – True if the QEMU Guest Agent is enabled in the
+          VM's Proxmox config (always False for LXC).
+
+        LXC  : uses ``/nodes/{node}/lxc/{vmid}/interfaces`` + LXC config
+        QEMU : tries QEMU guest agent first, falls back to VM config parsing.
+               In both paths the VM config is fetched to derive bridge/tag.
+        """
+        _NET_MODELS = {"virtio", "e1000", "e1000e", "vmxnet3", "rtl8139", "ne2k_pci"}
+
+        def _parse_net_entry(val_str: str) -> tuple[str, str, int | None]:
+            """Parse a Proxmox net config value → (mac_upper, bridge, tag|None)."""
+            mac = bridge = ""
+            tag: int | None = None
+            for part in str(val_str).split(","):
+                if "=" not in part:
+                    continue
+                k, v = part.split("=", 1)
+                k = k.strip().lower()
+                if k in _NET_MODELS:
+                    mac = v.strip()
+                elif k == "bridge":
+                    bridge = v.strip()
+                elif k == "tag":
+                    try:
+                        tag = int(v.strip())
+                    except ValueError:
+                        pass
+            return mac.upper() if mac else "", bridge, tag
+
+        interfaces: dict[str, _JsonDict] = {}
+
+        if vm_type == "container":
+            # Build iface_name → (bridge, tag) from LXC config
+            # LXC net entries look like: net0=name=eth0,bridge=vmbr40,tag=40,...
+            lxc_net_map: dict[str, tuple[str, int | None]] = {}
+            try:
+                config = self._node_api().lxc(vmid).config.get() or {}
+                net_re = re.compile(r"^net(\d+)$")
+                for key, val in config.items():
+                    if not net_re.match(key):
+                        continue
+                    iface_name = ""
+                    bridge = ""
+                    tag: int | None = None
+                    for part in str(val).split(","):
+                        if "=" not in part:
+                            continue
+                        k, v = part.split("=", 1)
+                        k = k.strip().lower()
+                        if k == "name":
+                            iface_name = v.strip()
+                        elif k == "bridge":
+                            bridge = v.strip()
+                        elif k == "tag":
+                            try:
+                                tag = int(v.strip())
+                            except ValueError:
+                                pass
+                    if iface_name:
+                        lxc_net_map[iface_name] = (bridge, tag)
+            except Exception as exc:
+                logger.debug("get_vm_interfaces: LXC %s config failed: %s", vmid, exc)
+
+            try:
+                for iface in (self._node_api().lxc(vmid).interfaces.get() or []):
+                    name = iface.get("name", "")
+                    if not name or name == "lo":
+                        continue
+                    mac = iface.get("hwaddr", "")
+                    ipv4 = ""
+                    inet = iface.get("inet", "")
+                    if inet:
+                        ipv4 = inet.split("/")[0]
+                    bridge, tag = lxc_net_map.get(name, ("", None))
+                    interfaces[name] = {
+                        "is_up": True,
+                        "is_enabled": True,
+                        "description": bridge,
+                        "mac_address": mac.upper() if mac else "",
+                        "speed": -1,
+                        "mtu": 1500,
+                        "last_flapped": -1.0,
+                        "ipv4": ipv4,
+                        "bridge": bridge,
+                        "tag": tag,
+                    }
+            except Exception as exc:
+                logger.debug("get_vm_interfaces: LXC %s ifaces failed: %s", vmid, exc)
+
+            # LXC containers do not use QEMU Guest Agent
+            return interfaces, False, False
+
+        else:
+            # QEMU: pre-fetch VM config to build MAC → (bridge, tag) map and
+            # to check whether the QEMU Guest Agent is enabled.
+            mac_to_net: dict[str, tuple[str, int | None]] = {}  # mac_upper → (bridge, tag)
+            net_idx_map: dict[str, tuple[str, str, int | None]] = {}  # "netN" → (mac, bridge, tag)
+            agent_enabled = False
+            try:
+                config = self._node_api().qemu(vmid).config.get() or {}
+                # Proxmox stores the agent setting as agent=1, agent=0, or
+                # agent=enabled=1[,fstrim_cloned_disks=1,...]
+                raw_agent = str(config.get("agent", "0"))
+                # Treat any truthy value ("1", "enabled=1", ...) as enabled
+                agent_enabled = bool(
+                    raw_agent.strip() in ("1", "true")
+                    or raw_agent.startswith("enabled=1")
+                    or raw_agent.startswith("1,")
+                )
+                net_re = re.compile(r"^net(\d+)$")
+                for key, val in config.items():
+                    m = net_re.match(key)
+                    if not m:
+                        continue
+                    mac, bridge, tag = _parse_net_entry(val)
+                    iface_key = f"net{m.group(1)}"
+                    net_idx_map[iface_key] = (mac, bridge, tag)
+                    if mac:
+                        mac_to_net[mac] = (bridge, tag)
+            except Exception as exc:
+                logger.debug("get_vm_interfaces: QEMU %s config fetch failed: %s", vmid, exc)
+
+            # Try guest agent first
+            agent_ok = False
+            try:
+                agent_result = self._node_api().qemu(vmid).agent("network-get-interfaces").get()
+                for iface in (agent_result or {}).get("result", []):
+                    name = iface.get("name", "")
+                    if not name or name == "lo":
+                        continue
+                    mac = (iface.get("hardware-address", "") or "").upper()
+                    ipv4 = ""
+                    for addr in iface.get("ip-addresses", []):
+                        if addr.get("ip-address-type") == "ipv4":
+                            ipv4 = addr.get("ip-address", "")
+                            break
+                    bridge, tag = mac_to_net.get(mac, ("", None))
+                    interfaces[name] = {
+                        "is_up": True,
+                        "is_enabled": True,
+                        "description": bridge,
+                        "mac_address": mac,
+                        "speed": -1,
+                        "mtu": 1500,
+                        "last_flapped": -1.0,
+                        "ipv4": ipv4,
+                        "bridge": bridge,
+                        "tag": tag,
+                    }
+                agent_ok = bool(interfaces)
+            except Exception as exc:
+                logger.debug("QEMU guest agent network-get-interfaces failed: %s", exc)
+
+            if not agent_ok:
+                # Fall back to config-only (gives MAC + bridge + tag, no IP)
+                for iface_key, (mac, bridge, tag) in net_idx_map.items():
+                    interfaces[iface_key] = {
+                        "is_up": False,
+                        "is_enabled": True,
+                        "description": bridge,
+                        "mac_address": mac,
+                        "speed": -1,
+                        "mtu": 1500,
+                        "last_flapped": -1.0,
+                        "ipv4": "",
+                        "bridge": bridge,
+                        "tag": tag,
+                    }
+
+            return interfaces, agent_ok, agent_enabled
+
+    def get_vms(self) -> list[_JsonDict]:
+        """Return all VMs (QEMU) and containers (LXC) on this node.
+
+        Each entry contains:
+        * vmid (str)        - Proxmox VM/container ID, e.g. ``"100"``
+        * name (str)        - display name
+        * type (str)        - ``"vm"`` or ``"container"``
+        * status (str)      - ``"running"``, ``"stopped"``, etc.
+        * vcpus (int)       - allocated vCPUs
+        * memory (int)      - configured RAM in megabytes
+        * cpu_usage (float) - current CPU utilisation 0.0–1.0 (from last stats cycle)
+        * memory_usage (int)- current RSS in megabytes
+        * uptime (int)      - uptime in seconds (0 if stopped)
+        * node (str)        - cluster node name
+        * interfaces (dict) - network interfaces (NAPALM format + ipv4 field)
+        * ipv4 (str)        - primary IPv4 address (empty string if unknown)
+        """
+        result: list[_JsonDict] = []
+
+        # QEMU VMs
+        try:
+            for vm in (self._node_api().qemu.get() or []):
+                vmid = int(vm.get("vmid", 0))
+                name = vm.get("name", f"vm-{vmid}")
+                status = vm.get("status", "unknown")
+                cpu_usage = float(vm.get("cpu", 0.0) or 0.0)
+                uptime = int(vm.get("uptime", 0) or 0)
+
+                # mem/maxmem are in bytes
+                maxmem_bytes = int(vm.get("maxmem", 0) or 0)
+                mem_bytes = int(vm.get("mem", 0) or 0)
+                memory_mb = maxmem_bytes // (1024 * 1024)
+                memory_usage_mb = mem_bytes // (1024 * 1024)
+
+                # vcpus can be in "cpus" key for running VMs
+                vcpus = int(vm.get("cpus", vm.get("vcpus", 0)) or 0)
+
+                interfaces, agent_running, agent_enabled = self.get_vm_interfaces(vmid, "vm")
+                ipv4 = next(
+                    (iface["ipv4"] for iface in interfaces.values() if iface.get("ipv4")),
+                    "",
+                )
+
+                disks, onboot = self._get_vm_disk_and_boot(vmid, "qemu")
+                result.append({
+                    "vmid": str(vmid),
+                    "name": name,
+                    "type": "vm",
+                    "status": status,
+                    "vcpus": vcpus,
+                    "memory": memory_mb,
+                    "cpu_usage": round(cpu_usage, 4),
+                    "memory_usage": memory_usage_mb,
+                    "uptime": uptime,
+                    "node": self._node_name,
+                    "interfaces": interfaces,
+                    "ipv4": ipv4,
+                    "agent_enabled": agent_enabled,
+                    "agent_running": agent_running,
+                    "disks": disks,
+                    "onboot": onboot,
+                })
+        except Exception as exc:
+            logger.warning("get_vms: failed to list QEMU VMs: %s", exc)
+
+        # LXC containers
+        try:
+            for ct in (self._node_api().lxc.get() or []):
+                vmid = int(ct.get("vmid", 0))
+                name = ct.get("name", f"ct-{vmid}")
+                status = ct.get("status", "unknown")
+                cpu_usage = float(ct.get("cpu", 0.0) or 0.0)
+                uptime = int(ct.get("uptime", 0) or 0)
+
+                maxmem_bytes = int(ct.get("maxmem", 0) or 0)
+                mem_bytes = int(ct.get("mem", 0) or 0)
+                memory_mb = maxmem_bytes // (1024 * 1024)
+                memory_usage_mb = mem_bytes // (1024 * 1024)
+
+                vcpus = int(ct.get("cpus", 0) or 0)
+
+                interfaces, agent_running, agent_enabled = self.get_vm_interfaces(vmid, "container")
+                ipv4 = next(
+                    (iface["ipv4"] for iface in interfaces.values() if iface.get("ipv4")),
+                    "",
+                )
+
+                disks, onboot = self._get_vm_disk_and_boot(vmid, "lxc")
+                result.append({
+                    "vmid": str(vmid),
+                    "name": name,
+                    "type": "container",
+                    "status": status,
+                    "vcpus": vcpus,
+                    "memory": memory_mb,
+                    "cpu_usage": round(cpu_usage, 4),
+                    "memory_usage": memory_usage_mb,
+                    "uptime": uptime,
+                    "node": self._node_name,
+                    "interfaces": interfaces,
+                    "ipv4": ipv4,
+                    "agent_enabled": agent_enabled,
+                    "agent_running": agent_running,
+                    "disks": disks,
+                    "onboot": onboot,
+                })
+        except Exception as exc:
+            logger.warning("get_vms: failed to list LXC containers: %s", exc)
+
+        return sorted(result, key=lambda x: int(x["vmid"]))
+
+    # Disk-key prefixes for QEMU: scsi, virtio, ide, sata (exclude cdrom/none entries)
+    _DISK_KEYS_VM = re.compile(r"^(scsi|virtio|ide|sata)\d+$")
+    # Disk-key prefix for LXC: rootfs, mp (mount points)
+    _DISK_KEYS_CT = re.compile(r"^(rootfs|mp\d+)$")
+
+    def _get_vm_disk_and_boot(
+        self, vmid: int, vm_type: str
+    ) -> tuple[list[dict], bool]:
+        """Return (disks, onboot) for a VM or container.
+
+        Fetches config from /nodes/{node}/{qemu|lxc}/{vmid}/config.
+        Each disk entry is a dict with 'name' and 'size_mb'.
+        Returns ([], False) on any error.
+        """
+        try:
+            if vm_type == "qemu":
+                cfg = self._node_api().qemu(vmid).config.get() or {}
+                disk_re = self._DISK_KEYS_VM
+            else:
+                cfg = self._node_api().lxc(vmid).config.get() or {}
+                disk_re = self._DISK_KEYS_CT
+
+            onboot = bool(int(cfg.get("onboot", 0) or 0))
+
+            disks: list[dict] = []
+            for key, value in sorted(cfg.items()):
+                if not disk_re.match(key):
+                    continue
+                val_str = str(value or "")
+                # Skip CD-ROM / none entries
+                if "media=cdrom" in val_str or val_str.startswith("none"):
+                    continue
+                # Extract size=NNX from the value string
+                m = re.search(r"\bsize=(\d+)([GMK]?)", val_str, re.I)
+                if not m:
+                    continue
+                num = int(m.group(1))
+                unit = m.group(2).upper()
+                if unit == "G" or unit == "":
+                    size_mb = num * 1024
+                elif unit == "M":
+                    size_mb = num
+                elif unit == "K":
+                    size_mb = num // 1024
+                else:
+                    size_mb = num * 1024
+                disks.append({"name": key, "size_mb": size_mb})
+
+            return disks, onboot
+        except Exception as exc:
+            logger.debug("Failed to fetch disk/boot config for vmid %s: %s", vmid, exc)
+            return [], False
+
+    _POWER_ACTIONS_VM = {'start', 'stop', 'shutdown', 'reboot', 'reset'}
+    _POWER_ACTIONS_CT = {'start', 'stop', 'shutdown', 'reboot'}
+
+    def power_vm(self, vmid: int, vm_type: str, action: str) -> dict:
+        """Send a power action to a VM or container on this node.
+
+        Supported actions for VMs:    start, stop, shutdown, reboot, reset
+        Supported actions for containers: start, stop, shutdown, reboot
+        """
+        allowed = self._POWER_ACTIONS_VM if vm_type == 'vm' else self._POWER_ACTIONS_CT
+        if action not in allowed:
+            return {"success": False, "error": f"Action '{action}' not supported for {vm_type} (allowed: {sorted(allowed)})"}
+        try:
+            vm_api = self._node_api().qemu(vmid) if vm_type == 'vm' else self._node_api().lxc(vmid)
+            task_id = getattr(vm_api.status, action).post()
+            return {"success": True, "task_id": task_id or ""}
+        except Exception as exc:
+            return {"success": False, "error": str(exc)}

napalm_proxmox/vm_provision_mixin.py

@@ -0,0 +1,804 @@
+"""VM provisioning mixin for Proxmox — creates, destroys, and monitors VMs via Cloud-Init."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import logging
+import re
+import time
+import yaml
+from typing import Any, Dict, List
+from urllib.parse import quote
+
+from napalm_device_types.models import (
+    NetworkTargetDict,
+    StorageTargetDict,
+    VMProvisionResultDict,
+    VMStatusDict,
+)
+
+_logger = logging.getLogger(__name__)
+
+# Downloaded cloud images are cached here on the hypervisor node, keyed by
+# filename, so provisioning multiple VMs from the same image only pays the
+# download cost once.
+_IMAGE_CACHE_DIR = "/var/lib/vz/template/netork-images"
+
+# Proxmox reads an import volume's format off its extension and accepts only
+# these. Ubuntu ships its qcow2 cloud images as ".img", so that is stored as
+# qcow2: if an .img is really raw, the import fails loudly, whereas guessing
+# raw for a qcow2 would attach the qcow2 container as a raw disk silently.
+_IMPORT_EXTENSIONS = {"qcow2": "qcow2", "raw": "raw", "vmdk": "vmdk", "img": "qcow2"}
+
+# Characters Proxmox keeps in a content file name (PVE::Storage's
+# SAFE_CHAR_CLASS_RE); anything else it would rewrite behind our back.
+_UNSAFE_FILENAME_CHARS = re.compile(r"[^A-Za-z0-9\-.+=_]")
+
+
+def _url_key(image_url: str) -> str:
+    """Short hash of the full URL — Ubuntu and others publish a new build
+    under the same basename every day, so the basename alone is no cache key."""
+    return hashlib.sha256(image_url.encode()).hexdigest()[:12]
+
+
+def _split_checksum(image_checksum: str) -> tuple[str, str]:
+    """``"<algo>:<hex>"`` as ``(algo, hex)``; the algorithm defaults to sha256."""
+    algo, _, expected = image_checksum.partition(":")
+    return (algo or "sha256").lower(), expected
+
+
+def _import_volume_name(image_url: str) -> str | None:
+    """The file name *image_url* gets in an import storage.
+
+    None when Proxmox cannot import the image's type at all (compressed,
+    ISO, no extension) — provisioning then downloads it over SSH as before.
+    """
+    basename = image_url.rstrip("/").rsplit("/", 1)[-1]
+    stem, dot, ext = basename.rpartition(".")
+    extension = _IMPORT_EXTENSIONS.get(ext.lower()) if dot and stem else None
+    if extension is None:
+        return None
+    safe_stem = _UNSAFE_FILENAME_CHARS.sub("_", stem)
+    return f"netork-{_url_key(image_url)}-{safe_stem}.{extension}"
+
+
+class ProxmoxVMProvisionMixin:
+    """Mixin to add VM provisioning to ProxmoxDriver."""
+
+    def _run_node_command(self, command: str, timeout: int) -> str:
+        """
+        Execute a shell command on the Proxmox node via SSH, raising on failure.
+
+        Unlike ``_exec_ssh_command`` (best-effort, fixed timeout, swallows
+        errors), this is for critical provisioning steps — image download,
+        disk import — where a non-zero exit or a caller-specific timeout must
+        surface as a hard failure rather than an empty string.
+        """
+        import paramiko
+
+        if self._ssh_client is None:
+            ssh_user = self._ssh_username or self.username
+            ssh_pass = self._ssh_password or self.password
+            ssh_pkey = None
+            if self._ssh_key and not ssh_pass:
+                from io import StringIO as _StringIO
+
+                ssh_pkey = paramiko.RSAKey.from_private_key(_StringIO(self._ssh_key))
+            self._ssh_client = paramiko.SSHClient()
+            self._ssh_client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+            connect_kwargs: Dict[str, Any] = {
+                "hostname": self.hostname,
+                "port": 22,
+                "username": ssh_user,
+                "timeout": self.timeout,
+            }
+            if ssh_pkey:
+                connect_kwargs["pkey"] = ssh_pkey
+            else:
+                connect_kwargs["password"] = ssh_pass
+            self._ssh_client.connect(**connect_kwargs)
+
+        _, stdout, stderr = self._ssh_client.exec_command(command, timeout=timeout)
+        exit_status = stdout.channel.recv_exit_status()
+        out = stdout.read().decode().strip()
+        err = stderr.read().decode().strip()
+        if exit_status != 0:
+            raise RuntimeError(f"Command failed (exit {exit_status}): {command}\n{err or out}")
+        return out
+
+    def _download_cloud_image(
+        self, image_url: str, image_checksum: str | None, timeout: int
+    ) -> str:
+        """
+        Download image_url to the node's image cache dir if not already present.
+
+        Returns the local path on the hypervisor node. The cache filename is
+        prefixed with a hash of the *full* URL, not just its basename —
+        Ubuntu (and others) publish per-build URLs that change daily under a
+        stable basename (e.g. .../release-20260713/ubuntu-26.04-server-
+        cloudimg-amd64.img), so keying the cache on the basename alone let a
+        stale previous-day build satisfy the "already cached" check and fail
+        checksum verification against today's expected hash.
+
+        Verifies image_checksum (format "<algo>:<hex>", e.g. "sha256:abc123...")
+        if given. On mismatch, removes the bad file and retries the download
+        once (covers a corrupted/partial transfer or a stale same-keyed file)
+        before raising.
+        """
+        filename = image_url.rstrip("/").rsplit("/", 1)[-1]
+        local_path = f"{_IMAGE_CACHE_DIR}/{_url_key(image_url)}-{filename}"
+
+        algo, expected = _split_checksum(image_checksum or "")
+
+        max_attempts = 2
+        for attempt in range(1, max_attempts + 1):
+            exists = self._run_node_command(
+                f"mkdir -p {_IMAGE_CACHE_DIR} && test -f {local_path} "
+                f"&& echo EXISTS || echo MISSING",
+                timeout=30,
+            )
+            if "EXISTS" not in exists:
+                _logger.info(f"Downloading cloud image {image_url} -> {local_path}")
+                self._run_node_command(
+                    f"wget -q -O {local_path}.tmp '{image_url}' "
+                    f"&& mv {local_path}.tmp {local_path}",
+                    timeout=timeout,
+                )
+
+            if not image_checksum:
+                return local_path
+
+            actual = self._run_node_command(
+                f"{algo}sum {local_path} | awk '{{print $1}}'", timeout=60
+            )
+            if actual.lower() == expected.lower():
+                return local_path
+
+            # Remove the bad file so the next attempt re-downloads instead of
+            # reusing it.
+            self._run_node_command(f"rm -f {local_path}", timeout=30)
+            if attempt == max_attempts:
+                raise RuntimeError(
+                    f"Checksum mismatch for {image_url}: expected {expected}, got {actual}"
+                )
+            _logger.warning(
+                f"Checksum mismatch for {image_url} on attempt {attempt}/{max_attempts} "
+                "— retrying download"
+            )
+
+        raise AssertionError("unreachable")  # loop always returns or raises above
+
+    def _find_import_storage(self) -> str | None:
+        """The first storage on this node that accepts content "import".
+
+        Such a storage (Proxmox 8.2+) can take a cloud image straight from its
+        URL. Inactive storages (typically a share that is not mounted) are
+        skipped rather than failed on: the SSH path still works without them.
+        Node-scoped for the same reason as _find_default_image_storage.
+        """
+        for storage in self._node_api().storage.get():
+            content = storage.get("content", "").split(",")
+            if "import" not in content:
+                continue
+            if storage.get("enabled", 1) == 0 or storage.get("active", 1) == 0:
+                continue
+            return storage["storage"]
+        return None
+
+    def _import_cloud_image(
+        self,
+        storage: str,
+        filename: str,
+        image_url: str,
+        image_checksum: str | None,
+        timeout: int,
+    ) -> str:
+        """Have Proxmox download *image_url* into *storage*; returns the volume id.
+
+        Proxmox runs the download as a task and verifies the checksum itself.
+        A file already in the storage is reused — the name carries a hash of
+        the full URL, and Proxmox only creates it once the download (and its
+        checksum check) has succeeded, so an existing file is a complete one.
+        """
+        volid = f"{storage}:import/{filename}"
+        present = self._node_api().storage(storage).content.get(content="import")
+        if any(item.get("volid") == volid for item in present):
+            _logger.info(f"Cloud image already in {storage}: {volid}")
+            return volid
+
+        params: dict[str, Any] = {"url": image_url, "content": "import", "filename": filename}
+        if image_checksum:
+            algo, expected = _split_checksum(image_checksum)
+            params["checksum"] = expected
+            params["checksum-algorithm"] = algo
+        _logger.info(f"Downloading cloud image {image_url} into {volid}")
+        upid = self._node_api().storage(storage)("download-url").post(**params)
+        self._wait_for_task(upid, timeout=timeout)
+        return volid
+
+    def _import_over_ssh(
+        self,
+        vmid: int,
+        image_storage: str,
+        image_url: str,
+        image_checksum: str | None,
+        download_timeout: int,
+        timeout: int,
+    ) -> None:
+        """Download the image on the node and import it as the root disk.
+
+        The path for nodes without an import storage, or for an image type
+        Proxmox cannot import itself.
+        """
+        local_path = self._download_cloud_image(image_url, image_checksum, timeout=download_timeout)
+        _logger.info(f"Importing {local_path} into VM {vmid} on storage {image_storage}")
+        self._run_node_command(
+            f"qm importdisk {vmid} {local_path} {image_storage} --format qcow2",
+            timeout=timeout,
+        )
+
+        # Proxmox leaves the imported disk as an "unusedN" reference — find
+        # it and attach it as the boot disk.
+        imported_config = self._node_api().qemu(vmid).config.get()
+        unused_value = next((v for k, v in imported_config.items() if k.startswith("unused")), None)
+        if not unused_value:
+            raise RuntimeError(
+                f"Disk import for VM {vmid} did not produce an unused disk reference"
+            )
+        self._node_api().qemu(vmid).config.post(
+            scsi0=f"{unused_value},discard=on",
+            boot="order=scsi0",
+        )
+
+    def _attach_root_disk(
+        self,
+        vmid: int,
+        image_storage: str,
+        image_url: str,
+        image_checksum: str | None,
+        download_timeout: int,
+        timeout: int,
+    ) -> None:
+        """Get the cloud image onto the node and make it the VM's root disk.
+
+        Through an import storage when the node has one — Proxmox downloads,
+        verifies and copies the image itself — and over SSH otherwise.
+        """
+        import_storage = self._find_import_storage()
+        filename = _import_volume_name(image_url) if import_storage else None
+        if not import_storage or not filename:
+            self._import_over_ssh(
+                vmid, image_storage, image_url, image_checksum, download_timeout, timeout
+            )
+            return
+
+        volid = self._import_cloud_image(
+            import_storage, filename, image_url, image_checksum, timeout=download_timeout
+        )
+        _logger.info(f"Importing {volid} into VM {vmid} on storage {image_storage}")
+        upid = (
+            self._node_api()
+            .qemu(vmid)
+            .config.post(
+                scsi0=f"{image_storage}:0,import-from={volid},discard=on",
+                boot="order=scsi0",
+            )
+        )
+        if upid:
+            self._wait_for_task(upid, timeout=timeout)
+
+    def _find_default_image_storage(self) -> str:
+        """Find a storage suitable for VM root disks (content includes 'images').
+
+        Proxmox's /storage API omits the "enabled" field entirely for storages
+        that were never explicitly toggled — it is not present-and-falsy, it is
+        just absent, defaulting to enabled. Only an explicit 0 means disabled.
+
+        Queries the node-scoped /nodes/{node}/storage endpoint, not the
+        cluster-wide /storage one: a storage can be configured with a "nodes"
+        restriction limiting it to other cluster members, and the cluster-wide
+        list doesn't reflect that — it would happily return a storage this
+        node can't actually see, and "qm importdisk" would fail with
+        "storage 'X' is not available on node 'Y'" after the VM shell was
+        already created.
+        """
+        for storage in self._node_api().storage.get():
+            content = storage.get("content", "")
+            if "images" in content and storage.get("enabled", 1) != 0:
+                return storage["storage"]
+        raise ValueError(
+            "No storage with content='images' found. Configure a storage for VM disks."
+        )
+
+    def _get_storage_path(self, storage: str) -> str:
+        """Resolve a storage's filesystem path on the node.
+
+        Needed to write Cloud-Init snippets directly: Proxmox's
+        /storage/{s}/upload API only accepts content in {iso, vztmpl,
+        import} — "snippets" is rejected outright, so snippets must be
+        written straight to the filesystem instead. Only dir-backed storages
+        (dir, nfs, cifs, cephfs) expose "path"; those are also the only
+        storage types Proxmox itself allows content='snippets' on.
+        """
+        config = self._api.storage(storage).get()
+        path = config.get("path")
+        if not path:
+            raise ValueError(
+                f"Storage '{storage}' has no filesystem path (content='snippets' "
+                "requires a dir/nfs/cifs/cephfs-backed storage)"
+            )
+        return path
+
+    def get_image_storages(self) -> List[StorageTargetDict]:
+        """List node-available storage pools suitable for a new VM's root disk."""
+        targets: List[StorageTargetDict] = []
+        for storage in self._node_api().storage.get():
+            content = storage.get("content", "")
+            if "images" not in content or storage.get("enabled", 1) == 0:
+                continue
+            if storage.get("active", 1) == 0:
+                continue
+            total = storage.get("total") or 0
+            avail = storage.get("avail") or 0
+            targets.append(
+                {
+                    "name": storage["storage"],
+                    "type": storage.get("type", ""),
+                    "total_gb": round(total / (1024**3), 1),
+                    "available_gb": round(avail / (1024**3), 1),
+                }
+            )
+        return targets
+
+    def _wait_for_task(self, upid: str, timeout: int = 120) -> None:
+        """
+        Poll a Proxmox task until completion.
+
+        Polls /nodes/{node}/tasks/{upid}/status until status == 'stopped'.
+        Raises RuntimeError if exitstatus != 'OK' or timeout exceeded.
+        """
+        start_time = time.time()
+        while True:
+            elapsed = time.time() - start_time
+            if elapsed > timeout:
+                raise RuntimeError(f"Task {upid} timed out after {timeout}s")
+
+            try:
+                task_status = self._node_api().tasks(upid).status.get()
+            except Exception as e:
+                _logger.debug(f"Error polling task {upid}: {e}")
+                time.sleep(2)
+                continue
+
+            if task_status.get("status") == "stopped":
+                exitstatus = task_status.get("exitstatus", "UNKNOWN")
+                if exitstatus != "OK":
+                    raise RuntimeError(
+                        f"Task {upid} failed with exitstatus='{exitstatus}': "
+                        f"{task_status.get('exitstatus_text', 'no error message')}"
+                    )
+                return
+
+            time.sleep(2)
+
+    def create_vm_from_cloud_init(
+        self,
+        name: str,
+        *,
+        image_url: str,
+        cpu: int,
+        memory: int,
+        nics: List[Dict[str, Any]],
+        cloud_init_config: Dict[str, Any],
+        image_checksum: str | None = None,
+        ssh_public_keys: List[str] | None = None,
+        disk_resize_gb: int | None = None,
+        storage: str | None = None,
+        download_timeout: int = 300,
+        timeout: int = 180,
+    ) -> VMProvisionResultDict:
+        """
+        Create a new VM from a downloaded cloud image via Proxmox API.
+
+        Steps:
+          1. Get next available VMID from cluster
+          2. Create an empty VM shell (no clone — no pre-existing template needed)
+          3. Download the cloud image on the node (cached by filename) and
+             import it as the VM's root disk
+          4. Configure CPU, memory, and network interfaces
+          5. Verify snippet storage exists
+          6. Render cloud-init config to YAML and upload
+          7. Set Cloud-Init config references and SSH keys
+          8. Optionally resize root disk
+          9. Start the VM
+          10. Return VMID, name, node
+
+        Args:
+            name: new VM display name
+            image_url: URL of the cloud image to download and use as root disk
+            cpu: number of vCPUs
+            memory: RAM in MB
+            nics: list of NIC config dicts (bridge, vlan_tag/trunk_vlan_tags, dhcp flag)
+            cloud_init_config: user-data dict (will be YAML-rendered)
+            image_checksum: expected "<algo>:<hex>" checksum of the image, verified
+                after download (None = no verification)
+            ssh_public_keys: SSH public keys to inject
+            disk_resize_gb: resize root disk to this size (None = no resize)
+            storage: storage pool for the root disk (None = auto-detect first
+                enabled, node-available storage with content='images')
+            download_timeout: max seconds for the image download (skipped if cached)
+            timeout: max seconds for the remaining provisioning steps
+
+        Returns:
+            {"vmid": str, "name": str, "node": str}
+
+        Raises:
+            RuntimeError: provisioning failure (download, import, config, timeout, etc.)
+            ValueError: invalid storage or configuration
+        """
+        try:
+            _logger.info(f"Creating VM '{name}' from image {image_url}")
+
+            # Step 1: Get next VMID
+            next_vmid = self._api.cluster.nextid.get()
+            vmid = int(next_vmid)
+            _logger.info(f"Allocated VMID {vmid}")
+
+            # Step 2: Create empty VM shell (no disks yet)
+            _logger.info(f"Creating VM shell {vmid}")
+            self._node_api().qemu.post(
+                vmid=vmid,
+                name=name,
+                memory=memory,
+                cores=cpu,
+                ostype="l26",
+                scsihw="virtio-scsi-pci",
+                # Without this, Proxmox never attaches the virtio-serial
+                # channel the QEMU guest agent needs — get_vm_status's
+                # agent queries (below) would have nothing to talk to.
+                agent="1",
+            )
+
+            # Step 3: Download cloud image (cached) and import as root disk
+            image_storage = storage or self._find_default_image_storage()
+            self._attach_root_disk(
+                vmid, image_storage, image_url, image_checksum, download_timeout, timeout
+            )
+
+            # Step 4: Configure network interfaces (CPU/memory already set at shell creation)
+            _logger.info(f"Configuring {len(nics)} NIC(s) for VM {vmid}")
+
+            config_args: Dict[str, Any] = {}
+
+            # Build NIC config strings generically
+            for i, nic in enumerate(nics):
+                bridge = nic.get("bridge")
+                if not bridge:
+                    raise ValueError(f"NIC {i}: bridge is required")
+
+                # Build base config: model[=mac] + bridge
+                mac = nic.get("mac")
+                net_config = f"virtio={mac},bridge={bridge}" if mac else f"virtio,bridge={bridge}"
+
+                # Add VLAN configuration (access vs trunk)
+                if "trunk_vlan_tags" in nic and nic["trunk_vlan_tags"]:
+                    vlan_list = ";".join(str(v) for v in nic["trunk_vlan_tags"])
+                    net_config += f",trunks={vlan_list}"
+                elif "vlan_tag" in nic and nic["vlan_tag"] is not None:
+                    net_config += f",tag={nic['vlan_tag']}"
+
+                config_args[f"net{i}"] = net_config
+
+            self._node_api().qemu(vmid).config.post(**config_args)
+
+            # Step 5: Verify snippet storage exists
+            # (enabled is absent-not-falsy, and node-scoping matters — see
+            # _find_default_image_storage)
+            _logger.info("Checking for snippet storage...")
+            storages = self._node_api().storage.get()
+            snippet_storage = None
+            for storage in storages:
+                content = storage.get("content", "")
+                if "snippets" in content and storage.get("enabled", 1) != 0:
+                    snippet_storage = storage["storage"]
+                    break
+
+            if not snippet_storage:
+                raise ValueError(
+                    "No storage with content='snippets' found. "
+                    "Configure a snippet-capable storage (e.g. local, nfs dir) "
+                    "and enable it."
+                )
+            _logger.info(f"Using snippet storage: {snippet_storage}")
+
+            # Step 6: Render and upload Cloud-Init config
+            _logger.info(f"Rendering Cloud-Init config for VMID {vmid}")
+
+            user_data_yaml = "#cloud-config\n" + yaml.dump(
+                cloud_init_config, default_flow_style=False
+            )
+
+            filename = f"{vmid}-user-data.yaml"
+            _logger.debug(f"Writing Cloud-Init snippet {filename} to {snippet_storage}")
+
+            # Proxmox's /storage/{s}/upload API only accepts content in
+            # {iso, vztmpl, import} — "snippets" is rejected outright
+            # ("does not have a value in the enumeration"). Snippets can only
+            # be written directly to the filesystem, so resolve the storage's
+            # backing path and write the file over SSH instead.
+            storage_path = self._get_storage_path(snippet_storage)
+            encoded = base64.b64encode(user_data_yaml.encode("utf-8")).decode("ascii")
+            self._run_node_command(
+                f"mkdir -p {storage_path}/snippets && "
+                f"echo {encoded} | base64 -d > {storage_path}/snippets/{filename}",
+                timeout=30,
+            )
+
+            # Step 7: Configure Cloud-Init references and SSH keys
+            _logger.info(f"Setting Cloud-Init config for VM {vmid}")
+
+            cloud_init_args = {
+                # The cloud-init drive is a disk image — it needs a storage
+                # with content='images' (same requirement as the root disk),
+                # NOT the snippet storage (content='snippets'). These are
+                # often different storages; Proxmox fails at VM start with
+                # "storage 'X' does not support content-type 'images'" if
+                # this points at a snippets-only storage.
+                "ide2": f"{image_storage}:cloudinit",
+                "citype": "nocloud",
+                "cicustom": f"user={snippet_storage}:snippets/{filename}",
+            }
+
+            # Configure DHCP for NICs where enabled (default True for index 0, False otherwise)
+            for i, nic in enumerate(nics):
+                dhcp_enabled = nic.get("dhcp", i == 0)  # Default DHCP for first NIC only
+                if dhcp_enabled:
+                    cloud_init_args[f"ipconfig{i}"] = "ip=dhcp"
+
+            if ssh_public_keys:
+                # URL-encode SSH keys for Proxmox API
+                sshkeys = ";".join(ssh_public_keys)
+                cloud_init_args["sshkeys"] = quote(sshkeys)
+
+            self._node_api().qemu(vmid).config.post(**cloud_init_args)
+
+            # Step 8: Optionally resize root disk
+            if disk_resize_gb is not None:
+                _logger.info(f"Resizing root disk to {disk_resize_gb}GB")
+                # Find root disk (scsi0, virtio0, ide0, sata0 — whichever is first)
+                try:
+                    config = self._node_api().qemu(vmid).config.get()
+                    root_disk = None
+                    for prefix in ("scsi", "virtio", "ide", "sata"):
+                        if f"{prefix}0" in config:
+                            root_disk = f"{prefix}0"
+                            break
+                    if root_disk:
+                        self._node_api().qemu(vmid).resize.put(
+                            disk=root_disk,
+                            size=f"{disk_resize_gb}G",
+                        )
+                    else:
+                        _logger.warning(f"Could not find root disk for VM {vmid}, skipping resize")
+                except Exception as e:
+                    _logger.warning(f"Failed to resize disk: {e}, continuing anyway")
+
+            # Step 9: Start the VM
+            _logger.info(f"Starting VM {vmid}")
+            start_upid = self._node_api().qemu(vmid).status.start.post()
+            self._wait_for_task(start_upid, timeout=timeout)
+
+            _logger.info(f"VM {vmid} ('{name}') provisioned successfully on {self._node_name}")
+            return {
+                "vmid": str(vmid),
+                "name": name,
+                "node": self._node_name,
+            }
+
+        except Exception as e:
+            _logger.exception(f"Failed to create VM '{name}': {e}")
+            raise
+
+    def destroy_vm(
+        self,
+        vmid: str,
+        *,
+        remove_disk: bool = True,
+        timeout: int = 60,
+    ) -> None:
+        """
+        Destroy a virtual machine and optionally remove its storage.
+
+        Steps:
+          1. Stop the VM if running
+          2. Delete VM configuration and optionally disks
+          3. Clean up Cloud-Init snippets
+
+        Args:
+            vmid: hypervisor VMID (string, e.g. "101")
+            remove_disk: if True, also delete disks and storage
+            timeout: max seconds for stop/delete operations
+
+        Raises:
+            RuntimeError: VM doesn't exist or destruction fails
+        """
+        try:
+            vmid_int = int(vmid)
+            _logger.info(f"Destroying VM {vmid}")
+
+            # Step 1: Stop the VM if running
+            try:
+                _logger.debug(f"Stopping VM {vmid}")
+                stop_upid = self._node_api().qemu(vmid_int).status.stop.post()
+                self._wait_for_task(stop_upid, timeout=timeout)
+            except Exception as e:
+                _logger.debug(f"VM {vmid} stop failed (may already be stopped): {e}")
+
+            # Step 2: Delete VM
+            # Proxmox's API parameter is hyphenated (destroy-unreferenced-disks),
+            # not a valid Python identifier — proxmoxer forwards kwargs to the
+            # request verbatim with no underscore-to-hyphen translation, so this
+            # must be built as a dict and unpacked rather than passed as a kwarg.
+            _logger.debug(f"Deleting VM {vmid} configuration and disks")
+            delete_params = {
+                "purge": 1,
+                "destroy-unreferenced-disks": 1 if remove_disk else 0,
+            }
+            self._node_api().qemu(vmid_int).delete(**delete_params)
+
+            # Step 3: Clean up Cloud-Init snippets
+            # (This is best-effort; snippet files may be unreachable if storage is unavailable)
+            try:
+                config = self._node_api().qemu(vmid_int).config.get()
+                cicustom = config.get("cicustom", "")
+                if "snippets/" in cicustom:
+                    parts = cicustom.split("=")
+                    if len(parts) >= 2:
+                        snippet_ref = parts[1]  # e.g. "snippets:snippets/101-user-data.yaml"
+                        storage, filepath = snippet_ref.split(":", 1)
+                        _logger.debug(f"Deleting snippet {filepath} from {storage}")
+                        try:
+                            self._node_api().storage(storage).content(filepath).delete()
+                        except Exception as e:
+                            _logger.warning(f"Failed to delete snippet {filepath}: {e}")
+            except Exception as e:
+                _logger.debug(f"Could not clean up snippets for VM {vmid}: {e}")
+
+            _logger.info(f"VM {vmid} destroyed successfully")
+
+        except Exception as e:
+            _logger.exception(f"Failed to destroy VM {vmid}: {e}")
+            raise
+
+    def get_vm_status(
+        self,
+        vmid: str,
+        *,
+        wait_for_ip: bool = False,
+        timeout: int = 300,
+        poll_interval: int = 5,
+    ) -> VMStatusDict:
+        """
+        Get the runtime status of a virtual machine.
+
+        Optionally waits for the guest-agent to report an IP address on the
+        management NIC (net0), useful after provisioning.
+
+        Args:
+            vmid: hypervisor VMID (string)
+            wait_for_ip: if True, poll until IP appears on net0
+            timeout: max seconds to wait for IP (if wait_for_ip=True)
+            poll_interval: seconds between status polls
+
+        Returns:
+            {"status": str, "ip_address": str, "hostname": str, "mac_address": str}
+            (ip_address, hostname, mac_address only if VM is running and has network info)
+
+        Raises:
+            RuntimeError: VM doesn't exist or wait_for_ip times out
+        """
+        try:
+            vmid_int = int(vmid)
+            _logger.debug(f"Getting status for VM {vmid}")
+
+            # VM must exist / be readable before we start polling.
+            try:
+                self._node_api().qemu(vmid_int).config.get()
+            except Exception:
+                # VM may not exist yet or config not readable
+                return {"status": "unknown"}
+
+            # Polling loop
+            start_time = time.time()
+            while True:
+                elapsed = time.time() - start_time
+                if wait_for_ip and elapsed > timeout:
+                    raise RuntimeError(f"VM {vmid} failed to acquire IP within {timeout}s")
+
+                try:
+                    # Query guest-agent network interfaces. Proxmox's REST path is
+                    # "network-get-interfaces" (hyphens) — it must be passed as a
+                    # resource id via __call__, not dotted attribute access (which
+                    # would silently build a non-existent "network_get_interfaces"
+                    # path and 404 on every poll).
+                    agent_info = (
+                        self._node_api().qemu(vmid_int).agent("network-get-interfaces").get()
+                    )
+                    interfaces = (agent_info or {}).get("result", [])
+
+                    # The guest agent does not report interfaces in a fixed order —
+                    # "lo" commonly comes first. Skip it and take the first real
+                    # NIC that has an IPv4 address.
+                    for iface in interfaces:
+                        name = iface.get("name", "")
+                        if not name or name == "lo":
+                            continue
+                        for addr in iface.get("ip-addresses", []):
+                            if addr.get("ip-address-type") != "ipv4":
+                                continue
+                            ip_addr = addr.get("ip-address", "")
+                            if ip_addr:
+                                _logger.info(f"VM {vmid} acquired IP {ip_addr}")
+                                return {
+                                    "status": "running",
+                                    "ip_address": ip_addr,
+                                    "hostname": name,
+                                    "mac_address": iface.get("hardware-address", ""),
+                                }
+
+                except Exception as e:
+                    _logger.debug(f"Error querying guest-agent for VM {vmid}: {e}")
+
+                if not wait_for_ip:
+                    # Return immediate status without IP
+                    return {"status": "running"}
+
+                # Wait before next poll
+                time.sleep(poll_interval)
+
+        except RuntimeError:
+            raise
+        except Exception as e:
+            _logger.exception(f"Error getting status for VM {vmid}: {e}")
+            raise RuntimeError(f"Failed to get VM {vmid} status: {e}")
+
+    def get_network_targets(self) -> List[NetworkTargetDict]:
+        """
+        List selectable network targets (bridges + SDN vnets) for a new VM's NIC.
+
+        Excludes physical NICs, bonds, and other non-bridge interface types —
+        those are never valid ``NICConfigDict.bridge`` values on Proxmox.
+        """
+        targets: List[NetworkTargetDict] = []
+
+        for iface in self._get_node_network():
+            iface_type = iface.get("type")
+            name = iface.get("iface", "")
+            if not name:
+                continue
+
+            if iface_type == "bridge":
+                vlan_aware = bool(int(iface.get("bridge_vlan_aware", 0) or 0))
+                targets.append({"name": name, "kind": "bridge", "vlan_aware": vlan_aware})
+            elif iface_type == "OVSBridge":
+                # OVS bridges tag per-port regardless of a dedicated "VLAN aware" setting.
+                targets.append({"name": name, "kind": "bridge", "vlan_aware": True})
+
+        for vnet in self._get_sdn_vnets():
+            name = vnet.get("vnet", "")
+            if not name:
+                continue
+            # A vnet's VLAN is already fixed by its zone/tag — no separate vlan_tag applies.
+            tag = vnet.get("tag")
+            fixed_vlan_tag = int(tag) if tag is not None else None
+            targets.append(
+                {
+                    "name": name,
+                    "kind": "vnet",
+                    "vlan_aware": False,
+                    "fixed_vlan_tag": fixed_vlan_tag,
+                }
+            )
+
+        return targets

napalm_proxmox/vm_snapshot_mixin.py

@@ -0,0 +1,74 @@
+"""HypervisorDriver snapshot methods for Proxmox VE guests (QEMU and LXC)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from napalm_device_types.models import SnapshotDict
+
+#: Proxmox lists the live state as a pseudo-snapshot of this name.
+_CURRENT = "current"
+#: A RAM snapshot of a large VM takes a while to write out.
+_SNAPSHOT_TIMEOUT = 600
+
+
+class ProxmoxVMSnapshotMixin:
+    """Relies on ``_resolve_vm``/``_guest_api`` from ProxmoxVMContractMixin."""
+
+    _resolve_vm: Any
+    _guest_api: Any
+    _wait_for_task: Any
+
+    def _snapshots(self, name: str) -> tuple[Any, str, str, list[dict[str, Any]]]:
+        vmid, vm_type = self._resolve_vm(name)
+        api = self._guest_api(vmid, vm_type)
+        raw = [s for s in api.snapshot.get() or [] if s.get("name") != _CURRENT]
+        return api, str(vmid), vm_type, raw
+
+    def _run_task(self, call: Any, *args: Any, **kwargs: Any) -> None:
+        try:
+            upid = call(*args, **kwargs)
+        except Exception as exc:
+            raise RuntimeError(str(exc)) from exc
+        if upid:
+            self._wait_for_task(upid, timeout=_SNAPSHOT_TIMEOUT)
+
+    @staticmethod
+    def _require(raw: list[dict[str, Any]], snapshot: str, vm: str) -> None:
+        if not any(s.get("name") == snapshot for s in raw):
+            raise ValueError(f"VM {vm!r} has no snapshot named {snapshot!r}")
+
+    def get_vm_snapshots(self, name: str) -> list[SnapshotDict]:
+        _, _, _, raw = self._snapshots(name)
+        return [
+            {
+                "name": s["name"],
+                "vm": name,
+                "created": float(s.get("snaptime", 0)),
+                "description": s.get("description", ""),
+                "has_memory": bool(s.get("vmstate")),
+                "parent": s.get("parent", ""),
+            }
+            for s in raw
+        ]
+
+    def create_vm_snapshot(
+        self, name: str, snapshot: str, description: str = "", include_memory: bool = False
+    ) -> None:
+        api, _, vm_type, raw = self._snapshots(name)
+        if any(s.get("name") == snapshot for s in raw):
+            raise ValueError(f"VM {name!r} already has a snapshot named {snapshot!r}")
+        kwargs: dict[str, Any] = {"snapname": snapshot, "description": description}
+        if vm_type == "vm":  # containers have no RAM state to save
+            kwargs["vmstate"] = 1 if include_memory else 0
+        self._run_task(api.snapshot.post, **kwargs)
+
+    def delete_vm_snapshot(self, name: str, snapshot: str) -> None:
+        api, _, _, raw = self._snapshots(name)
+        self._require(raw, snapshot, name)
+        self._run_task(api.snapshot(snapshot).delete)
+
+    def rollback_vm_snapshot(self, name: str, snapshot: str) -> None:
+        api, _, _, raw = self._snapshots(name)
+        self._require(raw, snapshot, name)
+        self._run_task(api.snapshot(snapshot).rollback.post)

pyproject.toml

@@ -25,7 +25,8 @@ classifiers = [
 requires-python = ">=3.9"
 dependencies = [
     "napalm>=5.0.0",
-    "napalm_device_types>=0.1.0",
+    "napalm_device_types>=2.0.0",
+    "paramiko>=5.0.0",  # CVE-2026-44405; imported directly for SSH fallback (driver.py)
     "proxmoxer>=2.0.0",
     "netaddr>=0.9.0",
     "requests>=2.31.0",

tests/conftest.py

@@ -91,7 +91,10 @@ SDN_SUBNETS_VNET1 = [
 
 SDN_SUBNETS_VNET2: list = []
 
-DNS_INFO = {"search": "pve1.example.com", "dns1": "8.8.8.8"}
+# A DNS *search domain*, not an FQDN. It used to read "pve1.example.com",
+# which made get_facts build "pve1.pve1.example.com" and looked like a
+# driver bug rather than bad test data.
+DNS_INFO = {"search": "example.com", "dns1": "8.8.8.8"}
 
 NTP_INFO = {"server": "pool.ntp.org,time.cloudflare.com"}
 
@@ -135,6 +138,7 @@ def _build_mock_api(
     pve_users=None,
     exec_return="",
     sensors=None,
+    cluster_status=None,
 ):
     """Build a MagicMock ProxmoxAPI with pre-configured return values."""
     api = MagicMock()
@@ -162,6 +166,7 @@ def _build_mock_api(
     # SDN
     cluster = MagicMock()
     api.cluster = cluster
+    cluster.status.get.return_value = cluster_status or []
     cluster.sdn.zones.get.return_value = sdn_zones or SDN_ZONES
     cluster.sdn.vnets.get.return_value = sdn_vnets or SDN_VNETS
 

tests/test_connection.py

@@ -34,7 +34,10 @@ class TestOpen:
         with patch("napalm_proxmox.driver.ProxmoxAPI", return_value=mock_api) as mock_cls:
             drv.open()
         call_kwargs = mock_cls.call_args.kwargs
-        assert call_kwargs["user"] == "napalm@pam!mytoken"
+        # proxmoxer wants the two halves separately, not the combined
+        # "<user>!<tokenid>" string that Proxmox's UI displays.
+        assert call_kwargs["user"] == "napalm@pam"
+        assert call_kwargs["token_name"] == "mytoken"
         assert call_kwargs["token_value"] == "super-secret"
 
     def test_open_connection_error(self):
@@ -73,3 +76,78 @@ class TestIsAlive:
     def test_not_alive_when_api_fails(self, driver):
         driver._api.version.get.side_effect = Exception("timeout")
         assert driver.is_alive() == {"is_alive": False}
+
+
+# A four-node cluster as GET /cluster/status reports it. The node the API
+# session landed on carries local=1 — here the third one, so taking the first
+# entry of /nodes (the old behaviour) picks the wrong host.
+CLUSTER_NODES = [
+    {"type": "node", "name": "pve-01", "ip": "172.22.8.101", "local": 0},
+    {"type": "node", "name": "pve-02", "ip": "172.22.8.102", "local": 0},
+    {"type": "node", "name": "pve-dual", "ip": "172.22.8.120", "local": 1},
+    {"type": "node", "name": "pve-garden", "ip": "172.22.8.5", "local": 0},
+]
+CLUSTER_STATUS = [{"type": "cluster", "name": "home", "nodes": 4}, *CLUSTER_NODES]
+CLUSTER_NODES_LIST = [{"node": n["name"], "status": "online"} for n in CLUSTER_NODES]
+
+
+def _open_with(hostname, **api_kwargs):
+    drv = ProxmoxDriver(hostname, "root", "secret")
+    mock_api = _build_mock_api(**api_kwargs)
+    with patch("napalm_proxmox.driver.ProxmoxAPI", return_value=mock_api):
+        drv.open()
+    return drv
+
+
+class TestClusterNodeResolution:
+    def test_local_node_wins_over_first_listed(self):
+        drv = _open_with(
+            "172.22.8.120", nodes=CLUSTER_NODES_LIST, cluster_status=CLUSTER_STATUS
+        )
+        assert drv._node_name == "pve-dual"
+
+    def test_matches_by_ip_without_local_flag(self):
+        status = [{**n, "local": 0} for n in CLUSTER_STATUS if n["type"] == "node"]
+        drv = _open_with("172.22.8.102", nodes=CLUSTER_NODES_LIST, cluster_status=status)
+        assert drv._node_name == "pve-02"
+
+    def test_matches_by_name_without_local_flag(self):
+        status = [{**n, "local": 0} for n in CLUSTER_STATUS if n["type"] == "node"]
+        drv = _open_with("pve-garden", nodes=CLUSTER_NODES_LIST, cluster_status=status)
+        assert drv._node_name == "pve-garden"
+
+    def test_matches_short_name_of_fqdn(self):
+        status = [{**n, "local": 0} for n in CLUSTER_STATUS if n["type"] == "node"]
+        drv = _open_with(
+            "pve-01.mgmt.example.com", nodes=CLUSTER_NODES_LIST, cluster_status=status
+        )
+        assert drv._node_name == "pve-01"
+
+    def test_single_node_without_cluster_status(self):
+        drv = _open_with("10.0.0.9", nodes=[{"node": "solo", "status": "online"}])
+        assert drv._node_name == "solo"
+
+    def test_ambiguous_cluster_refuses_to_guess(self):
+        status = [{**n, "local": 0} for n in CLUSTER_STATUS if n["type"] == "node"]
+        with pytest.raises(ConnectionException, match="node"):
+            _open_with("10.9.9.9", nodes=CLUSTER_NODES_LIST, cluster_status=status)
+
+    def test_api_error_fails_open_instead_of_guessing(self):
+        # A TLS failure used to be swallowed here: the IP became the node
+        # name, open() succeeded and every later call failed quietly.
+        drv = ProxmoxDriver("172.22.8.120", "root", "secret")
+        mock_api = _build_mock_api()
+        mock_api.cluster.status.get.side_effect = Exception("CERTIFICATE_VERIFY_FAILED")
+        mock_api.nodes.get.side_effect = Exception("CERTIFICATE_VERIFY_FAILED")
+        with patch("napalm_proxmox.driver.ProxmoxAPI", return_value=mock_api):
+            with pytest.raises(ConnectionException, match="CERTIFICATE_VERIFY_FAILED"):
+                drv.open()
+
+    def test_explicit_node_skips_lookup(self):
+        drv = ProxmoxDriver("172.22.8.120", "root", "secret", optional_args={"node": "pve-dual"})
+        mock_api = _build_mock_api()
+        with patch("napalm_proxmox.driver.ProxmoxAPI", return_value=mock_api):
+            drv.open()
+        assert drv._node_name == "pve-dual"
+        mock_api.cluster.status.get.assert_not_called()
+        mock_api.nodes.get.assert_not_called()

tests/test_misc.py

@@ -263,17 +263,28 @@ class TestGetRouteTo:
 
 
 class TestLLDPNeighbors:
+    # Real `lldpcli show neighbors summary` output. The interface line carries
+    # ", via: LLDP, ..." after the name, which is what the parser matches on —
+    # the previous fixture stopped at the name and matched nothing.
     LLDP_SUMMARY = (
-        "  Interface: eth0\n"
+        "LLDP neighbors:\n"
+        "-------------------------------------------------------------------------------\n"
+        "Interface:    eth0, via: LLDP, RID: 1, Time: 0 day, 00:11:22\n"
+        "  Chassis:\n"
         "    SysName:      sw01.example.com\n"
+        "  Port:\n"
         "    PortID:       ifname GigabitEthernet1/0/1\n"
-        "  Interface: eth1\n"
+        "-------------------------------------------------------------------------------\n"
+        "Interface:    eth1, via: LLDP, RID: 2, Time: 0 day, 00:11:22\n"
+        "  Chassis:\n"
         "    SysName:      sw02.example.com\n"
+        "  Port:\n"
         "    PortID:       ifname GigabitEthernet1/0/2\n"
+        "-------------------------------------------------------------------------------\n"
     )
 
     def test_neighbors_found(self, driver):
-        driver._node_api().execute.post.return_value = {"data": self.LLDP_SUMMARY}
+        with patch.object(driver, "_exec_ssh_command", return_value=self.LLDP_SUMMARY):
             result = driver.get_lldp_neighbors()
         assert "eth0" in result
         assert result["eth0"][0]["hostname"] == "sw01.example.com"

tests/test_ovs_and_arp.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import pytest
+from unittest.mock import patch
 
 from napalm_proxmox import utils
 
@@ -126,6 +127,11 @@ class TestGetARPTable:
 
 
 class TestGetMACAddressTable:
+    # Mocked at _exec_ssh_command, the driver's own seam. Mocking the API call
+    # underneath it broke twice over: that helper passes two positional
+    # arguments where these doubles accepted one, and it base64-wraps the
+    # command, so a fixture keyed on "bridge fdb" appearing in the text never
+    # matched.
     BRIDGE_FDB = (
         "aa:bb:cc:dd:ee:01 dev eth0 vlan 10 master vmbr0 permanent\n"
         "cc:dd:ee:ff:00:11 dev eth0 vlan 20 master vmbr0\n"
@@ -142,9 +148,7 @@ class TestGetMACAddressTable:
                 return self.BRIDGE_FDB
             return ""
 
-        driver._node_api().execute.post.side_effect = lambda command: {
+        with patch.object(driver, "_exec_ssh_command", side_effect=_exec):
-            "data": _exec(command)
-        }
             result = driver.get_mac_address_table()
         macs = {e["mac"] for e in result}
         assert "aa:bb:cc:dd:ee:01" in macs
@@ -155,9 +159,7 @@ class TestGetMACAddressTable:
                 return self.BRIDGE_FDB
             return ""
 
-        driver._node_api().execute.post.side_effect = lambda command: {
+        with patch.object(driver, "_exec_ssh_command", side_effect=_exec):
-            "data": _exec(command)
-        }
             result = driver.get_mac_address_table()
         static_entries = [e for e in result if e["mac"] == "aa:bb:cc:dd:ee:01"]
         assert static_entries[0]["static"] is True

tests/test_packages.py

@@ -0,0 +1,67 @@
+"""`get_packages` and the source coordinate OSV matching needs.
+
+A Proxmox node is a Debian host, so its packages are matched against Debian
+advisories — and OSV states those ranges in *source* package versions. Reporting
+the source package without its version leaves a consumer holding two numbers on
+different axes: `libldb2` is `2:2.11.0+samba4.22.11+dfsg-…` while its source,
+samba, is `2:4.22.11+dfsg-…`, and comparing the first against a samba range is
+meaningless.
+
+Measured before this was fixed: on three Proxmox nodes, **every one** of their
+2 349 packages carried a source package and no source version — 802 of 802,
+774 of 774, 773 of 773 — while twenty non-Proxmox hosts had both. The format
+string simply never asked for the field.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+# `${Package}\t${Version}\t${db:Status-Status}\t${Installed-Size}\t${source:Package}\t${source:Version}`
+DPKG = (
+    "openssh-server\t1:9.2p1-2\tinstalled\t1024\topenssh\t1:9.2p1-2\n"
+    "libldb2\t2:2.11.0+samba4.22.11+dfsg-0+deb13u1\tinstalled\t512\tsamba\t2:4.22.11+dfsg-0+deb13u1\n"
+    "curl\t7.88.1-10\tinstalled\t256\t\t\n"
+)
+
+
+@pytest.mark.parametrize("driver_with_exec", [DPKG], indirect=True)
+def test_the_source_version_is_reported(driver_with_exec):
+    """The field the whole fix is about."""
+    packages = {p["name"]: p for p in driver_with_exec.get_packages()}
+
+    assert packages["libldb2"]["source_package"] == "samba"
+    assert packages["libldb2"]["source_version"] == "2:4.22.11+dfsg-0+deb13u1"
+
+
+@pytest.mark.parametrize("driver_with_exec", [DPKG], indirect=True)
+def test_the_binary_version_is_kept_beside_it(driver_with_exec):
+    """Both are wanted: one says what is installed, the other is the axis the
+    advisory's range is stated on."""
+    libldb2 = {p["name"]: p for p in driver_with_exec.get_packages()}["libldb2"]
+
+    assert libldb2["version"] == "2:2.11.0+samba4.22.11+dfsg-0+deb13u1"
+
+
+@pytest.mark.parametrize("driver_with_exec", [DPKG], indirect=True)
+def test_an_empty_source_falls_back_to_the_package_itself(driver_with_exec):
+    """dpkg leaves both fields empty when the source is the package — and an
+    older dpkg leaves them empty because it does not know the field at all.
+    Neither may produce a package with no coordinate."""
+    curl = {p["name"]: p for p in driver_with_exec.get_packages()}["curl"]
+
+    assert curl["source_package"] == "curl"
+    assert curl["source_version"] == "7.88.1-10"
+
+
+def test_the_query_asks_for_the_field():
+    """The defect was in the format string, not in the parsing: the driver
+    reported a source package it had asked for and a source version it had
+    not, so no amount of parsing could have produced one."""
+    import inspect
+
+    from napalm_proxmox import system_mixin
+
+    source = inspect.getsource(system_mixin.ProxmoxSystemMixin.get_packages)
+
+    assert "source:Version" in source

tests/test_reboot_host.py

@@ -0,0 +1,16 @@
+"""reboot_host: restart the Proxmox node itself through the API, not over SSH."""
+
+from __future__ import annotations
+
+import pytest
+
+
+def test_posts_reboot_to_the_node(driver):
+    driver.reboot_host()
+    driver._node_api().status.post.assert_called_once_with(command="reboot")
+
+
+def test_api_refusal_is_a_runtime_error(driver):
+    driver._node_api().status.post.side_effect = Exception("Permission check failed")
+    with pytest.raises(RuntimeError, match="Permission check failed"):
+        driver.reboot_host()

tests/test_sdn.py

@@ -22,19 +22,33 @@ class TestGetVlans:
         result = driver.get_vlans()
         assert "100000" in result
 
-    def test_bridge_vlan_show_parsing(self, driver):
+    def test_membership_derived_from_vm_configs(self, driver):
-        # Simulate bridge vlan output
+        """Without OVS ports, VLAN membership comes from each VM's netN config.
-        bridge_output = (
+
-            "vmbr0   1\n"
+        This replaces a test for a `bridge vlan show` fallback that no longer
-            "        10\n"
+        exists — it also asserted an "interfaces" key this method has never
-            "        20\n"
+        produced, so it could not have passed against any version of the code.
-            "eth0    1\n"
+        """
-        )
+        node = driver._node_api()
-        driver._node_api().execute.post.return_value = {"data": bridge_output}
+        node.qemu.get.return_value = [{"vmid": 100}]
+        node.lxc.get.return_value = []
+        node.qemu.return_value.config.get.return_value = {
+            "net0": "virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=10",
+        }
+
         result = driver.get_vlans()
-        # Interface vmbr0 should appear in vlan 1
+        assert "vmbr0" in result["10"]["untagged"]
-        entry = result.get("1", {})
+
-        assert "vmbr0" in entry.get("interfaces", [])
+    def test_configured_vnets_appear_even_without_members(self, driver):
+        """An SDN VNet exists on the node whether or not anything is attached.
+
+        Entries with no member ports used to be filtered out of this one return
+        path while the OVS path returned them, so a configured VLAN was visible
+        or invisible depending on which branch ran.
+        """
+        result = driver.get_vlans()
+        assert result["20"]["name"] == "vnet1"
+        assert result["20"]["untagged"] == []
 
     def test_empty_sdn_returns_dict(self):
         from unittest.mock import patch

tests/test_vm_contract.py

@@ -0,0 +1,239 @@
+"""HypervisorDriver contract methods: VM lookup, power actions, get_vm_config.
+
+netOrk used to call Proxmox's own ``power_vm`` and reach into ``_node_api()``
+for a VM's hardware. Both are Proxmox-only, so a second hypervisor could not
+serve the same endpoints. These pin the contract methods that replace them.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from napalm_proxmox.vm_contract_mixin import parse_vm_config
+
+QEMU_LIST = [{"vmid": 100, "name": "web01", "status": "running"}]
+LXC_LIST = [{"vmid": 200, "name": "dns01", "status": "running"}]
+
+
+@pytest.fixture
+def api(driver):
+    node = driver._node_api()
+    node.qemu.get.return_value = QEMU_LIST
+    node.lxc.get.return_value = LXC_LIST
+    node.qemu.return_value.status.start.post.return_value = "UPID:start"
+    driver._wait_for_task = MagicMock()
+    return node
+
+
+class TestGetVmsReportsStringIds:
+    def test_vmid_is_a_string(self, driver, api):
+        driver.get_vm_interfaces = MagicMock(return_value=({}, False, False))
+        driver._get_vm_disk_and_boot = MagicMock(return_value=([], False))
+        assert [vm["vmid"] for vm in driver.get_vms()] == ["100", "200"]
+
+    def test_ordered_numerically_not_lexically(self, driver, api):
+        api.qemu.get.return_value = [{"vmid": 1000, "name": "a"}, {"vmid": 99, "name": "b"}]
+        api.lxc.get.return_value = []
+        driver.get_vm_interfaces = MagicMock(return_value=({}, False, False))
+        driver._get_vm_disk_and_boot = MagicMock(return_value=([], False))
+        assert [vm["vmid"] for vm in driver.get_vms()] == ["99", "1000"]
+
+
+class TestResolveVm:
+    def test_by_vmid_string(self, driver, api):
+        assert driver._resolve_vm("100") == (100, "vm")
+
+    def test_by_name(self, driver, api):
+        assert driver._resolve_vm("dns01") == (200, "container")
+
+    def test_unknown_raises_value_error(self, driver, api):
+        with pytest.raises(ValueError, match="nope"):
+            driver._resolve_vm("nope")
+
+
+class TestPowerActions:
+    def test_start_posts_and_waits_for_the_task(self, driver, api):
+        driver.start_vm("web01")
+        api.qemu.return_value.status.start.post.assert_called_once()
+        driver._wait_for_task.assert_called_once_with("UPID:start", timeout=120)
+
+    @pytest.mark.parametrize(("force", "action"), [(False, "shutdown"), (True, "stop")])
+    def test_stop_graceful_or_forced(self, driver, api, force, action):
+        driver.stop_vm("100", force=force)
+        getattr(api.qemu.return_value.status, action).post.assert_called_once()
+
+    @pytest.mark.parametrize(("force", "action"), [(False, "reboot"), (True, "reset")])
+    def test_reboot_graceful_or_forced(self, driver, api, force, action):
+        driver.reboot_vm("100", force=force)
+        getattr(api.qemu.return_value.status, action).post.assert_called_once()
+
+    def test_forced_reboot_of_a_container_is_a_stop_and_start(self, driver, api):
+        """LXC has no reset; stop + start is the closest thing to pulling the plug."""
+        driver.reboot_vm("200", force=True)
+        status = api.lxc.return_value.status
+        status.stop.post.assert_called_once()
+        status.start.post.assert_called_once()
+
+    def test_suspend_vm(self, driver, api):
+        driver.suspend_vm("100")
+        api.qemu.return_value.status.suspend.post.assert_called_once()
+
+    def test_suspend_container_is_refused(self, driver, api):
+        with pytest.raises(RuntimeError, match="container"):
+            driver.suspend_vm("200")
+
+    def test_api_error_becomes_runtime_error(self, driver, api):
+        api.qemu.return_value.status.start.post.side_effect = Exception("locked")
+        with pytest.raises(RuntimeError, match="locked"):
+            driver.start_vm("100")
+
+
+QEMU_CONFIG = {
+    "name": "web01",
+    "cores": 2,
+    "sockets": 2,
+    "memory": "8192",
+    "ostype": "l26",
+    "cpu": "host,flags=+aes",
+    "bios": "ovmf",
+    "machine": "q35",
+    "boot": "order=scsi0;ide2;net0",
+    "scsi0": "local-lvm:vm-100-disk-0,size=32G,format=raw",
+    "virtio1": "tank:vm-100-disk-1,size=512M",
+    "ide2": "local:iso/debian.iso,media=cdrom",
+    "efidisk0": "local-lvm:vm-100-disk-2,size=4M",
+    "net0": "virtio=BC:24:11:AA:BB:CC,bridge=vmbr0,tag=10,firewall=1",
+    "net1": "e1000=BC:24:11:AA:BB:DD,bridge=vmbr1",
+    "hostpci0": "0000:01:00.0,pcie=1",
+    "usb0": "host=1234:5678",
+    "description": "Production web server",
+    "tags": "prod;web",
+}
+
+LXC_CONFIG = {
+    "hostname": "dns01",
+    "cores": 1,
+    "memory": 512,
+    "ostype": "debian",
+    "rootfs": "local-lvm:vm-200-disk-0,size=8G",
+    "mp0": "tank:subvol-200-disk-1,mp=/data,size=1T",
+    "net0": "name=eth0,bridge=vmbr0,hwaddr=BC:24:11:00:00:01,ip=dhcp,tag=20,type=veth",
+}
+
+
+class TestParseQemuConfig:
+    @pytest.fixture
+    def cfg(self):
+        return parse_vm_config("100", "vm", QEMU_CONFIG)
+
+    def test_core_fields(self, cfg):
+        assert cfg["vmid"] == "100"
+        assert cfg["name"] == "web01"
+        assert cfg["vcpus"] == 4
+        assert cfg["memory"] == 8192
+        assert cfg["os_type"] == "l26"
+        assert cfg["description"] == "Production web server"
+        assert cfg["tags"] == ["prod", "web"]
+
+    def test_boot_order(self, cfg):
+        assert cfg["boot_order"] == ["scsi0", "ide2", "net0"]
+
+    def test_disks_skip_cdrom_and_normalise_size(self, cfg):
+        by_dev = {d["device"]: d for d in cfg["disks"]}
+        assert set(by_dev) == {"scsi0", "virtio1", "efidisk0"}
+        assert by_dev["scsi0"] == {
+            "device": "scsi0",
+            "storage": "local-lvm",
+            "size": 32,
+            "format": "raw",
+            "bootable": True,
+        }
+        assert by_dev["virtio1"]["size"] == 0  # 512M rounds down to 0 GB
+        assert by_dev["virtio1"]["bootable"] is False
+
+    def test_nics(self, cfg):
+        assert cfg["nics"] == [
+            {
+                "device": "net0",
+                "mac": "BC:24:11:AA:BB:CC",
+                "model": "virtio",
+                "bridge": "vmbr0",
+                "vlan_id": 10,
+            },
+            {
+                "device": "net1",
+                "mac": "BC:24:11:AA:BB:DD",
+                "model": "e1000",
+                "bridge": "vmbr1",
+                "vlan_id": 0,
+            },
+        ]
+
+    def test_hardware_details(self, cfg):
+        assert cfg["cpu_type"] == "host"
+        assert cfg["sockets"] == 2
+        assert cfg["cores_per_socket"] == 2
+        assert cfg["firmware"] == "efi"
+        assert cfg["machine"] == "q35"
+
+    def test_passthrough(self, cfg):
+        assert cfg["passthrough"] == [
+            {"slot": "hostpci0", "kind": "pci", "config": "0000:01:00.0,pcie=1"},
+            {"slot": "usb0", "kind": "usb", "config": "host=1234:5678"},
+        ]
+
+    def test_defaults_for_a_bare_config(self):
+        cfg = parse_vm_config("101", "vm", {})
+        assert cfg["name"] == "vm-101"
+        assert cfg["vcpus"] == 1
+        assert cfg["cpu_type"] == "kvm64"
+        assert cfg["firmware"] == "bios"
+        assert "machine" not in cfg
+        assert cfg["boot_order"] == []
+
+    def test_legacy_bootdisk(self):
+        cfg = parse_vm_config("101", "vm", {"boot": "cdn", "bootdisk": "scsi0"})
+        assert cfg["boot_order"] == ["scsi0"]
+
+
+class TestParseLxcConfig:
+    @pytest.fixture
+    def cfg(self):
+        return parse_vm_config("200", "container", LXC_CONFIG)
+
+    def test_core_fields(self, cfg):
+        assert cfg["name"] == "dns01"
+        assert cfg["vcpus"] == 1
+        assert cfg["memory"] == 512
+        assert cfg["tags"] == []
+
+    def test_rootfs_and_mountpoint(self, cfg):
+        assert [(d["device"], d["storage"], d["size"]) for d in cfg["disks"]] == [
+            ("rootfs", "local-lvm", 8),
+            ("mp0", "tank", 1024),
+        ]
+
+    def test_veth_nic(self, cfg):
+        assert cfg["nics"] == [
+            {
+                "device": "net0",
+                "mac": "BC:24:11:00:00:01",
+                "model": "veth",
+                "bridge": "vmbr0",
+                "vlan_id": 20,
+            }
+        ]
+
+    def test_no_vm_only_hardware_fields(self, cfg):
+        assert "firmware" not in cfg
+        assert "sockets" not in cfg
+
+
+class TestGetVmConfig:
+    def test_fetches_the_right_config(self, driver, api):
+        api.lxc.return_value.config.get.return_value = LXC_CONFIG
+        cfg = driver.get_vm_config("dns01")
+        assert cfg["vmid"] == "200"
+        assert cfg["name"] == "dns01"

tests/test_vm_import_download.py

@@ -0,0 +1,241 @@
+"""Tests for provisioning through a storage with content type "import".
+
+Proxmox (8.2+) can download a disk image into such a storage itself
+(``download-url``, with checksum verification) and attach it to a VM with
+``import-from``. When the node has one, provisioning uses it instead of
+downloading over SSH into the node's root filesystem.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from napalm_proxmox.vm_provision_mixin import (
+    ProxmoxVMProvisionMixin,
+    _import_volume_name,
+)
+
+_UBUNTU = (
+    "https://cloud-images.ubuntu.com/releases/26.04/release/ubuntu-26.04-server-cloudimg-amd64.img"
+)
+_DEBIAN = "https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2"
+
+
+def _mixin_with_storages(storages: list[dict]) -> tuple[ProxmoxVMProvisionMixin, MagicMock]:
+    mixin = ProxmoxVMProvisionMixin()
+    mixin._node_name = "pve1"
+    node = MagicMock()
+    node.storage.get.return_value = storages
+    mixin._node_api = MagicMock(return_value=node)
+    return mixin, node
+
+
+# ── which storage ─────────────────────────────────────────────────────────────
+
+
+def test_find_import_storage_picks_a_storage_that_accepts_import():
+    mixin, _ = _mixin_with_storages(
+        [
+            {"storage": "local", "content": "iso,backup,vztmpl,snippets"},
+            {"storage": "software", "content": "import,iso", "active": 1},
+        ]
+    )
+    assert mixin._find_import_storage() == "software"
+
+
+def test_find_import_storage_does_not_mistake_images_for_import():
+    mixin, _ = _mixin_with_storages([{"storage": "local-zfs", "content": "images,rootdir"}])
+    assert mixin._find_import_storage() is None
+
+
+def test_find_import_storage_skips_disabled_and_inactive_storages():
+    """An inactive storage is typically an unmounted share; Proxmox cannot
+    download into it, and the SSH path still works without it."""
+    mixin, _ = _mixin_with_storages(
+        [
+            {"storage": "off", "content": "import", "enabled": 0},
+            {"storage": "unmounted", "content": "import", "active": 0},
+        ]
+    )
+    assert mixin._find_import_storage() is None
+
+
+# ── what the file is called ───────────────────────────────────────────────────
+
+
+def test_import_volume_name_keeps_a_qcow2_extension():
+    name = _import_volume_name(_DEBIAN)
+    assert name is not None
+    assert name.endswith("-debian-12-genericcloud-amd64.qcow2")
+
+
+def test_import_volume_name_stores_an_img_as_qcow2():
+    """Proxmox reads the format off the extension and does not accept .img.
+    Ubuntu's .img is qcow2; guessing qcow2 for a raw .img fails loudly at
+    import, while the opposite guess would import a qcow2 container as a raw
+    disk without complaint."""
+    name = _import_volume_name(_UBUNTU)
+    assert name is not None
+    assert name.endswith("-ubuntu-26.04-server-cloudimg-amd64.qcow2")
+
+
+def test_import_volume_name_is_none_for_types_proxmox_cannot_import():
+    assert _import_volume_name("https://example.org/image.qcow2.xz") is None
+    assert _import_volume_name("https://example.org/installer.iso") is None
+    assert _import_volume_name("https://example.org/noextension") is None
+
+
+def test_import_volume_name_differs_for_the_same_basename_under_another_url():
+    """Ubuntu publishes daily builds under one basename; a cache keyed on the
+    basename alone would serve yesterday's build."""
+    a = _import_volume_name("https://x/release-20260927/ubuntu-26.04-server-cloudimg-amd64.img")
+    b = _import_volume_name("https://x/release-20260928/ubuntu-26.04-server-cloudimg-amd64.img")
+    assert a != b
+
+
+def test_import_volume_name_uses_only_characters_proxmox_keeps():
+    name = _import_volume_name("https://x/My Image (beta)+1.qcow2")
+    assert name is not None
+    assert all(c.isalnum() or c in "-.+=_" for c in name)
+
+
+# ── the download ──────────────────────────────────────────────────────────────
+
+
+def test_import_cloud_image_reuses_a_file_already_in_the_storage():
+    mixin, node = _mixin_with_storages([])
+    name = _import_volume_name(_DEBIAN)
+    node.storage.return_value.content.get.return_value = [
+        {"volid": f"software:import/{name}", "content": "import"}
+    ]
+
+    volid = mixin._import_cloud_image("software", name, _DEBIAN, None, timeout=300)
+
+    assert volid == f"software:import/{name}"
+    node.storage.return_value.return_value.post.assert_not_called()
+
+
+def test_import_cloud_image_has_proxmox_download_and_verify_it():
+    mixin, node = _mixin_with_storages([])
+    name = _import_volume_name(_UBUNTU)
+    node.storage.return_value.content.get.return_value = []
+    download = node.storage.return_value.return_value
+    download.post.return_value = "UPID:pve1:download"
+    mixin._wait_for_task = MagicMock()
+
+    volid = mixin._import_cloud_image("software", name, _UBUNTU, "sha256:abc123", timeout=300)
+
+    assert volid == f"software:import/{name}"
+    node.storage.assert_any_call("software")
+    node.storage.return_value.assert_called_with("download-url")
+    download.post.assert_called_once_with(
+        url=_UBUNTU,
+        content="import",
+        filename=name,
+        checksum="abc123",
+        **{"checksum-algorithm": "sha256"},
+    )
+    mixin._wait_for_task.assert_called_once_with("UPID:pve1:download", timeout=300)
+
+
+def test_import_cloud_image_without_checksum_sends_none():
+    mixin, node = _mixin_with_storages([])
+    name = _import_volume_name(_DEBIAN)
+    node.storage.return_value.content.get.return_value = []
+    mixin._wait_for_task = MagicMock()
+
+    mixin._import_cloud_image("software", name, _DEBIAN, None, timeout=300)
+
+    kwargs = node.storage.return_value.return_value.post.call_args.kwargs
+    assert "checksum" not in kwargs
+    assert "checksum-algorithm" not in kwargs
+
+
+# ── provisioning end to end ───────────────────────────────────────────────────
+
+
+def _provisioning_mixin(storages: list[dict]) -> tuple[ProxmoxVMProvisionMixin, MagicMock]:
+    mixin, node = _mixin_with_storages(storages)
+    api = MagicMock()
+    api.cluster.nextid.get.return_value = 101
+    api.storage.return_value.get.return_value = {"path": "/var/lib/vz"}
+    mixin._api = api
+    mixin._run_node_command = MagicMock(return_value="")
+    mixin._download_cloud_image = MagicMock(return_value="/var/lib/vz/template/x.qcow2")
+    vm = MagicMock()
+    node.qemu.return_value = vm
+    vm.config.get.return_value = {"unused0": "local-zfs:vm-101-disk-0"}
+    vm.config.post.return_value = None
+    node.tasks.return_value.status.get.return_value = {"status": "stopped", "exitstatus": "OK"}
+    node.storage.return_value.content.get.return_value = []
+    return mixin, node
+
+
+def _provision(mixin: ProxmoxVMProvisionMixin, image_url: str) -> None:
+    with patch("time.sleep"):
+        mixin.create_vm_from_cloud_init(
+            name="vm",
+            image_url=image_url,
+            cpu=1,
+            memory=1024,
+            nics=[{"bridge": "vmbr0"}],
+            cloud_init_config={"hostname": "vm"},
+            storage="local-zfs",
+            timeout=60,
+        )
+
+
+_WITH_IMPORT = [
+    {"storage": "local", "content": "iso,backup,vztmpl,snippets"},
+    {"storage": "software", "content": "import,iso"},
+    {"storage": "local-zfs", "content": "images,rootdir"},
+]
+
+
+def test_provisioning_downloads_through_the_import_storage_when_there_is_one():
+    mixin, node = _provisioning_mixin(_WITH_IMPORT)
+    name = _import_volume_name(_UBUNTU)
+
+    _provision(mixin, _UBUNTU)
+
+    mixin._download_cloud_image.assert_not_called()
+    assert not any("importdisk" in c.args[0] for c in mixin._run_node_command.call_args_list), (
+        "no SSH download/import when Proxmox can do it"
+    )
+    disk = next(
+        c.kwargs for c in node.qemu.return_value.config.post.call_args_list if "scsi0" in c.kwargs
+    )
+    assert disk["scsi0"] == f"local-zfs:0,import-from=software:import/{name},discard=on"
+    assert disk["boot"] == "order=scsi0"
+
+
+def test_provisioning_waits_for_the_import_task():
+    """Attaching with import-from copies the image — a task, which has to
+    finish before the cloud-init drive and the resize touch the VM."""
+    mixin, node = _provisioning_mixin(_WITH_IMPORT)
+    node.qemu.return_value.config.post.side_effect = lambda **kw: (
+        "UPID:pve1:import" if "scsi0" in kw else None
+    )
+    mixin._wait_for_task = MagicMock()
+
+    _provision(mixin, _DEBIAN)
+
+    waited = [c.args[0] for c in mixin._wait_for_task.call_args_list]
+    assert "UPID:pve1:import" in waited
+
+
+def test_provisioning_falls_back_to_ssh_without_an_import_storage():
+    mixin, _ = _provisioning_mixin([s for s in _WITH_IMPORT if s["storage"] != "software"])
+
+    _provision(mixin, _UBUNTU)
+
+    mixin._download_cloud_image.assert_called_once()
+    assert any("qm importdisk 101" in c.args[0] for c in mixin._run_node_command.call_args_list)
+
+
+def test_provisioning_falls_back_to_ssh_for_an_image_type_proxmox_cannot_import():
+    mixin, _ = _provisioning_mixin(_WITH_IMPORT)
+
+    _provision(mixin, "https://example.org/image.qcow2.xz")
+
+    mixin._download_cloud_image.assert_called_once()

tests/test_vm_snapshots.py

@@ -0,0 +1,95 @@
+"""HypervisorDriver snapshot methods on Proxmox (QEMU and LXC)."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+
+SNAPSHOTS = [
+    {"name": "base", "description": "clean install", "snaptime": 1700000000, "vmstate": 0},
+    {"name": "upgrade", "description": "", "snaptime": 1700000100, "parent": "base", "vmstate": 1},
+    {"name": "current", "description": "You are here!", "parent": "upgrade", "running": 1},
+]
+
+
+@pytest.fixture
+def api(driver):
+    node = driver._node_api()
+    node.qemu.get.return_value = [{"vmid": 100, "name": "web01"}]
+    node.lxc.get.return_value = [{"vmid": 200, "name": "dns01"}]
+    node.qemu.return_value.snapshot.get.return_value = SNAPSHOTS
+    driver._wait_for_task = MagicMock()
+    return node
+
+
+class TestList:
+    def test_flattens_and_skips_the_current_marker(self, driver, api):
+        assert driver.get_vm_snapshots("web01") == [
+            {
+                "name": "base",
+                "vm": "web01",
+                "created": 1700000000.0,
+                "description": "clean install",
+                "has_memory": False,
+                "parent": "",
+            },
+            {
+                "name": "upgrade",
+                "vm": "web01",
+                "created": 1700000100.0,
+                "description": "",
+                "has_memory": True,
+                "parent": "base",
+            },
+        ]
+
+    def test_unknown_vm(self, driver, api):
+        with pytest.raises(ValueError):
+            driver.get_vm_snapshots("nope")
+
+
+class TestCreate:
+    def test_vm_with_memory(self, driver, api):
+        api.qemu.return_value.snapshot.post.return_value = "UPID:snap"
+        driver.create_vm_snapshot("100", "pre", description="d", include_memory=True)
+        api.qemu.return_value.snapshot.post.assert_called_once_with(
+            snapname="pre", description="d", vmstate=1
+        )
+        driver._wait_for_task.assert_called_once_with("UPID:snap", timeout=600)
+
+    def test_container_never_saves_memory(self, driver, api):
+        api.lxc.return_value.snapshot.get.return_value = []
+        driver.create_vm_snapshot("200", "pre", include_memory=True)
+        api.lxc.return_value.snapshot.post.assert_called_once_with(snapname="pre", description="")
+
+    def test_duplicate_name(self, driver, api):
+        with pytest.raises(ValueError, match="already"):
+            driver.create_vm_snapshot("web01", "base")
+
+    def test_api_refusal(self, driver, api):
+        api.qemu.return_value.snapshot.post.side_effect = Exception(
+            "snapshot feature is not available"
+        )
+        with pytest.raises(RuntimeError, match="not available"):
+            driver.create_vm_snapshot("web01", "new")
+
+
+class TestDeleteAndRollback:
+    def test_delete(self, driver, api):
+        driver.delete_vm_snapshot("web01", "base")
+        api.qemu.return_value.snapshot.assert_called_with("base")
+        api.qemu.return_value.snapshot.return_value.delete.assert_called_once_with()
+
+    def test_rollback(self, driver, api):
+        driver.rollback_vm_snapshot("web01", "upgrade")
+        api.qemu.return_value.snapshot.return_value.rollback.post.assert_called_once_with()
+
+    @pytest.mark.parametrize("method", ["delete_vm_snapshot", "rollback_vm_snapshot"])
+    def test_unknown_snapshot(self, driver, api, method):
+        with pytest.raises(ValueError, match="no snapshot"):
+            getattr(driver, method)("web01", "nope")
+
+    def test_current_is_not_a_snapshot(self, driver, api):
+        with pytest.raises(ValueError):
+            driver.rollback_vm_snapshot("web01", "current")