Proxmox Backup Server smart home integration, free and open source
Read-only monitoring of Proxmox Backup Server datastores and maintenance tasks.
Published by prohand
- Devices
- Version 2.1.1
- Requires Gladys >=5.1.0
- ★ 0
This integration only calls PBS API GET routes. It cannot start, alter, prune, or delete backups or jobs.
Exact read-only permissions
Grant the built-in DatastoreAudit role (Datastore.Audit) on /datastore, and the built-in Audit role (Sys.Audit) on /system so the task history can be read. Do not grant any datastore write, backup, prune, verify, or admin role.
proxmox-backup-manager user create gladys@pbs --password 'A_LONG_UNIQUE_PASSWORD'
proxmox-backup-manager user generate-token gladys@pbs monitoring
proxmox-backup-manager acl update /datastore DatastoreAudit --auth-id gladys@pbs --propagate true
proxmox-backup-manager acl update /datastore DatastoreAudit --auth-id 'gladys@pbs!monitoring' --propagate true
proxmox-backup-manager acl update /system Audit --auth-id gladys@pbs --propagate true
proxmox-backup-manager acl update /system Audit --auth-id 'gladys@pbs!monitoring' --propagate true
PBS API tokens use separate ACL entries by design; generate-token does not accept a --privsep option. Effective token permissions are the intersection of the parent user's permissions and the token's own permissions, hence the matching ACLs. Replace /datastore with /datastore/NAME in both datastore commands to restrict monitoring to one store. Enter the full token ID and the one-time secret in Gladys. Keep TLS verification enabled unless the server uses a self-signed certificate on a trusted network.
The refresh interval defaults to 15 minutes. It cannot be set below 5 minutes to limit growth of the Gladys database, and it can be increased up to 24 hours.
The general Date format dropdown controls all task dates. It offers ISO 8601, day/month/year, year-month-day, and month/day/year formats.
The Time zone field sets the zone dates are shown in, as an IANA name such as Europe/Paris (summer and winter time are handled). It defaults to UTC; an empty or unknown value also falls back to UTC. In ISO 8601, a zone other than UTC adds its offset, for example 2026-09-23T23:30:01+02:00.
After changing and saving the date format or the time zone, open the affected PBS device in Gladys and save it again to apply the change.
Exposed features
Each PBS datastore is exposed as one Gladys device with these read-only features:
The three capacity values (Usage, Total size, and Used space) are mapped to the Gladys data/size capability while retaining their percent or gigabyte unit.
| Feature | Value | Description |
|---|---|---|
| Usage | Percentage | Used datastore capacity, rounded to two decimal places. |
| Total size | Gigabytes | Total datastore capacity, rounded to two decimal places. |
| Used space | Gigabytes | Used datastore capacity, rounded to two decimal places. |
| Snapshot count | Integer | Number of snapshots currently stored, summed over the backup groups. |
| Last verify status | Text | Latest verification status, for example OK. |
| Last verify date | Text | Latest verification date, in the configured format. |
| Last garbage collection status | Text | Latest garbage collection status, for example OK. |
| Last garbage collection date | Text | Latest garbage collection date, in the configured format. |
| Last prune status | Text | Latest prune status, for example OK. |
| Last prune date | Text | Latest prune date, in the configured format. |
| Backup stale (> 26 h) | 0 or 1 | 1 when no snapshot exists or the newest snapshot is older than 26 hours. |
Dashboard widgets, scene triggers, and scene actions (Gladys 5.1)
These require Gladys 5.1.0 or later. They only read PBS: no button, trigger, or action can start, change, or delete anything on the server.
Dashboard widgets
Add them from the dashboard editor, in the widget list of this integration.
| Widget | Settings | Content |
|---|---|---|
| PBS datastore | One datastore, show tiles (default: on) | Usage gauge, free space, snapshot count, one card per verify/GC/prune task (date and result badge), last backup, used / total space, Refresh button. |
| PBS backups | None | Usage of the fullest datastore, stale backups, failed tasks, one status row per datastore (up to 10), Refresh button. |
The snapshot tile follows the device state live. The other tiles, the task cards, and the status rows are updated after each refresh. The Refresh button reads PBS again right away. Turn off Show usage, free space and snapshot tiles to hide the three tiles.
Scene triggers
They show up in the scene editor, in the "Integrations" category. Each filter is optional: leave it empty to match any value.
| Trigger | Fires when | Filters | Variables |
|---|---|---|---|
| PBS maintenance task finished | A verify, garbage collection, or prune task has ended. | Datastore, task type, result | datastore_name, task_type, result, status, date |
| New PBS backup | A newer snapshot appeared on the datastore. | Datastore | datastore_name, last_backup, snapshot_count |
| PBS backup is stale | The newest snapshot just became older than 26 hours. | Datastore | datastore_name, last_backup, hours_since_backup |
| PBS unreachable | A datastore refresh failed (once per outage). | Datastore | datastore_name, error |
| PBS reachable again | A datastore refresh succeeded after a failure. | Datastore | datastore_name |
result is ok, warning, or error; status is the raw PBS status, for example OK, WARNINGS: 2, or the error text.
- Triggers fire once per change, never at every refresh. Example: a backup that stays stale fires
PBS backup is staleonly once. - Changes are detected by the scheduled refresh (the refresh interval). A refresh asked by a widget or a scene action never fires a trigger itself; the next scheduled refresh reports the change.
- The first refresh after a start or a configuration change fires nothing: it sets the reference point.
- If several tasks of the same type finish between two refreshes, only the newest is reported.
Scene actions
| Action | Fields | Outputs |
|---|---|---|
| Get PBS datastore status | Datastore (required), Read PBS now (default: off) | datastore_name, usage_percent, used_gb, total_gb, snapshot_count, backup_stale, last_backup, hours_since_backup, last_verify_status, last_verify_date, last_gc_status, last_gc_date, last_prune_status, last_prune_date |
| Get PBS backup report | Read PBS now (default: off), report language (en/fr) | datastore_count, stale_count, failed_task_count, unreachable_count, max_usage_percent, all_ok, summary |
- Without
Read PBS now, the action answers from the last refresh and costs nothing on PBS. summaryis a ready-to-send text, one line per datastore. Example for a daily report: "Every day at 8:00" → "Get PBS backup report" → "Send a message" with thesummaryoutput.- Example alert: "PBS maintenance task finished" filtered on result
error→ "Send a message":PBS {{triggerEvent.data.task_type}} failed on {{triggerEvent.data.datastore_name}}: {{triggerEvent.data.status}}.
Behaviour notes
- Snapshot count and backup freshness are read from the datastore's backup groups (
backup-countandlast-backup), so a datastore holding thousands of snapshots costs one small response per refresh. If a PBS release does not expose those counters, the integration falls back to listing the snapshots. - The task history is read page by page until the newest verify, garbage collection, and prune tasks have been found (up to 2000 tasks), so a busy datastore does not push them out of view and back to
Never run. - Datastores that are offline or unmounted report no capacity; the integration then publishes
0for usage, total size, and used space rather than an invalid value. - A refresh that fails (network error, timeout, PBS restart) is retried on the next one-minute Gladys tick instead of waiting a full refresh interval. At startup, the connection is retried four times with an exponential backoff before the integration reports itself as disconnected.
Checking which inventory route is used
The integration prefers the cheap groups route and falls back to the full snapshot list; the fallback is logged as a warning in the container logs (Falling back to the snapshot list for datastore ..., with the PBS error that caused it).
To check it against your server without installing anything in Gladys, run the read-only diagnostic from a clone of this repository:
PBS_URL=https://pbs.example.com:8007 \
PBS_TOKEN_ID='gladys@pbs!monitoring' \
PBS_TOKEN_SECRET='the-token-secret' \
npm run check:pbs
It prints, per datastore, the route actually used, how long each route takes, and the last verify/GC/prune task. It also cross-checks the snapshot count and the newest backup against the full snapshot list, and exits with code 1 if the two disagree. Add PBS_NODE=... for a node other than localhost, and PBS_VERIFY_TLS=false for a self-signed certificate.
The same routes can be checked by hand:
curl -sSf -H "Authorization: PBSAPIToken=gladys@pbs!monitoring:SECRET" \
'https://pbs.example.com:8007/api2/json/admin/datastore/NAME/groups' | head -c 400
An HTTP 403 means the ACL is missing Datastore.Audit on that datastore; an HTTP 404 means this PBS release does not serve the route and the snapshot fallback is expected.
Configuration settings
These are the settings Proxmox Backup Server asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Proxmox Backup Server connection | section | No | Create a dedicated API token with the read-only DatastoreAudit and Audit roles. See the documentation for the exact commands. |
| Server URL | string | Yes | For example: https://pbs.example.com:8007 |
| API token ID | string | Yes | Full ID, for example gladys@pbs!monitoring |
| API token secret | secret | Yes | |
| PBS node name | string | No | |
| Refresh interval (seconds) | number | No | |
| Verify TLS certificate | boolean | No | |
| Date format | select | No | Select how task dates are displayed, in the time zone set below. |
| Time zone | string | No | IANA name used to display dates, for example Europe/Paris. Empty or unknown: UTC. |
How to install Proxmox Backup Server in Gladys
- In Gladys, open Integrations: Proxmox Backup Server appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/prohand/gladys-proxmox-backup-server:2.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/prohand/gladys-proxmox-backup-server.
Proxmox Backup Server requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Proxmox Backup Server is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by prohand, not by the Gladys core team.
- Browse all external integrations
- Discover the native integrations built into Gladys
- Build and publish your own external integration
- Source code on GitHub — source of this documentation