Per-VM Configuration

Individual VMs and LXCs can carry pipam-specific configuration in their Proxmox description field. This allows per-entry overrides without changing the global config.

Format

Embed a JSON or YAML block between markers in the Proxmox description (Notes tab in the web UI):

Some regular description text here.

=== Start PIPAM CFG ===
{
  "tags": ["managed", "k8s-master"],
  "primary_mac": "bc:24:12:2f:cf:a8",
  "mapping": {
    "10.50.0.0/23": "services.homelab.muehlena.de",
    "10.202.0.0/16": "mgmt.homelab.muehlena.de"
  },
  "ip_map": {
    "10.50.0.18/32": "10.50.0.18/16"
  },
  "extra_names": ["nzbget"],
  "skip_interface_names": ["cilium_host"],
  "skip_interface_patterns": ["^lxc", "^cilium"]
}
=== End PIPAM CFG ===

YAML is also supported:

=== Start PIPAM CFG ===
tags:
  - managed
  - k8s-master
primary_mac: "bc:24:12:2f:cf:a8"
mapping:
  "10.50.0.0/23": services.homelab.muehlena.de
  "10.202.0.0/16": mgmt.homelab.muehlena.de
ip_map:
  "10.50.0.18/32": "10.50.0.18/16"
extra_names:
  - nzbget
skip_interface_names:
  - cilium_host
skip_interface_patterns:
  - "^lxc"
  - "^cilium"
=== End PIPAM CFG ===

The parser tries JSON first, then YAML. Text outside the markers is ignored.

Fields

All fields are optional.

tags

Additional tags to apply to the VM in NetBox. These are merged with tags from Proxmox (the semicolon-separated tag field) and the automatic type tag (qemu/lxc). Duplicates are removed.

{ "tags": ["managed", "production"] }

Tags listed here are only included in NetBox if they already exist there (same behaviour as Proxmox tags). Only the qemu and lxc type tags are created automatically.

primary_mac

MAC address of the interface whose IPs should be set as primary on the NetBox VM object. Without this, the single-interface heuristic applies (primary IPs are only set when the VM has exactly one interface).

{ "primary_mac": "bc:24:12:2f:cf:a8" }

mapping

Per-network domain mapping overrides. Keys are CIDRs, values are domain names. IPs matching a CIDR key use the corresponding domain instead of the global [mapping] config. Longest-prefix-match applies when CIDRs overlap.

{
  "mapping": {
    "10.50.0.0/23": "services.homelab.muehlena.de",
    "10.202.0.0/16": "mgmt.homelab.muehlena.de"
  }
}

This affects:

• DNS record FQDN resolution (hostname + domain)
• IPAM filtering (IPs matching a mapping override are included)
• Entry inclusion (VMs with a mapping override are collected even without a global mapping match)

ip_map

Remaps IP CIDRs during collection. Keys are the original address/prefix as reported by Proxmox, values are the desired address/prefix. This is applied before any DNS or IPAM processing.

Common use case — override prefix lengths when Proxmox reports /32 for VIPs but NetBox expects the actual subnet prefix:

{
  "ip_map": {
    "10.50.0.18/32": "10.50.0.18/16",
    "10.50.0.19/32": "10.50.0.19/16"
  }
}

The address part can also be changed (full remap), though this is rarely needed.

extra_names

Additional DNS names to publish for this guest, pointing at the same IPs as the primary hostname. Each name is resolved to an FQDN exactly like the hostname: a bare label gets the per-IP mapping domain appended, while a value that already contains a dot is used verbatim. Records (A/AAAA) are created and cleaned up alongside the hostname’s — service records are not duplicated for extra names.

{ "extra_names": ["nzbget"] }

On a host in services.homelab.muehlena.de this also publishes nzbget.services.homelab.muehlena.de → the host’s IPs, e.g. to give a service its own cert-matching name.

skip_interface_names

Guest interface names to ignore during collection (exact match). Interfaces skipped here are never written to NetBox, which stops churn from ephemeral virtual interfaces.

{ "skip_interface_names": ["cilium_host", "cilium_net", "docker0"] }

skip_interface_patterns

RE2 regexes matched against the guest interface name; a match drops the interface during collection. Use for whole families of ephemeral interfaces (Cilium/pod veths, Docker, etc.) whose names and IPs change every sweep and would otherwise be endlessly added and removed in NetBox. Patterns that fail to compile are logged and ignored.

{ "skip_interface_patterns": ["^lxc", "^cilium", "^veth"] }

Both skip lists are applied to VM and LXC interfaces. Names/patterns match the guest interface name (e.g. cilium_host, lxc1a2b3c), not the eth-<mac> name pipam gives the resulting NetBox interface.