PBS users, ACLs, tokens and datastore permissions · Proxmox VE

Most Proxmox estates add PBS to the cluster with a root@pam credential because that is what the setup guide shows and it works immediately. It is also the configuration in which an attacker who gets root on any node of the cluster can delete every backup of every guest, and then encrypt the guests.

The permission model is the control that prevents that, and it is the only one that survives a fully compromised hypervisor. Firewall rules, network segmentation and immutable-storage claims all help, but if the credential stored on the compromised node can prune the datastore, they help less than you think.

This lesson is therefore organised around one question: what can the credential on your PVE node actually do to the datastore?

The object-path tree

PBS addresses everything it protects with filesystem-like paths. Permissions are granted by attaching a role to a path for an authentication identity.

Path	Covers
`/`	Everything
`/datastore`	All datastores
`/datastore/{store}`	One datastore
`/datastore/{store}/{ns}`	One namespace inside a datastore
`/remote`	All configured remotes
`/system/network`	Host network configuration
`/tape/`	Tape devices, pools and jobs
`/access/users`	User administration
`/access/openid/{id}`	A specific OpenID realm

Permissions granted at a shorter path can propagate down the tree:

Permissions of higher levels (shorter paths) can optionally be propagated down within this hierarchy.

The propagate flag defaults to enabled. That default is convenient and it is where over-permissioning creeps in: DatastoreAdmin on /datastore with propagation on is a grant over every datastore that exists and every one created later.

Namespaces are the unit that makes least privilege practical

The /datastore/{store}/{ns} level is what turns the permission model from a blunt instrument into a design tool. Give each cluster, tenant or site its own namespace and scope its credential there:

/datastore/store1/prod-cluster-a      <- token for cluster A
/datastore/store1/prod-cluster-b      <- token for cluster B
/datastore/store1/dmz                 <- token for the DMZ hosts

Cluster A cannot see, read, restore or delete cluster B’s backups, and a compromise of A does not become a compromise of B. Without namespaces the smallest boundary you have is the whole datastore, which means either one datastore per tenant — with the deduplication savings split across them — or a shared blast radius.

The roles, and what each is for

Role	Grants	Use it for
`NoAccess`	Nothing	Explicitly denying a subtree below a broader grant
`Admin`	Anything, on the object path assigned	Human administrators, scoped as narrowly as the job allows
`Audit`	View status and configuration; change nothing	Monitoring systems, auditors, junior on-call
`DatastoreAdmin`	Anything on existing datastores	A backup administrator who should not create datastores
`DatastoreAudit`	View metrics, settings and content listings; cannot read the actual data	Capacity dashboards and compliance evidence without data access
`DatastoreReader`	Inspect a datastore or namespace and perform restores	A restore-only operator account
`DatastoreBackup`	Back up and restore owned backups	The PVE cluster credential
`DatastorePowerUser`	Back up, restore and prune owned backups	A cluster that manages its own retention. Note what that implies
`RemoteAdmin`	Anything on remotes	Managing the remote configuration
`RemoteAudit`	View remote settings	Monitoring sync configuration
`RemoteSyncOperator`	Read data from a remote	The account a pull sync job runs as
`TapeAdmin` / `TapeOperator` / `TapeAudit` / `TapeReader`	Tape operations at descending privilege	Tape workflows

The two rows that carry the whole security argument are DatastoreBackup and DatastorePowerUser. They differ by exactly one capability: prune.

The append-only arrangement, and what it actually buys

Give the PVE cluster a token with DatastoreBackup on its namespace and nothing more. Then:

The cluster can create backups. Normal operation is unaffected.
The cluster can restore its own backups. Recovery is unaffected.
The cluster cannot prune, delete or expire anything.

Retention is then enforced by a prune schedule configured on the PBS server, using PBS’s own credentials, which the cluster never holds.

The result: an attacker with root on every node of the PVE cluster can encrypt the guests, and can push garbage into new backup snapshots, and cannot remove yesterday’s. That is the difference between an incident and a company-ending event, and it costs one role assignment.

This is what “append-only” means in a PBS context. There is no immutability flag doing the work — the guarantee comes from the credential not having the privilege, so the arrangement is only as good as the separation between the PVE credential and the PBS administrative credential. If the same password opens both, you have configured a diagram rather than a control.

Creating the accounts

Configuration changethe PVE cluster identity - a user, a token, one namespace— Run on the PBS server. The token secret is displayed once and cannot be shown again.

set -euo pipefail

# A dedicated user for the cluster, in the built-in PBS realm.
proxmox-backup-manager user create pve-cluster-a@pbs \
--comment 'Backup identity for production cluster A'

# A token belonging to that user. Tokens are what automation should carry;
# they can be revoked without disturbing the user or any other token.
proxmox-backup-manager user generate-token pve-cluster-a@pbs backup
# => { "tokenid": "pve-cluster-a@pbs!backup", "value": "REPLACE_ME_ONCE_ONLY" }

# Grant on the namespace only, not the datastore.
proxmox-backup-manager acl update /datastore/store1/prod-cluster-a \
DatastoreBackup --auth-id 'pve-cluster-a@pbs!backup'

# The token needs the grant; so does the user, because the effective
# permission is the intersection of the two.
proxmox-backup-manager acl update /datastore/store1/prod-cluster-a \
DatastoreBackup --auth-id 'pve-cluster-a@pbs'

Why a token needs its own grant, and can never exceed its user

The documented rule is precise and worth reading twice:

API token permissions are calculated based on ACLs containing their ID, independently of those of their corresponding user. The resulting permission set on a given path is then intersected with that of the corresponding user.

Two consequences that catch everyone once.

A token with no ACL of its own has no permissions, no matter what its user can do. Creating a token and using it immediately produces authentication failures that look like a bad secret. They are not — the secret is fine and the intersection is empty.

A token can never exceed its user. Granting DatastoreAdmin to a token whose user has only DatastoreBackup yields DatastoreBackup. This is the property that makes tokens safe to hand out: the blast radius of a token is bounded above by the account it belongs to, so a token issued to a script can be narrower than the human it belongs to but never wider.

The design pattern that falls out: give the user the widest role the role holder should ever have, and give each token the narrow slice its job needs. Revoking a token then removes exactly that slice.

Read-only / Safecheck what an identity can actually do, rather than what you meant— The authoritative answer. Read it after every grant, and especially after every grant you thought was narrower than it was.

# proxmox-backup-manager user permissions 'pve-cluster-a@pbs!backup' --path /datastore/store1/prod-cluster-a

Privileges with (*) have the propagate flag set

Path: /datastore/store1/prod-cluster-a
- Datastore.Backup (*)
- Datastore.Read (*)

Illustrative output

Wiring it into PVE

Configuration changeadd the PBS storage on the PVE side using the token— Run on any PVE node. The fingerprint pins the PBS certificate; get it from the PBS server rather than from the connection you are about to trust.

set -euo pipefail

# On the PBS server:
#   proxmox-backup-manager cert info | grep -i fingerprint

pvesm add pbs pbs-main \
--server pbs1.example.com \
--datastore store1 \
--namespace prod-cluster-a \
--username 'pve-cluster-a@pbs!backup' \
--password 'REPLACE_ME_ONCE_ONLY' \
--fingerprint 'aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99' \
--content backup

pvesm status --storage pbs-main

Configuration changeretention on the server side, where the cluster cannot reach it— Run on the PBS server. Verify with the prune simulator in the PBS GUI before applying to a namespace that matters.

set -euo pipefail

proxmox-backup-manager datastore update store1 \
--prune-schedule 'daily 04:00' \
--keep-daily 14 --keep-weekly 8 --keep-monthly 12

proxmox-backup-manager datastore update store1 --gc-schedule 'sat 03:00'

Roles for the other actors

Actor	Path	Role	Reasoning
PVE production cluster	`/datastore/store1/prod-cluster-a`	`DatastoreBackup`	Write and restore its own; never delete
Monitoring / dashboards	`/datastore`	`DatastoreAudit`	Needs usage and job status; must not be able to read backup contents
Restore-only operator	`/datastore/store1`	`DatastoreReader`	Can inspect and restore anything; cannot write or prune
Backup administrator	`/datastore`	`DatastoreAdmin`	Full control of existing datastores, no host administration
Pull sync from a remote	`/remote/{remote}/{store}`	`RemoteSyncOperator`	Read the remote; the local write privilege is granted separately
Standalone host client	`/datastore/store1/hosts`	`DatastoreBackup`	Same argument as the cluster, at host granularity

Sync jobs deserve a note because their privileges are split across two sides. A pull job needs Remote.Read on /remote/{remote}/{remote-store} plus Datastore.Backup on the local target, and additionally Datastore.Prune if it uses remove-vanished. A push job needs Remote.Audit and Remote.DatastoreBackup on the target, plus read or backup privileges on the source, and Remote.DatastorePrune for remove-vanished.

Pull is the more defensive direction, and this is why

In a pull arrangement the off-site PBS reaches into the primary and takes a copy. The primary holds no credential for the off-site server at all.

In a push arrangement the primary holds a credential that can write to the off-site datastore — so an attacker who owns the primary has a foothold on the copy that was supposed to be out of reach.

Push exists for good reasons: it works when the off-site server cannot reach into the primary network, which is a common firewall reality. If you use it, scope the remote credential to a single namespace on the target, withhold Remote.DatastorePrune, and let the off-site server run its own retention. Note also that pushed content is owned by the remote user, and that each push sync job should have its own dedicated remote configuration so jobs do not interfere with one another.

What happens if you leave root@pam in the PVE storage configuration?

Everything works, and three separate protections quietly do not exist.

Deletion. root@pam on PBS can prune anything, so an attacker with root on a PVE node can read the credential out of /etc/pve/storage.cfg and delete every snapshot in the datastore before starting on the guests. The whole 3-2-1 design collapses to one copy.

Blast radius across clusters. A single root@pam shared by three clusters means a compromise of the least important one is a compromise of all three sets of backups. Cluster boundaries stop being security boundaries.

Attribution. Every task in the PBS log is attributed to root@pam, so “who deleted the March snapshots?” has no answer, and neither does “which cluster is generating this load?”.

The migration off it is not disruptive and can be done a cluster at a time: create the user and token, grant on the namespace, update the storage definition with pvesm set, run one backup to confirm, then remove the old credential. The only step that needs care is confirming that the server-side prune schedule exists before the cluster loses the ability to prune.

Knowledge check

Why this matters

Ransomware response plans usually assume the backups survive. The technical reason they might not is almost always a credential: a root@pam in storage.cfg, or a DatastorePowerUser where DatastoreBackup would have done, on a node the attacker already owns.

What makes this lesson worth the time is that the fix is not a product, a budget line or a project. It is a user, a token, one ACL and a prune schedule moved from one side of the connection to the other. Half a morning, and the worst case changes from “every backup deleted” to “the attacker added some snapshots we will discard”.

The general principle transfers beyond PBS: the credential that writes the backup should not be able to destroy it. Everything in this lesson is one product’s implementation of that sentence.