Proxmox Backup Server

This page gets Ferrule reading your Proxmox Backup Server (PBS) with a read-only API token.

What Ferrule reads: how full each datastore is and PBS's own estimate of when it fills; the last run of every job in the past week (backups, verify, prune, sync, garbage collection); and when each machine was last backed up. What it can't: it changes nothing, and it doesn't read the backups themselves.

Make the read-only token

In the PBS web interface, go to Configuration → Access Control:

1. User Management → Add: user ID telemetry, realm Proxmox Backup authentication server (pbs). Give it a long random password; Ferrule never uses it.
2. API Token → Add: user telemetry@pbs, token name ro. Copy the secret now: it's shown once.
3. Permissions → Add → User Permission: path /, user telemetry@pbs, role Audit, Propagate ticked.
4. Permissions → Add → API Token Permission: path /, token telemetry@pbs!ro, role Audit, Propagate ticked.

Do both step 3 and step 4

A token sees only what both it and its user may see. Miss either and PBS shows Ferrule no datastores, jobs or backups, with no error.

Enter it in the setup wizard

On the wizard's What you have page, set Proxmox Backup Server to the number you have. On its page:

1. Name: what you call it, such as pbs1.
2. Address: with the port: https://192.168.1.20:8007.
3. API token ID: telemetry@pbs!ro.
4. API token secret: the secret from step 2.
5. Leave Verify the certificate off, unless PBS has a trusted certificate.
6. Click Test.

When it works you see ✓ Connected: and what it found, such as 2 datastores, 14 backup groups, 9 jobs. A job whose last run failed is listed underneath.

Editing the stack by hand

Each source takes a numbered slot, SOURCE_1 to SOURCE_8, with its secret beside it. Write any $ in the secret as $$.

SOURCE_2=pbs https://192.168.1.20:8007 name=pbs1 user=telemetry@pbs!ro
SOURCE_2_SECRET=<the token secret>

Settings → Add a source writes the first line for you. See Every variable.

Where it shows up

PBS gets a panel on the Virtualization tab, beside the machines it backs up. Settings → Sources lists it as polling; for the first minute it says waiting for first poll.

It alerts on a job whose last run failed (critical) or finished with warnings, a datastore PBS can't read, and one nearly full. A job's alert clears when that job next runs clean.

A machine with no backup for 26 hours is highlighted, not alerted, because a machine you've deleted keeps its old backups forever. You can change the 26 hours under Settings → Display, Hours since a backup. That setting is kept in your browser only.

Retention and deduplication

New in the next release

This is on the dev and qa builds now, and in the next release.

With capacity planning, each datastore's row on the Capacity tab says what it keeps and how far along it is:

keeps 7 daily, 4 weekly, 6 monthly (prune job daily-main) · retention 40% filled · 2.7× dedup

The keep policy comes from the first of these that has one:

1. A prune job on PBS for that datastore, that isn't disabled.
2. The datastore's own keep settings, on PBS servers older than prune jobs.
3. The Proxmox VE backup job that writes to it, when Ferrule also watches that Proxmox VE cluster: the job's Retention, or failing that the PBS storage's in Proxmox VE. The row then says (Proxmox VE job …). It's matched by the PBS server and datastore name, or by the datastore name alone when only one storage uses it. See Proxmox VE.

Retention filled compares each backup group that backed up within a week of the newest one with the number of snapshots the policy keeps for a group backed up once a day. A group of a deleted machine isn't filling anything, so it isn't counted. Under 90%, the store is still growing into its policy and will level off; the forecast and any runway alert say the date may be early.

Deduplication is the ratio garbage collection last reported: the data the backups refer to over the space it takes on disk. It shows after garbage collection has run once. When the token can't read garbage collection, the row says dedup unknown: can't read garbage collection, with the reason.

The read-only Audit role this page sets up reads all of it.

If something's wrong

What you see	What to do
Connected, but 0 datastores, and the panel says Proxmox Backup Server shows this token no datastores	Step 3 or step 4 is missing. Add it.
Proxmox Backup Server refused the credentials	The token ID or secret is wrong.
set user= on the slot to the API token ID	Use the token ID, telemetry@pbs!ro, not the user.
Nothing answered at that address and port.	Add the port, :8007.
The certificate isn't trusted.	Untick Verify the certificate.
dedup unknown: can't read garbage collection on the Capacity tab	The token's user lacks the Audit role on that datastore. Garbage collection must also have run once.
No keep policy on the row	PBS has no prune job or keep settings for it, and no watched Proxmox VE job writes to it. Retention set on a PVE job shows only when that Proxmox VE cluster is a source too.
Ferrule couldn't reach Proxmox Backup Server from the Docker host: no answer.	A firewall is blocking the Docker host from port 8007.

See Troubleshooting for more.