PVE-Backup-Report/docs/en/api-pbs.md

Proxmox Backup Server API

Version francaise

This document describes the PBS collection used by the report.

Objective

PBS collection complements the PVE report with configured retention policies and backup versions visible on configured Proxmox Backup Server instances.

The application can query one or more PBS servers. Each server is collected only if its API URL, token ID and token secret are provided.

This step does not prove synchronizations between PBS servers. It collects prune jobs and snapshots visible on each configured PBS.

Authentication

The PBS client uses a PBS API token.

The HTTP header is:

Authorization: PBSAPIToken=TOKENID:TOKENSECRET

Example PBS server configuration:

PBS01_NAME=display-name
PBS01_API_URL=https://backup.example.invalid:8007
PBS01_API_TOKEN_ID=
PBS01_API_TOKEN_SECRET=

To collect multiple PBS servers, duplicate this block with PBS02_*, PBS03_*, PBS04_*, etc. All complete PBS<number>_* blocks are detected automatically.

The token secret must never be logged or appear in the report.

Used Endpoints

Data	PBS endpoint
Prune jobs	/config/prune
PBS datastores	/config/datastore
Datastore status	/admin/datastore/{datastore}/status
Datastore garbage collector status	/admin/datastore/{datastore}/gc
Datastore namespaces	/admin/datastore/{datastore}/namespace
Datastore/namespace snapshots	/admin/datastore/{datastore}/snapshots?ns={namespace}
PBS users	/access/users
Effective permissions	/access/permissions?auth-id={auth-id}&path={path}

The client automatically appends /api2/json to the PBS URL if this suffix is not already present.

Normalized Data

Each PBS prune job is transformed into a retention policy with the following fields:

• job identifier;
• PBS server;
• datastore;
• namespace;
• schedule;
• active/inactive state;
• keep-last;
• keep-hourly;
• keep-daily;
• keep-weekly;
• keep-monthly;
• keep-yearly;
• max-depth;
• comment.

If the ns field is missing, the namespace is considered to be the root /. The report computes the expected version count for a VM/CT from the active retention policy matching the same PBS server, datastore and namespace as the snapshots. This count is the sum of configured keep-last, keep-hourly, keep-daily, keep-weekly, keep-monthly and keep-yearly values. The delta displays visible snapshot count - expected count.

Each PBS snapshot is aggregated by datastore, namespace, backup type and VMID to produce:

• number of backup versions;
• oldest backup date;
• newest backup date;
• size of the newest backup when PBS exposes this information.

Snapshots still visible on PBS while the VM/CT no longer exists in the PVE inventory are kept in the retention table and marked Not active on PVE. Snapshots whose namespace is not declared in PVE-side PBS storages are excluded from these retention tables.

The status of each configured PBS datastore is collected to display total, used and free space in the report.

PBS Users Declared on PVE

The --dump-pbs-users diagnostic command collects PBS storages declared in PVE through /storage, then matches their username field with users visible on each configured PBS through /access/users.

For each PVE PBS storage with a username, the diagnostic queries effective permissions for this auth-id on the target PBS path:

/datastore/{datastore}
/datastore/{datastore}/{namespace}

The second format is used when a non-root namespace is declared on the PVE side.

Collected information feeds the report table PBS users - Access audit and the diagnostic command. It is used to verify which PBS account is used by PVE, whether the account is active when PBS exposes this information, and which effective privileges are available on the target datastore/namespace.

If the PVE username is a PBS token of type user@realm!token, matching with /access/users uses the parent user user@realm; permissions are requested with the full auth-id.

PBS types vm and ct are matched with PVE types qemu and lxc.

Snapshot collection queries datastores exposed by each configured PBS. For each datastore, it also adds all namespaces declared in PVE PBS storages, even if the relevant PBS does not directly receive VM/CT backups from PVE. This makes it possible to find synchronized backups on a secondary PBS, for example in namespaces serveurs-internes or Serveurs-PVELAB.

Namespaces returned by the target PBS API are still collected as well. Snapshots are then matched to VM/CT by type and VMID.

Because these additional servers can contain direct and synchronized backups, some /snapshots calls can take longer. Increase the timeout for the relevant PBS block if the default timeout is insufficient.

Error Handling

If no PBS is configured, PBS collection is skipped.

If a configured PBS is unavailable, the report continues and a pbs_retention anomaly is added for the relevant server.

If a configured PBS is unavailable for snapshot collection, the report continues and a pbs_snapshots anomaly is added for the relevant server.

When a namespace declared in PVE is tested on a PBS datastore where it does not exist, PBS may return HTTP 400 - Bad Request on the /snapshots endpoint. For a non-root namespace, this response is interpreted as namespace absence on that datastore and is not reported as an anomaly. Other errors, including a 400 on root /, remain visible.

If the /config/prune response is not a list, the report continues and adds an anomaly.

If /config/prune returns an empty list while a PBS is configured, a warning anomaly is added to verify either the real absence of prune jobs or the effective permissions of the PBS token.

Limits

Collection does not yet check:

• synchronizations between PBS servers;
• prune job execution state;
• the effective result of a prune on snapshots.

These points can be added in a dedicated step.