Christian Manivong daf1b519eb
driver / standard (pull_request) Successful in 18s
driver / lint (pull_request) Successful in 16s
driver / types (pull_request) Successful in 1m10s
driver / test (3.12) (pull_request) Successful in 1m9s
driver / test (3.13) (pull_request) Successful in 1m4s
driver / lowest (pull_request) Successful in 35s
driver / build (pull_request) Successful in 40s
driver / security (pull_request) Successful in 1m15s
CI / driver (pull_request) Successful in 2m53s
driver / publish (pull_request) Skipped
fix(ssh): raise when a node command cannot run, drop the execute call
_exec_ssh_command returned "" on any failure (no SSH credential, a
refused login or host key, an unreachable node, a timeout), so a
getter that could not look read like one that found nothing; on
API-token-only nodes get_snmp_config answered None and the SSH-backed
getters empty lists on every poll. It now raises ConnectionException
with the cause (SshHostKeyMismatch as it is), and refuses before
connecting when there is neither a password nor a usable key.

It returned stderr when stdout was empty; output is stdout now. It
first posted every command to /nodes/{node}/execute, which runs a
batch of API calls rather than a shell; that dead round trip is gone.

The key types, the key before the password, the host-key check and the
single connect path were done in f491f9f and 6bb3035. The shared
transport is NAPALM/napalm-device-types#35.

Closes #17
2026-11-02 08:52:32 +01:00
2026-05-29 09:24:39 +02:00
2026-05-29 09:24:39 +02:00

napalm-proxmox

A NAPALM driver for Proxmox VE nodes.

It supports all three networking domains of Proxmox VE:

Domain Description
Classic Linux /etc/network/interfaces, Linux bridges, VLANs
SDN Zones (VLAN, QinQ, VXLAN, EVPN), VNets, subnets
OVS Open vSwitch bridges, bonds, and internal ports

Requirements

  • Python ≥ 3.12
  • NAPALM ≥ 5.0.0
  • napalm-device-types ≥ 4.22.0
  • proxmoxer ≥ 2.0.0
  • netaddr ≥ 0.9.0
  • requests ≥ 2.31.0

Installation

pip install napalm-proxmox

Or directly from source:

git clone https://git.netork.io/NAPALM/napalm-proxmox.git
cd napalm-proxmox
pip install -e .

Usage

Password authentication

from napalm import get_network_driver

driver = get_network_driver("proxmox")
device = driver(
    hostname="pve1.example.com",
    username="root",
    password="secret",
    optional_args={
        "realm": "pam",  # default: "pam"
        "port": 8006,  # default: 8006
        "verify_ssl": True,  # default: True
    },
)

with device:
    facts = device.get_facts()
    print(facts)
    # {'vendor': 'Proxmox Server Solutions GmbH', 'model': 'PowerEdge R640',
    #  'hostname': 'pve1', 'os_version': 'Proxmox VE 8.2.4', ...}

    interfaces = device.get_interfaces()
    interfaces_ip = device.get_interfaces_ip()
    vlans = device.get_vlans()
    network_instances = device.get_network_instances()

API token authentication

device = driver(
    hostname="pve1.example.com",
    username="napalm",
    password="",
    optional_args={
        "token_name": "napalm@pam!napalm-token",
        "token_value": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    },
)

Targeting a specific node

In a multi-node cluster the driver auto-detects the node by matching the hostname against the cluster's node list. You can also pin a specific node:

device = driver(
    hostname="pve-cluster.example.com",  # cluster VIP
    username="root",
    password="secret",
    optional_args={"node": "pve2"},
)

Supported NAPALM methods

Method Notes
open / close Password + API token auth
is_alive Checks /api2/json/version
get_facts vendor, model, hostname, os_version, uptime, interface_list, fqdn
get_interfaces eth, bridge, OVS bridge/bond; speed, MTU, MAC, status
get_interfaces_ip IPv4/IPv6 from classic ifaces + SDN subnet gateways
get_interfaces_counters From node/netstat RRD data
get_environment CPU %, memory (bytes), hardware temperature sensors
get_arp_table Reads /proc/net/arp over SSH
get_mac_address_table bridge fdb show (Linux) + ovs-appctl fdb/show (OVS)
get_vlans SDN VNet tags + bridge vlan show
get_network_instances SDN zones (VLAN→L2VPN, EVPN→L3VRF) + default instance
get_ntp_servers From node/ntp API
get_ntp_stats Parses chronyc / ntpq -pn output
get_snmp_information Parses /etc/snmp/snmpd.conf
get_users Proxmox access/users API + local /etc/passwd
get_config /etc/network/interfaces + SDN config; sanitize support
load_merge_candidate / load_replace_candidate String or file
compare_config Unified diff
commit_config Writes /etc/network/interfaces + ifreload -a
discard_config / rollback Revert candidate
get_lldp_neighbors lldpcli show neighbors over SSH
get_lldp_neighbors_detail Full LLDP detail
get_ipv6_neighbors_table ip -6 neigh show
ping Linux ping over SSH
traceroute traceroute -n over SSH
cli Arbitrary commands over SSH (stdout)
get_route_to ip route show over SSH

Not implemented (raise NotImplementedError): get_bgp_config, get_bgp_neighbors, get_bgp_neighbors_detail, get_optics, get_probes_config, get_probes_results, get_firewall_policies

Optional arguments

Argument Type Default Description
port int 8006 Proxmox API port
verify_ssl bool True Verify TLS certificate
realm str "pam" PAM realm for password auth
node str auto Override target node name
token_name str None API token identifier (user@realm!tokenid)
token_value str None API token secret
ssh_username str username Login for the node's SSH (port 22)
ssh_password str password SSH password; the API password when not set
ssh_private_key_str str None SSH private key (Ed25519, ECDSA or RSA), tried before the password

What the API does not offer (ARP, LLDP, packages, SNMP config, cli, …) runs in the node's shell over SSH. Without an SSH password or key — a node reached with an API token only — those calls raise ConnectionException instead of reading as empty.

Development

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests with coverage
pytest --cov=napalm_proxmox --cov-report=term-missing

# Lint
ruff check napalm_proxmox

Architecture

napalm_proxmox/
├── __init__.py     # Exports ProxmoxDriver
├── driver.py       # ProxmoxDriver — all NAPALM methods
└── utils.py        # MAC normalisation, CIDR parsing, ARP/OVS parsers
tests/
├── conftest.py          # Shared fixtures and mock API payloads
├── test_connection.py   # open / close / is_alive
├── test_get_facts.py    # get_facts
├── test_interfaces.py   # get_interfaces, get_interfaces_ip, get_interfaces_counters
├── test_environment.py  # get_environment
├── test_sdn.py          # get_vlans, get_network_instances
├── test_ovs_and_arp.py  # get_arp_table, get_mac_address_table, ARP/OVS utils
├── test_misc.py         # NTP, SNMP, users, config, ping, traceroute, CLI, LLDP
└── test_utils.py        # Unit tests for napalm_proxmox.utils

License

Apache License 2.0 — see LICENSE.

S
Description
No description provided
Readme
1.2 MiB
0 Stars 1 Watchers 0 Forks
2026-11-03 04:24:56 +00:00
Languages
Python 100%