Technical Information

Proxmox VE to NetBox Object Mapping

Object Type Mapping Table

Proxmox VE Object	NetBox Object	Key Attributes
(static)	ClusterType	name "Proxmox", slug "proxmox"
Cluster	Cluster	name, type "Proxmox", scope_site (from SITE_NAME config)
pveversion	Platform	name "Proxmox VE X.Y" (major.minor per node)
Node	Device	node → name, status, platform, site, custom_fields.proxmox_cpu_count, custom_fields.proxmox_memory_mb
Node network interface	Interface	iface → name, type, speed (Mbps → kbps), mtu
Node interface IP	IPAddress	cidr → address, sets device primary_ip4/primary_ip6
(derived from node interface IPs)	Prefix	network address, status "active", scope_site
QEMU / LXC guest OS	Platform	name from guest agent or ostype map
VM / LXC Container	VirtualMachine	name, status, vcpus, memory, comments, tags, custom_fields.proxmox_vmid, custom_fields.proxmox_node, custom_fields.proxmox_vm_type, custom_fields.proxmox_ha_state
VM / LXC network interface	VMInterface	name, primary_mac_address, untagged_vlan
QEMU VM IP (guest agent)	IPAddress	address (CIDR), matched to VMInterface by MAC
LXC container IP	IPAddress	ip/ip6 from net config → address
Node interface VLAN / VM interface tag	VLAN	vid, name "VLAN {vid}", scope_site
VM / LXC disk config	VirtualDisk	name, size (MB), custom_fields.proxmox_storage_pool

---

Field Mapping Details

VM / LXC Container Status Mapping

Proxmox Status	NetBox Status
running	active
stopped	offline
any other	staged

Node (Device) Status Mapping

Proxmox Node Status	NetBox Status
online	active
any other	offline

Node Interface Type Mapping

Proxmox Interface Type	NetBox Interface Type
bridge	bridge
bond	lag
vlan	virtual
alias	virtual
OVSBridge	bridge
OVSBond	lag
OVSPort	virtual
OVSIntPort	virtual
(any other)	other

VM Platform Mapping (from ostype)

Proxmox ostype	NetBox Platform
l24	Linux
l26	Linux
w2k	Windows 2000
w2k3	Windows Server 2003
w2k8	Windows Server 2008
wvista	Windows Vista
win7	Windows 7
win8	Windows 8/2012
win10	Windows 10/2016/2019
win11	Windows 11/2022
solaris	Solaris
debian	Debian
ubuntu	Ubuntu
centos	CentOS
fedora	Fedora
opensuse	openSUSE
archlinux	Arch Linux
alpine	Alpine Linux
gentoo	Gentoo
nixos	NixOS
unmanaged	(no platform)
other	(no platform)
(unknown)	(ostype title-cased)

Additional Info

For QEMU VMs with the guest agent installed and running, the guest agent OS info takes precedence over the ostype map. The guest agent provides a more specific platform name (e.g., "Ubuntu 24.04" instead of "Linux").

Node Platform

Proxmox VE node platforms are derived from the pveversion string returned by the node status API. The format is pve-manager/X.Y.Z/hash, and the platform is created as "Proxmox VE X.Y" (major.minor only). Each node may have a different platform version.

---

Custom Fields

The integration creates the following custom fields in NetBox during bootstrap:

Custom Field	Label	Type	Object Type	Purpose
proxmox_vmid	Proxmox VM ID	Text	VirtualMachine	The unique numeric ID assigned to this VM or container by Proxmox VE
proxmox_node	Proxmox Node	Text	VirtualMachine	The Proxmox VE cluster node that this VM or container is running on
proxmox_ha_state	Proxmox HA State	Text	VirtualMachine	High-availability state as reported by the Proxmox VE HA manager (e.g. started, stopped, fence)
proxmox_cpu_count	Proxmox CPU Count	Integer	Device	Total number of logical CPU cores available on this Proxmox VE node
proxmox_memory_mb	Proxmox Memory (MB)	Integer	Device	Total physical memory installed on this Proxmox VE node, in megabytes
proxmox_vm_type	Proxmox VM Type	Text	VirtualMachine	Proxmox VE virtualisation type: qemu for KVM VMs or lxc for Linux containers
proxmox_storage_pool	Proxmox Storage Pool	Text	VirtualDisk	Proxmox VE storage pool (e.g. local-lvm, ceph) from which this virtual disk is allocated

---

Policy Configuration

Config Parameters

Parameter	Required	Default	Description
BOOTSTRAP	No	false	When true, creates only static entities (custom fields, cluster type, tags); no API calls to Proxmox
PROXMOX_HOST	Yes (non-bootstrap)	—	Proxmox VE hostname or IP address
PROXMOX_PORT	No	8006	Proxmox VE API port
PROXMOX_USER	No	root@pam	Proxmox VE user for API token authentication (format: user@realm)
PROXMOX_TOKEN_NAME	Yes (non-bootstrap)	—	API token ID (the name portion, e.g. netbox-integration)
PROXMOX_TOKEN_VALUE	Yes (non-bootstrap)	—	API token secret value
PROXMOX_SSL_VERIFY	No	false	Enable/disable SSL certificate verification for HTTPS API calls
PROXMOX_API_TIMEOUT	No	30	API request timeout in seconds
CLUSTER_NAME	No	(auto-detected)	Override the auto-detected Proxmox cluster name
SITE_NAME	No	Proxmox	Default NetBox site name assigned to nodes and VMs (used as fallback for NODE_SITE_MAP)
NODE_SITE_MAP	No	—	Comma-separated node:site pairs for per-node site assignment (e.g. "pve1:London,pve2:Amsterdam")

Scope Parameters

Parameter	Default	Description
nodes	["*"]	List of Proxmox node names to include. Use ["*"] for all nodes.

---

Tags and Metadata

Global Tags

All created entities are automatically tagged with:

• proxmox-ve — identifies objects from Proxmox VE
• discovered — marks objects as auto-discovered
• proxmox-{hostname} — unique per Proxmox host (not applied in bootstrap mode)

Tag Colors

Tag	Color
proxmox-ve	Orange (#e57000)
discovered	Green (#198754)
proxmox-{hostname}	Amber (#fd7e14)

Proxmox VM Tags

Proxmox VE allows assigning tags to VMs and containers. These tags (semicolon-separated in the Proxmox API response) are forwarded directly to NetBox as tags on the VirtualMachine object, in addition to the global tags above.

---

API and Behaviour Notes

Proxmox VE APIs Used

The integration communicates with the following Proxmox VE REST API endpoints:

• GET /cluster/resources?type=vm — full VM/container inventory across all nodes
• GET /cluster/status — cluster name and node membership
• GET /nodes — list of cluster nodes with CPU/memory info
• GET /nodes/{node}/status — per-node status including PVE version
• GET /nodes/{node}/network — per-node network interface configuration
• GET /nodes/\{node\}/qemu/{vmid}/config — QEMU VM configuration (disks, interfaces, ostype)
• GET /nodes/\{node\}/lxc/{vmid}/config — LXC container configuration
• GET /nodes/\{node\}/qemu/{vmid}/agent/get-osinfo — guest agent OS information (QEMU only)
• GET /nodes/\{node\}/qemu/{vmid}/agent/network-get-interfaces — guest agent network interfaces and IPs (QEMU only)

Authentication

The integration uses Proxmox API token authentication exclusively. Username/password (cookie/ticket) authentication is not supported. You must create a Proxmox API token and provide:

• PROXMOX_USER — the user that owns the token (e.g., root@pam)
• PROXMOX_TOKEN_NAME — the token ID
• PROXMOX_TOKEN_VALUE — the token secret

Bootstrap Mode

In bootstrap mode, the integration creates the following static entities without connecting to the Proxmox API:

1. ClusterType — "Proxmox"
2. CustomFields — all 7 custom fields (see Custom Fields)
3. Tags — proxmox-ve, discovered (not the unique host tag)

The unique host tag (proxmox-{hostname}) is only created during regular (non-bootstrap) operation.

Cluster Name Resolution

The cluster name is determined in this order:

1. CLUSTER_NAME config parameter (if set)
2. Cluster name from GET /cluster/status API (type=cluster entry)
3. Falls back to the value of PROXMOX_HOST

VM/Container Inventory

• Templates are detected via template == 1 in the inventory and are always skipped
• Only qemu and lxc types are processed; other types are ignored
• VMs with missing vmid or name are skipped

IP Address Discovery

• QEMU VMs: IP addresses are retrieved from the QEMU guest agent (network-get-interfaces). The guest agent must be installed and running inside the VM. IPs are matched to VMInterfaces by MAC address (OS interface names from the guest agent differ from Proxmox config keys)
• LXC containers: IP addresses are parsed from the net config ip= and ip6= fields. dhcp, manual, and auto values are skipped
• Loopback (lo, docker0) and link-local addresses are skipped for both VM types

Prefix Discovery

Prefixes are derived from node network interface IP addresses. Host routes (/32 and /128) and loopback interfaces are excluded. Each unique (network cidr, site) pair produces one Prefix.

VLAN Discovery

VLANs are collected from two sources:

1. Node network interfaces with type=vlan and a vlanid field
2. VM interface configurations with an untagged VLAN tag (tag= in QEMU, tag in LXC)

VLANs are named "VLAN {vid}" and scoped to the site of the node they were discovered on. Duplicates (same vid + site) are deduplicated.

Virtual Disk Discovery

• QEMU: disk config keys matching scsi*, virtio*, ide*, sata* are processed. Cloud-init drives, CD-ROMs (media=cdrom), and none values are skipped.
• LXC: rootfs and mount point keys (mp0, mp1, ...) are processed.
• Disk sizes are stored in MB. Proxmox size suffixes M (megabytes), G (gigabytes), and T (terabytes) are all converted to MB.

Retry Behaviour

The integration automatically retries failed API requests on transient HTTP errors (status codes 429, 502, 503, 504) with a maximum of 5 attempts.

Entity Emission Order

Entities are emitted to Diode in dependency order to ensure Assurance can correctly apply deviations:

1. Tags
2. Custom Fields
3. Cluster Type
4. Clusters
5. Platforms
6. VLANs
7. VM Interfaces
8. Node Interfaces
9. IP Addresses
10. Prefixes
11. Virtual Machines (references already-existing IPs for primary_ip4/primary_ip6)
12. Virtual Disks
13. Devices (references already-existing IPs for primary_ip4/primary_ip6)