Connect Proxmox VE

1. Make the API reachable from viztopo.com

viztopo.com calls the Proxmox API from its own server, so it needs an https:// address that answers from the internet: a public IP or name, on port 8006 or a port you forward. In your firewall, let only VizTopo's server address through to that port. VizTopo shows the address, and the name that resolves to it, when you add the connection. Private and local addresses are refused.

2. Create the user, the token and the grants

Run these on any node as root. They create a user with a read-only, privilege-separated token. Skip the first line if the user already exists.

pveum user add viztopo@pve --comment "VizTopo read-only"
pveum user token add viztopo@pve readonly --privsep 1 --comment "VizTopo inventory"
pveum acl modify / --users viztopo@pve --roles PVEAuditor
pveum acl modify / --tokens 'viztopo@pve!readonly' --roles PVEAuditor

Proxmox shows the token's secret once: copy it for step 5.

Don't skip the two acl modify lines. A privilege-separated token only gets what both it and its user are granted, so the role goes to both. Without it, Proxmox doesn't refuse VizTopo: it hides every VM, container, storage and bridge, and only the node shows up.

To check: pveum user token permissions viztopo@pve readonly should list PVEAuditor's privileges on /.

3. VM IP addresses (Proxmox VE 8 only)

VizTopo reads VM IP addresses from the QEMU guest agent. On Proxmox VE 9, PVEAuditor already allows it. On Proxmox VE 8 it takes one more privilege:

pveum role add VizTopoGuestInfo --privs "VM.Monitor"
pveum acl modify / --users viztopo@pve --roles VizTopoGuestInfo
pveum acl modify / --tokens 'viztopo@pve!readonly' --roles VizTopoGuestInfo

4. Choose how VizTopo verifies the certificate

VizTopo always verifies the node's certificate before it sends the token. Pick one:

• Pin its fingerprint (Proxmox's own self-signed certificate). VizTopo shows the fingerprint it sees; compare it with the node's:

openssl x509 -noout -fingerprint -sha256 -in /etc/pve/local/pveproxy-ssl.pem 2>/dev/null \
  || openssl x509 -noout -fingerprint -sha256 -in /etc/pve/local/pve-ssl.pem

• Paste the cluster's CA, which signs every node's certificate:

cat /etc/pve/pve-root-ca.pem

• A publicly trusted certificate (an ACME one from Let's Encrypt, for example) needs nothing more.

5. Add the connection

In VizTopo: Connections → Add connection → Proxmox VE → Guide me. Enter the address, pick how to verify the certificate, then the token ID viztopo@pve!readonly and its secret. Test connection signs in with the token and checks its privileges; nothing is saved until you choose Save connection.

6. Optional: allow changes

Each kind of change has its own small role, granted next to PVEAuditor to the same user and token. Add only the ones you want:

For example, power on Proxmox VE 9:

pveum role add VizTopoPower --privs "VM.Audit VM.PowerMgmt VM.GuestAgent.Audit"   # already there? pveum role modify VizTopoPower --privs "VM.Audit VM.PowerMgmt VM.GuestAgent.Audit"
pveum acl modify / --users viztopo@pve --roles VizTopoPower
pveum acl modify / --tokens 'viztopo@pve!readonly' --roles VizTopoPower

And consoles:

pveum role add VizTopoConsole --privs "VM.Audit VM.Console"   # already there? pveum role modify VizTopoConsole --privs "VM.Audit VM.Console"
pveum acl modify / --users viztopo@pve --roles VizTopoConsole
pveum acl modify / --tokens 'viztopo@pve!readonly' --roles VizTopoConsole

Then turn on write mode for the connection on the Connections page, by typing its name. VizTopo's Permissions page shows what the token may do, checked live, with the exact command for anything missing.