Technical Information

Proxmox VE to NetBox Object Mapping

This document provides a comprehensive mapping of Proxmox VE object types to their corresponding NetBox object types, based on the integration implementation.

Object Type Mapping Table

Rows are ordered infrastructure-first (cluster → node → VM), then shared objects (VLANs, disks). Config parameters are marked (config).

Proxmox VE Object	NetBox Object Type	Proxmox VE Field	Notes
Cluster Type	ClusterType	(static)	Created once; shared by all clusters. Not sourced from the Proxmox API. Sets name="Proxmox", slug="proxmox".
Cluster	Cluster	cluster_name
SITE_NAME (config)
(static)	Name auto-detected from /cluster/status API, overridden by CLUSTER_NAME config, or falls back to PROXMOX_HOST. SITE_NAME → scope_site. type always "Proxmox". Status always active.
Node Platform	Platform	pveversion	Parsed from pve-manager/X.Y.Z/hash — major.minor only. Platform name set to "Proxmox VE X.Y". Each node may carry a different version platform.
Node	Device	node
status
pveversion (→ platform)
SITE_NAME / NODE_SITE_MAP (config)
maxcpu
maxmem	DeviceType "Proxmox Node", DeviceRole "Hypervisor", Manufacturer "Proxmox". maxcpu → proxmox_cpu_count; maxmem → proxmox_memory_mb. Status mapped — see Node Status.
Node Interface	Interface	iface
type
speed (Mbps)
mtu	iface → interface name. Loopback and interfaces without a resolvable IP are skipped. speed converted Mbps → kbps (×1000). Type mapped — see Interface Types.
Node IP Address	IPAddress	cidr (or address + netmask)
Interface ref	Tries cidr first; falls back to address+netmask. First IPv4 and IPv6 per node set as device primary_ip4 / primary_ip6.
Network Prefix	Prefix	network address (derived from interface CIDR)
SITE_NAME / NODE_SITE_MAP (config)	Derived from node interface IPs. Host routes (/32, /128) and loopback excluded. One prefix per unique (network, site) pair.
VM/LXC Platform	Platform	QEMU: guest agent name + version-id
Fallback: ostype (VM config)	QEMU: guest agent preferred (e.g. "Ubuntu 24.04"); falls back to ostype map if agent unavailable. LXC: always uses ostype map. unmanaged / other → no platform created. See VM Platform Mapping.
VM / LXC Container	VirtualMachine	name
status
maxcpu
maxmem
description
tags
onboot	maxcpu → vcpus; maxmem → memory; description → comments; onboot → start_on_boot. Templates (template == 1) skipped. Status mapped — see VM Status. Proxmox tags (;-separated) forwarded as NetBox tags.
VM / LXC Custom Fields	VirtualMachine	vmid → proxmox_vmid
node → proxmox_node
type → proxmox_vm_type
hastate → proxmox_ha_state	proxmox_ha_state only populated when HA is configured for the VM/container. proxmox_vm_type is qemu or lxc.
VM / LXC Interface	VMInterface	QEMU: netN key, MAC from driver string, tag=
LXC: name field (or netN), hwaddr, tag	QEMU: interface named by config key (net0, net1, …). LXC: interface named from name=eth0 field, falling back to netN key. MAC → primary_mac_address; tag= → untagged_vlan.
QEMU VM IP Address	IPAddress	ip-address + prefix (guest agent)
VMInterface ref (MAC-matched)	Requires QEMU guest agent installed and running in the VM. IPs matched to VMInterfaces by MAC address. Loopback (lo, docker0) and link-local excluded.
LXC Container IP Address	IPAddress	ip / ip6 (net config)
VMInterface ref	Parsed from container net config. Values dhcp, manual, auto skipped. Loopback and link-local excluded. No guest agent required.
VLAN	VLAN	vlanid (node interface) or untagged_vlan.vid (VM interface)
(auto-generated)
SITE_NAME / NODE_SITE_MAP (config)	Two sources: node interfaces of type vlan (with vlanid), and VM/LXC interface VLAN tags. Named "VLAN {vid}". Deduplicated by (vid, site).
Virtual Disk	VirtualDisk	disk config key
size from config value
storage pool from config value	QEMU keys: scsi*, virtio*, ide*, sata*. LXC keys: rootfs, mp*. Cloud-init, CDROMs, none skipped. Size (MB) stored in size; pool stored in proxmox_storage_pool. Size suffixes M/G/T converted to MB.

---

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)