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

# Proxmox Backup Server API

[Version francaise](../api-pbs.md)

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:

```text
Authorization: PBSAPIToken=TOKENID:TOKENSECRET
```

Example PBS server configuration:

```env
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:

```text
/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.