Skip to content

Monitoring Proxmox Backup Server over the API

A backup nobody looks at is a hope, not a backup. Vesana monitors a Proxmox Backup Server (PBS) through its REST API on port 8007 and answers exactly the questions a backup strategy fails on:

  • Is the datastore filling up, and how long will it last?
  • How old is the oldest backup — is the backup still running at all?
  • Did the last verification pass, or does the backup exist but cannot be restored?
  • Is garbage collection running? Without it PBS never frees the space of deleted snapshots, and the datastore fills up although retention is doing its job.
  • Did a task (backup, verify, sync, prune) fail?

No agent runs on the PBS and no shell access is needed. The checks run an editable Python script (Scripts library: "Proxmox Backup Server — API") that the collector executes.

This profile complements Proxmox VE (API): the hypervisor reports whether the backup run succeeded — the backup server whether the backup is still good.

1. Create an API token in PBS

In the PBS web UI:

  1. Configuration → Access Control → API Token → Add.
  2. Pick a user (e.g. monitoring@pbs), give the token an ID (e.g. vesana). The full identifier is user@realm!tokenid.
  3. Copy the secret shown only once.

Grant permissions: Configuration → Access Control → Permissions → Add → API Token Permission, path /, role Audit.

Privilege separation

As with Proxmox VE: if it is enabled on the token, the token needs its own permission entry; otherwise it inherits its user's permissions.

2. Get the profile and create the host

The profile "Proxmox Backup Server (API)" lives in the Vesana library (tier Beta, so far checked against the official API schema, not against a real PBS) — install it, then create a host:

  1. Target: IP or DNS name of the backup server.
  2. Profile: "Proxmox Backup Server (API)".
  3. API access (in the host wizard, or in the host settings, Connection tab):
  4. User: user@realm!tokenid
  5. Password / secret: the token secret

PBS separates with a colon

The PBS auth header reads PBSAPIToken=user@realm!id:secret — with a colon, while Proxmox VE uses =. Vesana builds the header for you; you only fill in ID and secret. Copying the header by hand from a PVE example gets you a 401 and sends you looking in the wrong place.

What the checks measure

Datastore

Check Meaning
Datastore usage (fullest) Fill level of the fullest datastore; all of them are in the details. A full backup target stops accepting backups — and then the newest backup quietly is the last one.
Datastore unusable Datastores PBS cannot use: an unreadable chunk store, or a removable datastore that is not mounted. Noticed before the next backup window notices it.
Days until full PBS' own projection of when a datastore will be full. The direction is downwards — fewer days are worse. UNKNOWN while PBS has no estimate yet (it needs about a month of history).

Backups

Check Meaning
Oldest backup age Age of the newest snapshot of the group that was written longest ago. A snapshot count cannot answer this: it stays high while nothing new arrives.
Verification failures Snapshots of the last 30 days whose verification failed — the backup exists but cannot be restored. The most important check on a backup server, and the one nobody notices without monitoring: the backup job itself reported success.
Snapshots never verified Never-verified snapshots — statistics. Off by default: without a verify schedule that would be every snapshot.
Snapshots Count per datastore, display only, with a graph.

Maintenance

Check Meaning
Garbage collection age Hours since the last completed GC run (defaults: WARNING after 200 h, CRITICAL after 400 h); WARNING when GC has never run.
Garbage collection result Result of the last run and the number of damaged chunks left behind. Damaged chunks are CRITICAL even when the run itself reports "OK" — the affected backups cannot be restored.
Failed tasks Failed tasks inside a real time window (26 h by default). The check can be narrowed to single types — a failed sync to the offsite target is a different conversation than a failed backup.

The machine

CPU, memory, system filesystem, uptime (info mode), services and pending package updates (info mode) — same logic as the Proxmox VE profile. Not created by default, add them on the device when needed: load per core, ZFS pools, SMART and subscription status.

Adjusting

Adjustable per check: exclude datastores and backup groups, give a datastore its own limits (NAME:warn:crit), change the verification and task windows, narrow down task types. Exclusions accept prefixes (ct/*, host/laptop).

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

Troubleshooting

  • HTTP 401: check the token ID (with !tokenid) and the secret. With "Privilege Separation" enabled the token needs its own permission entry.
  • HTTP 403: the token is missing the Audit role on path /.
  • A datastore is missing from the numbers: if the token cannot read it, it is named as "not readable" in the message — the rest is still judged. If all of them are unreadable the check reports UNKNOWN.
  • "PBS not reachable": the collector must reach port 8007.
  • 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.