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:
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
- Go to Devices and open the device whose agent reaches the PBS.
- Click the Checks tab → Add Check → Proxmox Backup Server.
- Enter the address including the port under PBS HTTPS URL, for example
https://pbs.example.com:8007. - Enter the API token ID (
monitor@pbs!octoja) and the API token secret. - (Optional) Limit monitoring to specific datastores under Datastores (exact names) and adjust the thresholds.
- Click Add Check.
After the first run, the result appears in the device's Checks tab.
Settings
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.
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/100orct/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:
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
Why does the check report "Access denied" although the user has permissions?
Why does the check report "Access denied" although the user has permissions?
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.
Why does the check report "PBS API request failed"?
Why does the check report "PBS API request failed"?
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.
A backup group keeps reporting "Latest completed backup exceeds the age threshold". What can I do?
A backup group keeps reporting "Latest completed backup exceeds the age threshold". What can I do?
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.
Was this helpful?
More in Backup
Acronis BackupAcronis Cyber Protect CloudAltaro BackupArcserve UDPStill need help? Ask the team