Zum Inhalt springen
Produkte

// Betrieb

Connecting a Proxmox homelab

A single, end-to-end walkthrough for putting a Proxmox VE host under Fleeger: create the location, add the proxmox_node resource, mint a read-only Proxmox monitoring token, hand it to Fleeger as a credential, deal with the self-signed API certificate, and onboard the spoke-agent that ties it together.

The individual steps each have their own reference page (creating a location, adding a resource, managing credentials, onboarding a location); this page threads them into one sequence and fills in the Proxmox-specific details those pages leave generic.

What you'll need: root (or Sys.Audit) access to a Proxmox node for a few pveum commands, the hub's URL, and somewhere to run the agent (the PVE host itself, a Pi, a VM — anywhere that can reach both the hub and the Proxmox API).

The shape of it

 spoke-agent  ──(1) bootstrap over HTTPS ──►  hub (mints per-location NATS creds)
      │        ──(2) metrics + inventory ──►  hub, over wss://<hub>/nats
      │
      └────────(3) reads the Proxmox API ──►  https://<pve>:8006  (self-signed)

The agent reaches the hub over one URL (see onboarding). Separately, it reaches the target — your Proxmox API — using the address and credential you register below. Those are two different network paths; this page is mostly about the second one.

1. Create the location

Locations → New location: name it (e.g. homelab), pick Kind = homelab. See creating a location. The location's name is a stable id — later steps (agent creds, metric labels) bind to it.

2. Create a read-only Proxmox monitoring token

Fleeger only reads Proxmox for metrics and discovery (node/VM status and resource usage), so the monitoring token needs audit rights only — no power privileges. (Power actions like Start/Stop are a separate, opt-in step with its own token privilege; see controlling a Proxmox VM.)

Run these on any Proxmox node, as root@pam. They create a dedicated user, an API token for it, and grant that token the built-in PVEAuditor role (Proxmox's read-only role) across the whole datacenter:

# 1. a dedicated monitoring user in the PVE realm (no password — token-only)
pveum user add fleeger@pve

# 2. an API token for it, with privilege separation ON (--privsep 1).
#    This prints the token's secret VALUE exactly once — copy it now.
pveum user token add fleeger@pve monitoring --privsep 1

# 3. grant the TOKEN read-only audit rights on the whole tree, propagating down
pveum acl modify / --tokens 'fleeger@pve!monitoring' --roles PVEAuditor --propagate 1

Step 2 prints something like:

┌──────────────┬──────────────────────────────────────┐
│ key          │ value                                │
├──────────────┼──────────────────────────────────────┤
│ full-tokenid │ fleeger@pve!monitoring               │
│ value        │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  │
└──────────────┴──────────────────────────────────────┘

Keep both: full-tokenid and value are the two halves of the credential you enter in step 4.

--privsep 1 matters. With privilege separation on, the token starts with no rights and only gets what you grant to the token in step 3 (not what its user has). That's why the ACL in step 3 targets --tokens 'fleeger@pve!monitoring' and not the user. It's the least-privilege default.

A quick homelab shortcut is to use an existing root@pam token instead of a dedicated user — the UI even placeholders root@pam!monitoring — but that token is only read-only if you scope it with PVEAuditor as above; a privsep-off root token inherits root's full rights.

PVEAuditor is the smallest built-in role that covers everything the collector calls (/nodes needs Sys.Audit, /cluster/resources needs VM.Audit; PVEAuditor bundles Datastore.Audit, Sys.Audit, VM.Audit, …). Using the built-in PVEAuditor is the version-proof choice: Proxmox keeps it in sync across major upgrades, so it stays correct on both PVE 8 and PVE 9 (see required permissions by Proxmox version). If you'd rather hand-roll a minimal custom role:

pveum role add FleegerMonitor -privs "VM.Audit Sys.Audit Datastore.Audit"
pveum acl modify / --tokens 'fleeger@pve!monitoring' --roles FleegerMonitor --propagate 1

The custom FleegerMonitor role above is deliberately spelled with only VM.Audit, Sys.Audit, and Datastore.Audit — three privileges that exist and mean the same thing on both PVE 8 and PVE 9 — so it survives an 8 → 9 upgrade unchanged. Do not add the old VM.Monitor privilege to it: PVE 9 removed that privilege, and pveum role add … -privs "… VM.Monitor" fails outright on a PVE 9 host. See the version table next for the details.

Required permissions by Proxmox version

Fleeger's collector only ever makes three read calls per poll, and their privilege requirements are what actually matter:

API call (per poll) What it feeds Privilege Granted at
GET /api2/json/nodes node status + CPU/RAM/uptime Sys.Audit / (propagate)
GET /api2/json/cluster/resources?type=vm per-VM/CT status + usage VM.Audit / (propagate)
GET /api2/json/cluster/status which cluster the VMs belong to (below) Sys.Audit / (propagate)

Both privileges — and the built-in PVEAuditor role that bundles them — exist on every supported Proxmox version, so the setup in this page works the same whether the host is PVE 8 or PVE 9:

Proxmox major Recommended role Equivalent hand-rolled privileges Notes
8.x PVEAuditor Sys.Audit, VM.Audit, Datastore.Audit VM.Monitor still exists but Fleeger's metrics path never needs it.
9.x PVEAuditor Sys.Audit, VM.Audit, Datastore.Audit VM.Monitor removed — basic monitor access folded into Sys.Audit.

The 8 → 9 change that silently breaks metrics. Proxmox VE 9.0 lists "Removal of the VM.Monitor privilege" among its breaking changes — basic KVM monitor access now rides on Sys.Audit instead. Two ways this bites a homelab that was working on PVE 8:

  • A custom role that listed VM.Monitor. After the upgrade Proxmox drops the now-nonexistent privilege from the role. If that role was the token's only grant of Sys.Audit-adjacent rights, its effective audit coverage can shrink and /nodes / /cluster/resources start returning 403, which the agent surfaces as "no metrics" rather than a loud error. Re-grant with the PVE-9 privilege set above (or just switch the token to built-in PVEAuditor).
  • Re-running an old provisioning script that does pveum role add … -privs "… VM.Monitor" on the freshly-upgraded host — it now errors because VM.Monitor no longer exists. Drop it from the -privs list.

If you used the built-in PVEAuditor (this page's recommendation), the upgrade needs no permission changes — Proxmox updated the built-in role for you.

3. Add the Proxmox resource

Open the location → New resource (see adding a resource):

  • Kind — proxmox_node.
  • Address — the Proxmox API base URL, https://<host>:8006. Use a name/IP the agent can reach (see networking). Examples: https://pve1.local:8006, https://192.168.1.10:8006, or https://localhost:8006 when the agent runs on the PVE host itself. Behind a reverse proxy at a path, include the path: https://proxy.lan/proxmox is asked at https://proxy.lan/proxmox/api2/json/….
  • Allow invalid/self-signed TLS certs — tick this. Proxmox serves :8006 with a self-signed certificate by default, so leaving it unchecked makes every collection fail with a TLS verification error. See self-signed TLS below for the trade-off and alternatives.
  • Tags (optional) — e.g. env:homelab.

4. Attach the monitoring token as a credential

Still in the resource form, under Credential, choose New credential and fill in the two Proxmox fields (this is the credential shape managing credentials refers to generically):

Field UI label Enter Example
api_user API token id the full token id, USER@REALM!TOKENID fleeger@pve!monitoring
api_secret API token secret the token's secret value (a UUID) 3b6f…-…-…

Those are the full-tokenid and value from step 2. Internally the agent sends them to Proxmox as the PVEAPIToken=<api_user>=<api_secret> header — so the id must include the !TOKENID part, not just the user. The secret is stored encrypted at rest and never shown again; to change it later, rotate the credential (one place, all attached resources — see managing credentials).

Save the resource.

5. Networking: what must reach what

Two independent paths, and only one is the "single hub URL" the onboarding docs describe:

  • Agent → hub — one URL (https://<hub> for bootstrap, then wss://<hub>/nats for everything else). Covered in onboarding.
  • Agent → Proxmox API — the agent must reach the Address from step 3 on TCP 8006. This is what varies by where you run the agent:
    • On the PVE host (as a container or the binary): https://localhost:8006 works, but the self-signed cert's name won't match localhost, so you must tick allow invalid certs (step 3). If you run it in Docker, remember localhost inside a container is the container — use --network host, or point the address at the host's LAN IP instead.
    • Elsewhere on the LAN (a Pi, another VM): use the PVE host's LAN name or IP, e.g. https://pve1.local:8006, and make sure any firewall lets 8006 through from the agent's host.

6. Onboard the agent

Back on Locations, use Onboard on the location's row to mint a one-time registration token and copy the install command (full onboarding guide). One Proxmox-specific caveat:

Your own registry? The Onboard panel's Docker command runs registry.netcode.dev/fleeger/spoke-agent at your hub's version. If you built and pushed the images to another registry (deploy/build-and-push.sh with your REGISTRY, see container images), swap the image accordingly, e.g.:

docker run -d --restart unless-stopped --name fleeger-agent \
  -v fleeger-agent-data:/var/lib/fleeger \
  -e FLEEGER_HUB_URL=https://your-hub.example.com \
  --env-file fleeger-agent.env \
  registry.example.com/fleeger/spoke-agent:X.Y.Z

fleeger-agent.env holds the token so it stays off the command line. The copied Docker command creates it in its first line and removes it after docker run; keep both lines around the edited docker run. The onboarding guide has a version that asks for the token at a prompt.

Run the command where the agent lives. On first boot it exchanges the token for per-location NATS credentials and starts collecting. Within ~90s the location flips to reachable (checking reachability).

Tuning the poll interval

The agent collects every 30s by default. To change it, set FLEEGER_POLL_INTERVAL_SECS (or poll_interval_secs in the TOML config; 0 is ignored). Docker only takes environment variables when it creates a container, so a running agent is removed and created again; its credentials stay on the volume:

docker rm -f fleeger-agent
docker run -d --restart unless-stopped --name fleeger-agent \
  -v fleeger-agent-data:/var/lib/fleeger \
  -e FLEEGER_HUB_URL=https://your-hub.example.com \
  -e FLEEGER_POLL_INTERVAL_SECS=15 \
  registry.netcode.dev/fleeger/spoke-agent:X.Y.Z

Keep it well under 90s: each resource reports once per cycle, and its alerts treat 90s of silence as unreachable. An agent that has already bootstrapped needs no token: its credentials are on the fleeger-agent-data volume. On a first start, add the token's --env-file fleeger-agent.env as above.

Verifying

  • Dashboard → Locations: the card shows reachable with a recent "last seen".

  • Open the location → Resources: the proxmox_node reports, and each VM/CT appears as an auto-discovered read-only sub-resource.

    A VMID is unique only within its cluster, so each guest is keyed on its cluster's name as well: two clusters in one location that both have VM 100 show two resources. A node in no cluster keys its guests on its own registration. So register a cluster by any one of its nodes (or several: they share the guests), and give two clusters in one location different names. A node that later joins a cluster, or a renamed cluster, keeps its guests' resources. If the agent cannot read /cluster/status, it still reports metrics but no guests, and the node's resource shows the collect error cannot tell which cluster it belongs to.

  • Nothing after a minute or two? Work through checking reachability. The two most common Proxmox-specific causes:

    • TLS error in the agent log → the allow invalid certs box wasn't ticked (step 3), or you're pointing at a name the cert doesn't cover.
    • 403 Forbidden → the token is missing audit rights, or privsep is on and the ACL was granted to the user instead of the token (step 2's --privsep 1 note). Note agent logs live on the remote host — they are not shipped to the hub.
    • Metrics stopped after a Proxmox major upgrade (e.g. 8 → 9) → the token's effective privileges changed with the Proxmox version. Re-check the token against the version table: PVE 9 removed VM.Monitor, so a custom role that listed it can lose coverage on upgrade. Fastest fix is to (re-)grant built-in PVEAuditor, which Proxmox keeps correct across versions.

Reference

Self-signed TLS

Proxmox's :8006 API uses a self-signed certificate out of the box. Fleeger gives you a per-resource Allow invalid/self-signed TLS certs toggle (the allow_invalid_certs flag on the proxmox_node resource). Ticking it tells the agent's HTTP client to skip certificate verification for that endpoint only.

For a LAN-local homelab that's the normal choice. If you'd rather keep verification on, install a certificate the agent trusts on the Proxmox host (e.g. via the built-in ACME/Let's Encrypt integration, using a DNS name the agent then uses as the Address) and leave the box unticked.

Standalone binary

The Standalone onboarding option runs spoke-agent --config …, but there is no separately-published binary artifact — only the container images are published (container images). Build it from the repo:

cargo build -p spoke-agent --release   # → target/release/spoke-agent

Then run it with a small TOML config, exactly as onboarding → Standalone shows. For most homelabs the Docker option is less fuss.

See also

// Zusammenarbeit

Bereit, Ihre digitale Infrastruktur zu bauen?

Ob individuelle Automatisierung für Ihr Unternehmen oder ein durchgeplantes Netzwerk für Ihr Zuhause — lassen Sie uns über das Projekt sprechen.