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"
  }
}
=== 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"
=== 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.