Skip to content

Monitoring Proxmox VE over the API

Vesana monitors a Proxmox VE node through its REST API on port 8006. No agent runs on the Proxmox host and no shell access is needed — a token with a read-only role is enough.

Since profile version v11 an editable Python script reads the node (check type "Script (API)"). You will find it in your Scripts library as "Proxmox VE — API": open it, read it, extend it. The collector runs it and the script talks to the API itself.

Monitored: node CPU / memory / root filesystem / swap / load / uptime, storage fill levels and unreachable storages, cluster quorum and node outages, VMs and containers, backups (age of the oldest backup, failures and warnings inside a real time window, guests without a backup job), services, ZFS pools, SMART and pending package updates.

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) and give the token an ID (e.g. vesana). The full identifier is user@realm!tokenid, e.g. monitoring@pve!vesana.
  3. Copy the secret shown only once.

The token needs read permissions: Datacenter → Permissions → Add → API Token Permission, path /, your token, role PVEAuditor.

Privilege separation

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

A plain account with a password (user@realm + password) works too — the script then logs in for a ticket. A token is the cleaner way because it can be revoked on its own.

2. Get the Proxmox profile

The profile "Proxmox VE (API)" lives in the Vesana library. Open Profiles → Available tab, search for "Proxmox" and install it.

3. Create the host and store the API access

Create a host:

  1. Target: the IP address or DNS name of the Proxmox node.
  2. Profile: "Proxmox VE (API)".
  3. Open API access (in the host wizard; for an existing host in the host settings, Connection tab):
  4. User: the token ID, user@realm!tokenid
  5. Password / secret: the token secret

The credentials are stored encrypted and never appear in a profile or export.

The device name is free now

Up to profile version v10 the node checks pointed at the Proxmox node through the Vesana device name — if the device was named differently from the node (say "Dell Optiplex" instead of pve1), Proxmox answered HTTP 500 and CPU, memory and root filesystem were permanently CRITICAL. From v11 the script asks Proxmox which node is answering. Name the device whatever you like; only set a node name on the check if you want to watch a different node of the cluster from this host.

What the checks measure

Node

Check Meaning
CPU usage / Memory usage Node utilisation. On ZFS hosts the ARC cache counts as used memory — which is why the defaults are higher than on a normal server.
Root filesystem usage Fill level of /. When that runs full Proxmox can no longer write its configuration.
Swap usage · Load per core Memory overcommit and load per thread. "Load per core" is off by default (a hypervisor is bursty by nature).
Uptime Pure statistics (info mode, unit days). To be alerted on an unplanned reboot turn info mode off, pick the unit hours and set a lower threshold (warn 2 = "started less than 2 hours ago").

Storage

  • Storage usage (fullest) — fill level of the fullest storage; every storage is listed in the check details with type, size and free space.
  • Storages not reachable — storages enabled in Proxmox that do not answer. A lost NFS share shows up here before the next backup fails on it.

Adjustable per check: exclude storages, give one its own limits (NAME:warn:crit), hide small ISO/template shares below a minimum size, and — in a cluster — skip shared storages so a shared NFS alerts once instead of once per node.

Backups

Check Meaning
Oldest backup age Age of the newest backup of the guest that was backed up longest ago — the question "did last night's backup run?" as a number. Reads the backup storages of this node, so a Proxmox Backup Server mounted here is covered. Defaults: WARNING after 26 h, CRITICAL after 50 h.
Backup failures vzdump runs that failed inside a real time window (26 h by default).
Backup warnings Runs that finished WITH warnings — in Info mode, visible without alerting.
Guests without backup job Guests no vzdump job covers.
Backup jobs configured Number of jobs with schedule and next run — display only.

Why 'with warnings' is not a failure

Proxmox finishes a backup task with OK, with WARNINGS: n or with an error text. Proxmox itself counts only the third as an error — a run with warnings is orange "Warning: n" in the task list, not red. Vesana draws the same line. Typical causes: the guest agent did not answer, a volume was skipped, a hook script complained — the backup itself ran.

Backups on a Proxmox Backup Server

"Oldest backup age" sees a PBS target that is attached to the node as a storage. Whether the backups there are still valid (verify), whether garbage collection runs and how long the datastore will last is answered by the separate Proxmox Backup Server (API) profile.

Cluster, hardware, maintenance

Quorum and node outages; Proxmox services; number of running guests (info mode); pending package updates (info mode). Not created by default — add them on the device when needed: "VMs not running", "Containers not running", ZFS pool health, SMART and "SSD life left" (not every installation has ZFS or real disks) and the subscription status. "SSD life left" is the remaining life of the most worn SSD as Proxmox reports it (wearout, 100% = new): yellow from 20%, red from 10%. The details list every disk with serial number and remaining life.

Adjusting

Every check has adjustable values below the script selection — exclusion lists, time windows, units. Exclusion lists accept a prefix: test-* matches everything starting like that. If an exclusion removes all objects, the check reports UNKNOWN instead of a worthless "0 = fine".

Limits do not belong to the adjustable values but into the check's threshold fields — there they take effect immediately and can be overridden per device.

If a metric is missing, open the script in the library and extend it: a new metric then appears in the selection of every check of this profile.

Migrating from profile version v10

Version v11 replaces the old http_json checks with script checks under new names (Proxmox — …). After the profile update:

  1. The new checks are created (Update on the profile row, with "Also add the new checks to connected hosts").
  2. The update dialog offers a super admin to move the old checks to the trash — select that there. Especially CPU usage (node), RAM usage (node), Root FS usage (node) and Uptime (node): those are the ones that depended on the node name.

History and thresholds of the old checks stay until you remove them.

Troubleshooting

  • HTTP 500 — hostname lookup '…' failed (old checks): the node name in the URL is wrong. Move to profile v11 or put the node name into the URL.
  • HTTP 595 / 596 / 599: these are Proxmox' own status codes; the error comes from the cluster, not from Vesana. 595: the Proxmox proxy cannot reach the node it was asked about (node down, wrong name/DNS). 596: it can't get through to the node (TLS/certificate between the nodes). 599: internal proxy error (often overload).
  • HTTP 401/403: check the token ID (including !tokenid), the secret and the role — PVEAuditor on path /, and with "Privilege Separation" enabled on the token itself.
  • "Node not reachable": the Vesana server or collector must reach the node on port 8006.
  • The check stays UNKNOWN with "Server-side plugins are not enabled for this tenant": script checks on the Active Collector need the approval "Own plugins on the server" for the tenant under Admin → Agents & Collectors → Active checker. Checks saved by a super admin run regardless.
  • Self-signed certificate: Proxmox ships one; the profile's checks accept it deliberately.