Skip to main content
Backup

Proxmox Backup Server

Use the Proxmox Backup Server check to monitor datastore usage, backup age per backup group, backup tasks and sync jobs through the PBS API.

The Proxmox Backup Server check monitors a Proxmox Backup Server (PBS) through its HTTPS API: datastore usage, the latest completed backup of every backup group, backup tasks and configured sync jobs. It signs in with an API token and only reads; it changes nothing on the PBS. The check runs every 10 minutes on an octoja agent on Windows, Linux or macOS (x64 and Arm64) that can reach the PBS over the network.

Prerequisites

  • The running agent reaches the PBS API over HTTPS, typically on port 8007 (for example https://pbs.example.com:8007).
  • The PBS TLS certificate is trusted on the agent's device. A self-signed certificate makes the request fail unless you enable Ignore TLS certificate errors (insecure).
  • A PBS user with an API token. The user and the token each need their own permissions, because PBS only grants a token the intersection of the user's and the token's permissions:
PathRole (propagated)Purpose
/AuditProvides Sys.Audit on /system/tasks (backup tasks) and Datastore.Audit for every datastore and namespace
/remoteRemoteAuditProvides Remote.Audit for sync jobs. Only needed when Check configured sync jobs is enabled. The Audit role does not include Remote.Audit

Steps

Step 1 – Create an API token on the PBS

You can create the user, token and permissions in the PBS web interface under Configuration → Access Control, or in the PBS shell with proxmox-backup-manager. Example for a user monitor@pbs with the token octoja:

proxmox-backup-manager user create monitor@pbs
proxmox-backup-manager user generate-token monitor@pbs octoja
proxmox-backup-manager acl update / Audit --auth-id monitor@pbs
proxmox-backup-manager acl update / Audit --auth-id 'monitor@pbs!octoja'
proxmox-backup-manager acl update /remote RemoteAudit --auth-id monitor@pbs
proxmox-backup-manager acl update /remote RemoteAudit --auth-id 'monitor@pbs!octoja'

generate-token prints the token ID (monitor@pbs!octoja) and the secret. Copy the secret right away; PBS does not show it again. New permissions are created with propagation. You only need the two /remote lines for sync job monitoring.

Step 2 – Add the check in octoja

  1. Go to Devices and open the device whose agent reaches the PBS.
  2. Click the Checks tab → Add Check → Proxmox Backup Server.
  3. Enter the address including the port under PBS HTTPS URL, for example https://pbs.example.com:8007.
  4. Enter the API token ID (monitor@pbs!octoja) and the API token secret.
  5. (Optional) Limit monitoring to specific datastores under Datastores (exact names) and adjust the thresholds.
  6. Click Add Check.

After the first run, the result appears in the device's Checks tab.

Settings

FieldTypeRequiredDefaultDescription
PBS HTTPS URLstringYes—Address of the PBS, for example https://pbs.example.com:8007. https only, without path, credentials, query or fragment. The check does not follow redirects
API token IDstringYes—Full token ID in the format user@realm!tokenname. Without ! the configuration is invalid
API token secretpasswordYes—Secret of the API token
Ignore TLS certificate errors (insecure)booleanNoOffTurns off certificate verification. Enable this only in trusted test environments
Whole-check timeout (seconds)integerNo60Total time for all API requests of one run. Allowed range 1 to 300
Datastores (exact names)list of stringsNoemptyLeave empty to monitor all accessible datastores. Names must match exactly, including case
Storage used: warning (%)numberNo80Warning once a datastore's usage reaches this value. Allowed range 0 to 100
Storage used: critical (%)numberNo90Critical once a datastore's usage reaches this value. Allowed range 0 to 100
Completed backup age: warning (hours)integerNo26Warning when the latest completed backup of a backup group is at least this old. Minimum 1
Completed backup age: critical (hours)integerNo48Critical when the latest completed backup of a backup group is at least this old. Minimum 1
Backup-task lookback (hours)integerNo48Shows the latest completed backup task per worker within this period, plus running backup tasks. Allowed range 1 to 720
Check configured sync jobsbooleanNoOnEvaluates the sync jobs of the monitored datastores, both pull and push. Requires Remote.Audit on /remote

If the warning and critical thresholds are reversed, the check treats the lower value as the warning and the higher value as critical. Values outside the allowed ranges result in Invalid configuration.

Results

The check evaluates every datastore, backup group, backup task and sync job on its own. The worst individual result becomes the overall status.

ConditionMessageSeverity
A setting is invalid, such as an http URL, a URL with a path or a token ID without !Invalid configuration.Failure
PBS rejects the token (HTTP 401/403), Sys.Audit on /system/tasks is missing, or, with sync monitoring enabled, propagated Remote.Audit on /remote is missingAccess denied. Check Audit on / and RemoteAudit on /remote (sync) for both user and token.Failure
A datastore or one of its namespaces lacks Datastore.Audit (propagated on the datastore)Access denied. … (on the affected datastore)Failure
The PBS cannot be reached, its certificate is not accepted, or the API answers with an error or a redirectPBS API request failed.Failure
The API returns data the check cannot evaluate, for example a snapshot more than 5 minutes in the futureInvalid PBS API response.Failure
The run exceeds Whole-check timeout (seconds). Data read up to that point is still shownWhole-check timeout exceeded.Failure
A datastore listed under Datastores (exact names) does not exist or is not visible to the tokenRequested datastore missing or not visible.Failure
No datastore is visible and none is listedNo accessible datastores found.Warning
A datastore's usage reaches the critical thresholdStorage usage reached the critical threshold.Critical
A datastore's usage reaches the warning thresholdStorage usage reached the warning threshold.Warning
A datastore contains no visible backup groupNo visible backup groups found.Warning
A backup group has only incomplete snapshotsNo completed backup found.Critical
The latest completed backup of a group reaches the critical age thresholdLatest completed backup exceeds the age threshold.Critical
The latest completed backup of a group reaches the warning age thresholdLatest completed backup exceeds the age threshold.Warning
A backup task or sync job finished with OK or is runningOK or Running (informational)OK
A backup task or sync job finished with warnings (WARNINGS: n) or without a readable statusWarnings: n or UnknownWarning
A sync job has never runNever runWarning
A backup task or sync job finished with an errorError message from PBSCritical

If only one datastore fails, the check still evaluates the remaining datastores.

How the check evaluates backups, tasks and sync jobs

  • Backup groups: The check searches the root namespace and all namespaces of every datastore. A backup group is, for example, vm/100 or ct/101. A snapshot counts as completed once PBS has finished writing it; the age is measured from the timestamp of the newest completed snapshot.
  • Backup tasks: For each worker, the check shows the latest completed backup task within the lookback period plus all running backup tasks. A worker without a task in the lookback period does not appear; stale backups are caught by the backup group age check.
  • Sync jobs: The check reads the pull and push sync jobs of every monitored datastore and evaluates the state of their last run.

Detail view

The check's detail view has these sections, each entry with its own severity:

SectionContent
DatastoresUsed percentage, total and free space
Latest completed backup per groupDatastore, namespace (Root for the root namespace) and time of the latest completed backup
Backup tasks: latest completed per worker in lookback + runningDatastore, status, start and end time
Configured sync jobsDirection (pull or push), source datastore, remote / peer datastore, remote (Local for local sync jobs) and end time of the last run

Notes

  • PBS only returns what the token may see. An empty sync job list can mean that no sync jobs are visible, not that none exist. In that case, check that the user and the token have the roles from the prerequisites.
  • The check only reads the PBS backup data. To monitor your Proxmox VE hosts, use the Proxmox Cluster & Quorum and Proxmox Services & HA checks.
  • The check does not currently count as a backup check in the backup widgets of reports.

FAQ

For a PBS API token, the effective permissions are always the intersection of the user's and the token's permissions. Assign the roles to both the user (monitor@pbs) and the token (monitor@pbs!octoja). When Check configured sync jobs is enabled, both also need RemoteAudit propagated on /remote; without it the whole check fails. If you do not want to monitor sync jobs, turn the option off.

Check that the agent reaches the PBS at the configured address and port and that the PBS certificate is trusted on the agent's device. After installation, PBS uses a self-signed certificate. Install a trusted certificate on the PBS; only enable Ignore TLS certificate errors (insecure) in trusted test environments.

Old groups, for example from deleted VMs, stay visible on the PBS until their snapshots are removed. Remove groups you no longer need on the PBS. If a group is backed up less often than daily, raise both age thresholds above its backup interval.