Set up Proxmox VE discovery

A Proxmox VE cluster keeps a list of every node and every guest it runs. Scanopy reads that list through the Proxmox VE API and records each node and guest as a host, with each guest linked to the node that runs it.

Any node's API answers for the whole cluster, so the credential goes on one Proxmox VE node, or on the daemon host when the daemon runs on a node. Assigning it to more than one node does no harm. Each node reports the same cluster, and the results land on the same hosts.

What gets discovered

On each scan, the daemon reads the cluster's node and guest lists:

Guests appear grouped under their node in the Workloads perspective.

Templates are skipped. Every other guest is recorded, with whatever addresses the API reports for it:

The guest host records only addresses on the guest's own NICs. Container bridges such as docker0, tunnels such as WireGuard, and loopback are left out. An interface with its own MAC and a LAN address becomes a network identity host instead. A guest recorded by its MAC alone gains its address when a network scan finds it, and stays one host.

Prerequisites

• Proxmox VE 8.x or 9.x
• A daemon running version 0.17.21 or later
• TCP port 8006 open from the daemon host to the node the credential is assigned to
• A dedicated Proxmox VE user and API token with read access to the cluster (see below)
• The daemon accepts the node's certificate (see below)

Create the user and token

Run these as root on any node:

pveum user add scanopy@pve --comment "Scanopy discovery"
pveum role add ScanopyGuestAgent --privs "VM.GuestAgent.Audit"
pveum acl modify / --users scanopy@pve --roles PVEAuditor
pveum acl modify / --users scanopy@pve --roles ScanopyGuestAgent
pveum user token add scanopy@pve discovery --privsep 0

On Proxmox VE 8.x, create the role with --privs "VM.Monitor" instead. VM.GuestAgent.Audit exists only on 9.x.

The last command prints the token secret once. Copy it before closing the terminal.

To do the same in the web interface, go to Datacenter → Permissions. Add the user under Users, the role under Roles, the token under API Tokens, and both role assignments on / under Permissions.

With privilege separation on (--privsep 1, or Privilege Separation checked in the web interface), the token holds its own permissions. Grant both ACLs to the token instead of the user:

pveum acl modify / --tokens 'scanopy@pve!discovery' --roles PVEAuditor
pveum acl modify / --tokens 'scanopy@pve!discovery' --roles ScanopyGuestAgent

Certificates

Each node serves a self-signed certificate issued by the cluster's own CA. The daemon accepts it in either of two ways:

Choosing a credential type

Proxmox VE has one credential type.

Proxmox VE API Token

The daemon connects to the node's API over HTTPS and sends the token with each request. Tokens hold no session, and they expire only if you set an expiry when creating them.

Token ID is the full ID in the form user@realm!tokenname, such as scanopy@pve!discovery. Token Secret is the UUID Proxmox VE shows once at creation. It takes the value with Enter value, or a path to a file holding it with File on daemon host.

Verifying it works

1. Run a discovery from Discover > Scan > Scheduled
2. Open the scan session. The credential appears in the session's credential summary
3. Check Assets > Hosts for a host per node, each with a Proxmox VE service
4. Check Assets > Hosts for the running VMs and containers, named as in Proxmox VE
5. Open the Workloads perspective and confirm the guests appear under their node

Troubleshooting

The token is rejected

The node returns 401 when the token ID or secret is wrong, or the token has expired. Check the Token ID includes both the user and the token name (scanopy@pve!discovery, not scanopy@pve). Check the token's expiry under Datacenter → Permissions → API Tokens. A lost secret cannot be shown again. Remove the token and create a new one.

Guests appear without a link to their node

The scan reports a partial result for Proxmox VE nodes. The token lacks Sys.Audit, so the daemon cannot read node addresses from /cluster/status, and guests on a multi-node cluster are recorded without their node. Grant PVEAuditor on / to the user, or to the token when privilege separation is on.

VMs have no addresses

A running VM's address comes from the QEMU guest agent, or from a cloud-init static address. Without either, the VM is recorded by its MAC until a network scan finds its address. For the agent, check each of these:

1. qemu-guest-agent is installed and running inside the VM
2. The VM's Options → QEMU Guest Agent is on, and the VM was restarted after turning it on
3. The token has VM.GuestAgent.Audit on Proxmox VE 9.x, or VM.Monitor on 8.x

Certificate errors

The node's self-signed certificate fails verification. Turn on Accept Invalid Scan Certificates for the daemon, or add /etc/pve/pve-root-ca.pem to its SCANOPY_TRUSTED_CA_BUNDLE. See Certificates.

Other nodes are missing, or their guests are not linked

The daemon records the node it queries at the address it scanned. It records every other node at the cluster address /cluster/status reports. When that address sits on a dedicated corosync network outside any subnet Scanopy knows, the node is not recorded, its guests lose their link to it, and the scan reports a partial result for Proxmox VE nodes. Assign the credential to each node, so each one is recorded at its scanned address, or make the corosync network reachable from the daemon.

For diagnosing credential loading and file read errors from daemon logs, see Credential troubleshooting.