Skip to content

Monitoring Proxmox VE over the API

Vesana monitors a Proxmox VE node through its REST API on port 8006 using an API token. No agent runs on the Proxmox host — the checks run in active mode (the Vesana server queries the API itself; without an Active Collector the Python fallback handles the http_json checks).

Monitored, among others: API reachability, cluster quorum, node CPU/RAM/disk, number of running VMs and LXC containers, and storages.

1. Create an API token in Proxmox

In the Proxmox web UI:

  1. Datacenter → Permissions → API Tokens → Add.
  2. Pick a user (e.g. monitoring@pve or root@pam) and give the token an ID (e.g. vesana). The full token identifier then has the form user@realm!tokenid, e.g. monitoring@pve!vesana.
  3. Copy the secret shown once and store it safely — it is not displayed again afterwards.

The token needs read access. Assign it a role such as PVEAuditor at path /:

  • Datacenter → Permissions → Add → API Token Permission, path /, your token, role PVEAuditor.

Privilege separation

If "Privilege Separation" is enabled on the token (the default), the token needs its own permission entry as above. If it is disabled, the token inherits its user's permissions.

2. Get the Proxmox profile in Vesana

The ready-made "Proxmox VE (API)" profile lives in the Community Hub. Open Profiles, search the hub for "Proxmox" and import the profile. It already bundles the API checks (API reachable, quorum, node CPU/RAM/disk, running VMs/LXC, storages).

3. Add the host and store the API access

Create a host:

  1. Set the Proxmox node's IP address or DNS name as the target. This fills in the {host} in the check URLs (e.g. https://{host}:8006/api2/json/version).
  2. Choose the "Proxmox VE (API)" profile.
  3. In the credentials section, open API access and fill the two fields:
  4. User: the token ID, user@realm!tokenid (e.g. monitoring@pve!vesana)
  5. Password / secret: the token secret from step 1

Vesana assembles the Proxmox auth header (PVEAPIToken=…) for you and sends it with every API check. The access is stored encrypted. The same "API access" card takes a plain username and password for other devices (e.g. ESXi) instead of a token — it's the same field pair, just with different contents.

Existing customers

If a Proxmox token was already stored on a host, it was carried over automatically into the User/Password fields of the "API access" card during the update — nothing further to do.

Notes & troubleshooting

  • Self-signed certificate: Proxmox uses a self-signed certificate by default. The profile's checks accept it deliberately.
  • "API reachable" is CRITICAL with 401/403 → the token or role is wrong. Check the Token-ID (including !tokenid), the secret, and the assigned role (PVEAuditor at path /).
  • 5xx on "API reachable" → the Proxmox API itself is unhealthy, not the Vesana configuration.
  • Multi-node cluster: the node-health checks read the first node by default. Point the host at the specific node you want, or add one host per node (using the same token).
  • Reachability: the Vesana server (or the Active Collector) must reach the node on port 8006 — check the firewall if needed.

Backup monitoring

The profile ships four backup checks (from the bundle version with backup support):

  • Backup failures (recent tasks) — counts failed vzdump backups in the recent task history (cluster-wide). A running backup never counts as a failure. The counter only drops once the failed task rotates out of the Proxmox task list — until then the check stays WARNING.
  • Backup warnings (recent tasks) — runs that finished WITH warnings. Ships in Info mode: visible, but never alerting.
  • Guests without backup job — guests not covered by any vzdump job. If you back up externally (e.g. Proxmox Backup Server in pull mode or storage snapshots), adjust the threshold or disable the check.
  • Backup jobs configured — display only: number of configured vzdump jobs (including disabled ones). 0 means no backup is set up at all.

Why 'finished with warnings' is not a failure

Proxmox ends a backup task with OK, with WARNINGS: n, or with an error text. Only the third counts as an error to Proxmox — a run with warnings shows up orange as "Warning: n" in the task list, not red. Vesana draws the same line: warnings go into their own Info-mode counter, not into the failures. Typical causes are a guest agent that doesn't answer, a skipped volume, or a hook script reporting something — the backup itself did run.

All four are regular profile checks — thresholds, intervals and the enable switch can be adjusted per profile or per host. A time-based check ("last backup older than X") cannot be expressed reliably via the REST API and is deliberately absent.