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

Cluster mode

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

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.

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