pipam Overview

pipam is a distributed daemon that collects VM and LXC network data from Proxmox and syncs it to DNS (PowerDNS) and optionally IPAM (NetBox). It can run as a single node or as a 3+ node raft cluster for high availability.

Architecture

graph LR
    PVE[Proxmox API] -->|collect| Collector
    Collector -->|snapshot| Raft[Raft Consensus]
    Raft -->|committed state| Diff[State Diff]
    Diff -->|added/changed/removed| Reconciler
    Reconciler -->|A/AAAA records| PDNS[PowerDNS]
    Reconciler -->|VMs/IPs| NB[NetBox]
    Reconciler -->|reconciled state| Raft

Cluster mode

In cluster mode, only the raft leader performs collection and reconciliation. Followers replicate state for failover.

sequenceDiagram
    participant L as Leader
    participant R as Raft (all nodes)
    participant DNS as PowerDNS
    participant IPAM as NetBox

    L->>L: Collect VMs/LXCs from Proxmox
    L->>R: Propose snapshot
    R->>R: Commit & apply to FSM
    R-->>L: Applied signal
    L->>L: Diff(reconciled, current)
    L->>DNS: EnsureRecord / DeleteRecord
    L->>IPAM: EnsureVM / DeleteVM
    L->>R: Propose reconciled state
    R->>R: Commit reconciled state

    Note over R: On leader failover, new leader<br/>reads reconciled state from FSM —<br/>failed entries are retried automatically

Single-node mode

When raft.node_id is not set (or 0), pipam runs without raft — a simple collect, diff, reconcile loop with in-memory state.

graph LR
    PVE[Proxmox API] -->|collect| C[Collector]
    C -->|snapshot| D[Diff]
    D -->|changes| R[Reconciler]
    R -->|DNS records| PDNS[PowerDNS]
    R -->|IPAM entries| NB[NetBox]

CLI commands

pipam run                          # daemon mode
pipam run --config /etc/pipam.toml # with explicit config
pipam output                       # one-shot: print collected state
pipam output --json                # one-shot: JSON to stdout
pipam reconcile                    # one-shot: full reconcile of all entries
pipam clean                        # remove all managed DNS/IPAM entries
pipam clean --collect              # collect fresh from Proxmox, then remove
pipam health                       # check provider connectivity

Global flags

Flag	Default	Description
--config, -c	$XDG_CONFIG_HOME/pipam/config.toml	Config file path
--log-format	text	Log format (text, json)
--log-level	info	Log level (debug, info, warning, error)

Building

pipam is part of the Go workspace rooted at go.work. Build from the module directory:

cd code/proxmox-ipam
go build ./cmd/pipam

Debian package

Builds a .deb using nfpm. The package is a static Go binary.

make deb                           # default (amd64)
make deb ARCH=arm64 GOARCH=arm64   # cross-compile
sudo dpkg -i pipam_*.deb

The package installs:

Path	Purpose
/usr/bin/pipam	Binary
/etc/pipam/config.toml	Config (preserved on upgrade)
/etc/pipam/secrets/	Secret files (root:pipam, 0750)
/etc/default/pipam	Environment overrides
/var/lib/pipam/	WAL and raft state
/lib/systemd/system/pipam.service	Systemd unit

Docker

docker build -f code/proxmox-ipam/Dockerfile .

# 3-node cluster example
docker compose -f code/proxmox-ipam/examples/basic-docker/docker-compose.yaml up --build