Proxmox Backup Server Smart-Home-Integration, kostenlos und Open Source
Read-only monitoring of Proxmox Backup Server datastores and maintenance tasks.
Veröffentlicht von prohand
- Geräte
- Version 2.1.2
- Erfordert Gladys >=5.1.0
- ★ 0
Die Dokumentation dieser Integration wird von ihrem Autor geschrieben und ist bisher nur auf Englisch verfügbar.
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.
Konfigurationseinstellungen
Diese Einstellungen fragt Proxmox Backup Server in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Proxmox Backup Server connection | section | Nein | Create a dedicated API token with the read-only DatastoreAudit and Audit roles. See the documentation for the exact commands. |
| Server URL | string | Ja | For example: https://pbs.example.com:8007 |
| API token ID | string | Ja | Full ID, for example gladys@pbs!monitoring |
| API token secret | secret | Ja | |
| PBS node name | string | Nein | |
| Refresh interval (seconds) | number | Nein | |
| Verify TLS certificate | boolean | Nein | |
| Date format | select | Nein | Select how task dates are displayed, in the time zone set below. |
| Time zone | string | Nein | IANA name used to display dates, for example Europe/Paris. Empty or unknown: UTC. |
So installierst du Proxmox Backup Server in Gladys
- Öffne in Gladys Integrationen: Proxmox Backup Server erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/prohand/gladys-proxmox-backup-server:2.1.2) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/prohand/gladys-proxmox-backup-server.
Proxmox Backup Server benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
Proxmox Backup Server ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von prohand veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle externen Integrationen durchsuchen
- Die nativen Integrationen entdecken, die in Gladys eingebaut sind
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation