david/homelab-dashboard
1
0
Fork 0
Code Issues Pull requests Projects Releases 76 Packages 1 Wiki Activity Actions
Page: Proxmox
Pages
Container Registry Documentation Screenshots Grimmory Home Kavita Lab View Module Setup Navidrome Notifications Plex Proxmox Roadmap Security Hardening Seerr Requests Storage Health UniFi Network Uptime Kuma White Labeling
5 Proxmox
david edited this page 2026-06-09 13:47:34 -07:00
Table of Contents

Proxmox

Dashboard Status

This module is live. The dashboard reads cluster resources, per-node resource usage, guest counts, and backup status.

Primary API surfaces:

/api2/json/cluster/resources
/api2/json/cluster/tasks?typefilter=vzdump&limit=500
/api2/json/nodes/{node}/tasks?typefilter=vzdump&limit=500
/api2/json/nodes/{node}/storage
/api2/json/nodes/{node}/storage/{storage}/content?content=backup
/api2/json/nodes/{node}/storage/{storage}/content?content=backup&vmid={vmid}
/api2/json/nodes/{node}/tasks/{upid}/log

Admin Fields

  • Proxmox URL
  • API Token ID
  • API Token Secret
  • Allow self-signed TLS (true/false)
  • CPU warning percent
  • Memory warning percent
  • Storage warning percent

Recommended Values

Proxmox URL: https://proxmox.example.com:8006
API Token ID: user@realm!tokenid
API Token Secret: generated-secret
Allow self-signed TLS: true
CPU warning percent: 90
Memory warning percent: 90
Storage warning percent: 90

Use the Proxmox base URL that the dashboard container can reach. For internal Proxmox nodes this is often an internal IP or DNS name on port 8006.

The dashboard builds this authorization header:

Authorization: PVEAPIToken=user@realm!tokenid=generated-secret

Create A Read-Only Token

  1. Open the Proxmox web UI as a user that can manage users/tokens.
  2. Go to Datacenter -> Permissions -> API Tokens.
  3. Click Add.
  4. Select the user that should own the token.
  5. Enter a token ID such as homelab-dashboard.
  6. Keep privilege separation enabled for a least-privilege token.
  7. Click Add and copy the generated secret immediately.
  8. Go to Datacenter -> Permissions.
  9. Add permissions for the token.

Recommended starting permission:

Path: /
Role: PVEAuditor
Propagate: enabled

The backing user must also be allowed to perform the same read operations. Proxmox token permissions are a subset of the permissions held by the user that owns the token.

Resource Warning Thresholds

The Proxmox card warns on cluster CPU, memory, and storage at 90% by default. Tune the admin fields above or set these environment fallbacks:

PROXMOX_CPU_WARNING_PERCENT=90
PROXMOX_MEMORY_WARNING_PERCENT=90
PROXMOX_STORAGE_WARNING_PERCENT=90

Set a threshold to 0 to disable that card warning.

CLI Alternative

Run this on a Proxmox node, adjusting user and token names:

pveum user add dashboard@pve
pveum user token add dashboard@pve homelab-dashboard --privsep 1
pveum aclmod / -token 'dashboard@pve!homelab-dashboard' -role PVEAuditor -propagate 1

Copy the token secret printed when the token is created.

What The Card Shows

  • Running guest count and total guest count.
  • Online node count and total node count.
  • Cluster CPU, memory, and storage summary.
  • One rectangular card per Proxmox node with CPU/RAM bars.
  • Guest backup status as a compact list showing each guest and how long it has been since the latest detected backup.

Backup Discovery

The dashboard uses multiple backup discovery paths because Proxmox can expose scheduled backups differently depending on storage type and task history:

  1. Recent cluster vzdump tasks.
  2. Recent per-node vzdump tasks.
  3. Backup-capable storage repositories from /nodes/{node}/storage.
  4. Global backup storage contents from /nodes/{node}/storage/{storage}/content?content=backup.
  5. Per-guest backup storage contents with vmid={vmid}.
  6. Recent completed vzdump task logs, so scheduled nightly jobs that appear as one job-level task can still map to guest IDs when the log contains VM/CT IDs.

The backup list uses the newest backup discovered for each guest. If the Proxmox UI shows backups but the dashboard does not, check token permissions for task logs and storage content reads.

Backup tasks are filtered inside the dashboard backend after task history is fetched. This avoids Proxmox task endpoints that reject query parameters such as typefilter or limit while keeping the card focused on vzdump activity.

Test From The Docker Host

Cluster resources:

curl -k \
  -H 'Authorization: PVEAPIToken=dashboard@pve!homelab-dashboard=TOKEN_SECRET' \
  'https://proxmox.example.com:8006/api2/json/cluster/resources'

Storage content:

curl -k \
  -H 'Authorization: PVEAPIToken=dashboard@pve!homelab-dashboard=TOKEN_SECRET' \
  'https://proxmox.example.com:8006/api2/json/nodes/NODE/storage/STORAGE/content?content=backup'

Per-guest backup content:

curl -k \
  -H 'Authorization: PVEAPIToken=dashboard@pve!homelab-dashboard=TOKEN_SECRET' \
  'https://proxmox.example.com:8006/api2/json/nodes/NODE/storage/STORAGE/content?content=backup&vmid=100'

If your Proxmox certificate is trusted, remove -k. In dashboard settings, set Allow self-signed TLS to true when connecting directly to a default self-signed Proxmox endpoint.

Common Problems

  • 401: token ID or secret is wrong. Check the user@realm!tokenid format.
  • 403 or Permission check failed: the token or backing user lacks PVEAuditor or equivalent read permissions.
  • TLS errors: the Proxmox certificate is self-signed and Allow self-signed TLS is not enabled.
  • Nodes missing: verify /cluster/resources returns all nodes to the token.
  • Backups missing: verify the token can read node storage lists, storage content, task history, and task logs.
  • Empty/partial data: verify permissions at / with propagation enabled.

Sources