Skip to main content

Discovering Proxmox with Faddom

Available from v2026.3 and later

Written by Egor Marachev

Faddom maps Proxmox VE environments through two connections: each Proxmox host sends flow records to Faddom over IPFIX, and Faddom reads the hosts and VMs from the Proxmox API.

Requirement

Use

Direction and port

softflowd on each Proxmox host

Traffic between VMs and to the rest of the network

Proxmox to Faddom, UDP 4739

Proxmox API token

Inventory of hosts and VMs

Faddom to Proxmox, TCP 8006

QEMU Guest Agent in each VM

VM IP addresses

Inside each VM

Step 1: Install softflowd on one Proxmox host

  1. Install softflowd:

    apt install -y softflowd

  2. Open /etc/softflowd/default.conf with nano and set these two lines. Replace FADDOM_IP with the Faddom server’s IP:

    interface='vmbr0'
    options='-n FADDOM_IP:4739 -v 10 -t maxlife=60 -s 20'


    ​-s 20 samples 1 in every 20 packets, which keeps CPU use low on busy hosts. 20 is the recommended minimum. A higher number reduces the load further, but Faddom will take longer to detect new connections. Without -s, softflowd processes every packet.
    ​
    ​vmbr0 is the bridge the VMs use; change it if yours differs. -v 10 sends IPFIX, and -t maxlife=60 makes sure long-running connections are reported at least once a minute.

  3. Start softflowd and set it to start at boot:
    ​systemctl enable --now softflowd@default

    If the VMs use more than one bridge, create one config file per bridge (for example /etc/softflowd/vmbr1.conf, with interface='vmbr1') and enable it with systemctl enable --now softflowd@vmbr1.

    Note: If you change /etc/softflowd/default.conf later (for example the Faddom IP or the sampling rate), restart softflowd to apply it:

    systemctl restart softflowd@default

Step 2: Create a read-only API token

Faddom uses a dedicated read-only user and token. Do this once per Proxmox cluster or standalone host, under Datacenter in the Proxmox web UI.

  1. Create the user: Datacenter > Permissions > Users > Add. Set User name to faddom, Realm to Proxmox VE authentication server, and any password.

  2. Grant read-only access: Datacenter > Permissions > Add > User Permission. Set Path to /, User to faddom@pve, Role to PVEAuditor, and leave Propagate ticked.

  3. Create the token: Datacenter > Permissions > API Tokens > Add. Set User to faddom@pve, Token ID to faddom, and untick Privilege Separation.

  4. Copy the Secret from the window that appears. Proxmox shows it only once; if you lose it, delete the token and create a new one.

Step 3: Add Proxmox in Faddom

  1. On the Faddom server, make sure that inbound UDP on port 4739 is open

  2. Sign in to Faddom and navigate to Settings > Data Sources
    ​

  3. Add a new Proxmox data source and fill in Step 1 - Proxmox Discovery:
    ​

Field

Value

Host

The Proxmox host's IP

Port

8006

Token ID

faddom@pve!faddom

Token secret

The secret from Step 2

Validate server certificate

Unticked, unless Proxmox has a trusted certificate

Need proxy

Unticked, unless Faddom reaches Proxmox through a proxy

Troubleshooting

To confirm packets are reaching the Faddom Server, navigate to Settings > Configuration > Sensor Status, and click on "Show Debug Information" for the localProxy. This will show you whether or not packets are being collected by Faddom.

Confirm that flow records are leaving the Proxmox host. You should see packets going to FADDOM_IP.4739 within about a minute:

tcpdump -ni vmbr0 udp port 4739 -c 5

Symptom

Likely cause

Fix

tcpdump shows no packets to port 4739

softflowd isn't running, or the config is wrong

Run systemctl status softflowd@default and check /etc/softflowd/default.conf

Packets leave the host, but Faddom shows nothing

The Faddom server's firewall is blocking UDP 4739

On the Faddom server, in an admin PowerShell: New-NetFirewallRule -DisplayName "IPFIX 4739" -Direction Inbound -Protocol UDP -LocalPort 4739 -Action Allow

Proxmox discovery fails in Faddom

Wrong token, or Faddom can't reach port 8006

Check that the Token ID is in the form faddom@pve!faddom and that Privilege Separation is unticked. Confirm Faddom can open https://PROXMOX_IP:8006.

Did this answer your question?