Proxmox BS: secure PVE connection via API & encryption

Introduction

This tutorial explains how to connect Proxmox VE to Proxmox Backup Server using Proxmox API tokens, namespace-limited permissions, and client-side encryption. This approach improves Proxmox VE security because Proxmox VE does not need a full PBS user password and the backup server does not need access to unencrypted VM backup data.

You will configure secure API token authentication, register the Proxmox Backup Server storage in Proxmox VE, enable client-side backup encryption, and configure prune and garbage collection schedules to prevent the datastore from consuming all available storage.

Prerequisites

Target audience: Intermediate system administrators.
Estimated completion time: 45 to 60 minutes.
End goal: By the end of this tutorial, you will have a secure Proxmox backup repository connected to Proxmox VE with restricted API token access, encrypted VM backups, and retention settings that match your storage capacity.

Required environment:

• Proxmox VE 8.x or later.
• Proxmox Backup Server 3.x or later.
• Administrative access to the Proxmox VE web interface or shell.
• Administrative access to the Proxmox Backup Server web interface or shell.
• An existing PBS datastore.
• Network connectivity from Proxmox VE to PBS on TCP port 8007.
• Enough datastore capacity for the planned backup retention window.

Example values used in this tutorial:

Placeholder	Example value	Description
<PBS_HOST>	pbs.example.com	PBS hostname or IP address
<PBS_PORT>	8007	Default PBS API port
<DATASTORE>	backup-store	PBS datastore name
<NAMESPACE>	pve-prod	Namespace for this Proxmox VE source
<PBS_USER>	pve-backup@pbs	PBS user created for Proxmox VE
<TOKEN_NAME>	pve-token	API token name
<TOKEN_ID>	pve-backup@pbs!pve-token	Full PBS API token ID
<PVE_STORAGE_ID>	pbs-secure	Storage ID shown in Proxmox VE
<PBS_FINGERPRINT>	AA:BB:CC:...	PBS certificate fingerprint

Step 1: Plan the Secure Proxmox Backup Design

Before changing any configuration, define how Proxmox VE should access PBS.

Use this design:

Component	Recommended setting
Authentication	API token instead of user password
Access scope	Datastore namespace, not the entire datastore
PBS role	DatastoreBackup plus DatastoreReader if restore browsing is required
Encryption	Client-side encryption enabled in Proxmox VE
Retention	PBS prune job or datastore retention policy
Space cleanup	Scheduled garbage collection after pruning
Compromise response	Revoke the token and create a replacement

This design follows the principle of least privilege. Proxmox Backup Server uses role-based and path-based permissions. Access can be assigned to a specific datastore or namespace path, such as /datastore/<DATASTORE>/<NAMESPACE>.

Step 2: Create a Dedicated PBS User

Log in to the PBS shell as root or another administrator.

Create a dedicated PBS realm user for Proxmox VE:

proxmox-backup-manager user create <PBS_USER> \
  --comment "Proxmox VE backup user"

Expected result: empty output or message

User '<PBS_USER>' created.

Verify that the user exists:

proxmox-backup-manager user list

Expected result:

userid          enable  expire  comment
<PBS_USER>     1                Proxmox VE backup user
root@pam       1                Superuser

Step 3: Create a Namespace for Proxmox VE Backups

A namespace lets you separate one Proxmox VE host or cluster from other backup sources inside the same datastore. This is useful for secure Proxmox backup authentication because permissions can be scoped to only that namespace.

You can create the namespace from the PBS web interface:

1. Open the PBS web interface.
2. Go to Datastore.
3. Select <DATASTORE>.
4. Open Content.
5. Click Add Namespace.
6. Enter <NAMESPACE>.
7. Click Create.

Expected result: PBS creates the namespace under the selected datastore.

If you prefer the command line, use the PBS client namespace command:

proxmox-backup-client namespace create <NAMESPACE> \
  --repository root@pam@localhost:<DATASTORE>

Expected result: empty output or message

Namespace '<NAMESPACE>' created.

Step 4: Generate an API Token

Create an API token for the PBS user through the web interface by navigating to Configuration → Access Control → API Token → Add:

Alternatively, generate an API token for the PBS user through the CLI:

proxmox-backup-manager user generate-token <PBS_USER> <TOKEN_NAME>

Expected output:

{
  "tokenid": "<TOKEN_ID>",
  "value": "<TOKEN_SECRET>"
}

Save <TOKEN_SECRET> immediately. It cannot be displayed again after creation.

Step 5: Assign Least-Privilege Permissions

API token permissions in PBS are calculated from the token ACL and then intersected with the parent user permissions. In practice, the user and the token both need appropriate access, and the token can never do more than its parent user.

Grant the parent user backup access to only the desired namespace:

proxmox-backup-manager acl update \
  /datastore/<DATASTORE>/<NAMESPACE> DatastoreBackup \
  --auth-id <PBS_USER>

Grant the token the same backup role:

proxmox-backup-manager acl update \
  /datastore/<DATASTORE>/<NAMESPACE> DatastoreBackup \
  --auth-id <TOKEN_ID>

If you want Proxmox VE to browse and restore existing owned backups from the same namespace, add DatastoreReader as well:

proxmox-backup-manager acl update \
  /datastore/<DATASTORE>/<NAMESPACE> DatastoreReader \
  --auth-id <PBS_USER>

proxmox-backup-manager acl update \
  /datastore/<DATASTORE>/<NAMESPACE> DatastoreReader \
  --auth-id <TOKEN_ID>

Verify the ACLs:

proxmox-backup-manager acl list

Expected output:

ugid                         path                                      roleid
<PBS_USER>                   /datastore/<DATASTORE>/<NAMESPACE>       DatastoreBackup
<TOKEN_ID>                   /datastore/<DATASTORE>/<NAMESPACE>       DatastoreBackup
<PBS_USER>                   /datastore/<DATASTORE>/<NAMESPACE>       DatastoreReader
<TOKEN_ID>                   /datastore/<DATASTORE>/<NAMESPACE>       DatastoreReader

Do not assign Admin or DatastoreAdmin to a Proxmox VE backup token unless you have a specific operational reason. For most encrypted VM backups, a namespace-scoped token with DatastoreBackup and optional DatastoreReader is a safer Proxmox backup best practice.

Step 6: Record the PBS Certificate Fingerprint

If PBS uses a self-signed certificate, Proxmox VE must trust the PBS fingerprint.

On the PBS server, run:

proxmox-backup-manager cert info | grep Fingerprint

Expected output:

Fingerprint (sha256): <PBS_FINGERPRINT>

Save the fingerprint for the next step.

Step 7: Add PBS Storage to Proxmox VE

Log in to the Proxmox VE shell as root.

Add the PBS storage using the API token ID as the username. Enter the token secret when prompted:

pvesm add pbs <PVE_STORAGE_ID> \
  --server <PBS_HOST> \
  --port <PBS_PORT> \
  --datastore <DATASTORE> \
  --namespace <NAMESPACE> \
  --username <TOKEN_ID> \
  --fingerprint <PBS_FINGERPRINT> \
  --password

When prompted, paste the API token secret:

Enter Password: <TOKEN_SECRET>

Expected result: Proxmox VE adds the PBS storage configuration.

Verify the storage:

pvesm status --storage <PVE_STORAGE_ID>

Expected output:

Name             Type     Status     Total        Used     Available     %
<PVE_STORAGE_ID> pbs      active     ...

When using a namespace-restricted API token, the Total, Used, and Available values may display as 0 even when the status is active. This behavior is normal.

You can also configure this from the Proxmox VE web interface:

1. Open Datacenter.
2. Go to Storage.
3. Click Add.
4. Select Proxmox Backup Server.
5. Set ID to <PVE_STORAGE_ID>.
6. Set Server to <PBS_HOST>.
7. Set Datastore to <DATASTORE>.
8. Set Namespace to <NAMESPACE>.
9. Set Username to <TOKEN_ID>.
10. Set Password to the API token secret.
11. Set Fingerprint to <PBS_FINGERPRINT> if required.
12. Click Add.

Expected result: The storage appears under Proxmox VE storage and reports as active.

Step 8: Enable Client-Side Encryption

Client-side encryption protects backup data before it leaves Proxmox VE. PBS stores encrypted VM backups, but the encryption key remains on the Proxmox VE side. This improves Proxmox VE backup security because a compromised PBS datastore alone does not expose VM disk contents.

From the Proxmox VE web interface:

1. Open Datacenter.
2. Go to Storage.
3. Select <PVE_STORAGE_ID>.
4. Click Edit.
5. Go to the Encryption tab and select an Auto-generate a client encryption key.
6. Generate a new key if this is a new secure backup repository.
7. Store a backup copy of the encryption key in a password manager or offline secret vault.
8. Click OK.

Expected result: New backups to this PBS storage are encrypted on the client side.

Recommended key handling:

Practice	Reason
Store the key outside the Proxmox VE cluster	Protects against cluster loss
Restrict file permissions	Reduces local exposure
Back up the key offline	Enables disaster recovery
Do not store the key on PBS only	PBS loss or compromise must not block recovery
Test restore with the key	Confirms recovery works before an incident

Step 9: Create a Proxmox VE Backup Job

Create a backup job that writes to the encrypted PBS storage.

From the Proxmox VE web interface:

1. Open Datacenter.
2. Go to Backup.
3. Click Add.
4. Select the nodes, VMs, or containers to protect.
5. Set Storage to <PVE_STORAGE_ID>.
6. Choose a schedule, such as daily at 02:00.
7. Set the mode according to your workload.
8. Leave retention empty if PBS will manage pruning.
9. Click Create.

Expected result: Proxmox VE creates a scheduled backup job that writes encrypted backups to PBS.

Keep retention in one place. For most PBS designs, configure retention on PBS using prune jobs or datastore retention settings, and leave Proxmox VE job retention empty. This avoids confusing overlaps between Proxmox VE retention and PBS pruning.

Step 10: Configure Prune Settings

Pruning decides which backup snapshots remain visible and restorable. It does not immediately remove all unreferenced chunks from disk. PBS prune jobs can be configured from the Prune & GC tab or with proxmox-backup-manager prune-job. Proxmox documentation states that prune job configuration is stored in /etc/proxmox-backup/prune.cfg.

A common retention policy for daily VM backups is:

Setting	Value	Meaning
keep-daily	7	Keep one backup per day for the last 7 days
keep-weekly	4	Keep one backup per week for the last 4 weeks
keep-monthly	6	Keep one backup per month for the last 6 months

Configure this policy on the datastore:

proxmox-backup-manager prune-job create <JOB_ID> \
  --store <DATASTORE> \
  --ns <NAMESPACE> \
  --keep-daily 7 \
  --keep-weekly 4 \
  --keep-monthly 6 \
  --prune-schedule "03:00"

Expected result: PBS applies retention and runs pruning daily at 03:00.

For a smaller datastore, use a shorter policy:

proxmox-backup-manager prune-job create <JOB_ID> \
  --store <DATASTORE> \
  --ns <NAMESPACE> \
  --keep-daily 3 \
  --keep-weekly 2 \
  --keep-monthly 1 \
  --prune-schedule "03:00"

Expected result: PBS keeps fewer restore points and consumes less space.

Step 11: Estimate Backup Storage Volume

PBS deduplicates chunks, so storage consumption is not simply the full VM size multiplied by the number of backups. However, you still need a conservative estimate.

Use this formula:

Estimated required capacity = initial full protected data
+ changed data per backup * retained backup points
+ safety margin

Example 1: Small environment

Value	Amount
Protected VM data	600 GiB
Average daily change rate	3 percent
Changed data per day	18 GiB
Retention	7 daily, 4 weekly, 6 monthly
Approximate retained points	17
Changed data estimate	306 GiB
Safety margin	30 percent

Calculation:

600 GiB + (18 GiB * 17) = 906 GiB
906 GiB * 1.30 = 1177.8 GiB

Recommended datastore capacity: at least 1.2 TiB, preferably 1.5 TiB or more.

Example 2: Larger production environment

Value	Amount
Protected VM data	4 TiB
Average daily change rate	5 percent
Changed data per backup	204.8 GiB
Retention	14 daily, 8 weekly, 12 monthly
Approximate retained points	34
Changed data estimate	6.8 TiB
Safety margin	30 percent

Calculation:

4 TiB + (204.8 GiB * 34) = 10.8 TiB
10.8 TiB * 1.30 = 14.04 TiB

Recommended datastore capacity: at least 14 TiB, preferably 16 TiB or more.

Step 12: Configure Garbage Collection

Garbage collection (GC) is the process that actually removes unreferenced chunks from the datastore. Pruning removes backup snapshots according to retention rules, but chunks can remain on disk if other snapshots still reference them or if they are still inside the safety window.

PBS garbage collection has two phases:

Phase	What happens
Mark	PBS reads index files and updates access time for referenced chunks
Sweep	PBS scans chunks and removes chunks older than the cutoff time if no snapshot references them

PBS uses a cutoff based on the oldest running backup writer or 24 hours and 5 minutes before the GC start time. Chunks inside this grace period are logged as pending removals instead of being deleted immediately. This protects currently running backups and accounts for filesystem relatime behavior.

Schedule GC after pruning:

proxmox-backup-manager datastore update <DATASTORE> \
  --gc-schedule "04:30"

Expected result: PBS runs garbage collection daily at 04:30.

Recommended schedule for a daily backup at 02:00:

Task	Example time	Purpose
Proxmox VE backup	02:00	Create encrypted VM backups
PBS prune	03:00	Apply retention policy
PBS garbage collection	04:30	Reclaim unreferenced chunks when safe

Check GC status:

proxmox-backup-manager garbage-collection status <DATASTORE>

Start GC manually when needed:

proxmox-backup-manager garbage-collection start <DATASTORE>

Expected result: PBS starts a datastore-level garbage collection task. The official PBS documentation also provides these commands and the web UI option under the datastore Prune & GC tab.

Step 13: Run a Test Backup

Run the backup job manually from Proxmox VE:

1. Open Datacenter.
2. Go to Backup.
3. Select the backup job.
4. Click Run now.
5. Confirm the action.

Expected result: The backup task completes successfully.

You can also check from the Proxmox VE shell:

pvesm status --storage <PVE_STORAGE_ID>

Expected output:

Name              Type     Status
<PVE_STORAGE_ID>  pbs      active

On PBS, open:

1. Datastore.
2. <DATASTORE>.
3. Content.
4. <NAMESPACE>.

Expected result: The new VM or container backup appears in the namespace.

Verification

Verify token permissions on PBS:

proxmox-backup-manager user permissions <TOKEN_ID> \
  --path /datastore/<DATASTORE>/<NAMESPACE>

Expected result: The token shows datastore permissions only for the target namespace.

Verify storage access from Proxmox VE:

pvesm status --storage <PVE_STORAGE_ID>

Expected result:

<PVE_STORAGE_ID> pbs active

Verify that backups are encrypted:

1. Open Proxmox VE.
2. Select the VM backup on the PBS storage.
3. Confirm that restore operations are available from Proxmox VE.
4. Confirm that the key is backed up outside the cluster.

Verify prune and GC configuration:

proxmox-backup-manager datastore show <DATASTORE>

Expected result: The datastore configuration shows the prune and garbage collection schedules.

What to Do if the API Token Is Compromised

If the token secret is exposed, revoke it immediately.

On PBS, delete the token:

proxmox-backup-manager user delete-token <PBS_USER> <TOKEN_NAME>

Expected result: PBS removes the token.

Then create a replacement token:

proxmox-backup-manager user generate-token <PBS_USER> <NEW_TOKEN_NAME>
proxmox-backup-manager acl update /datastore/<DATASTORE>/<NAMESPACE> DatastoreBackup --auth-id '<PBS_USER>!<NEW_TOKEN_NAME>'
proxmox-backup-manager acl update /datastore/<DATASTORE>/<NAMESPACE> DatastoreReader --auth-id '<PBS_USER>!<NEW_TOKEN_NAME>'

Update the Proxmox VE storage password:

pvesm set <PVE_STORAGE_ID> --username '<PBS_USER>!<NEW_TOKEN_NAME>'
pvesm set <PVE_STORAGE_ID> --password

When prompted, paste the new token secret.

Expected result: Proxmox VE uses the new token for secure API token authentication.

Reverting Changes

Remove the Proxmox VE storage entry:

pvesm remove <PVE_STORAGE_ID>

Expected result: Proxmox VE removes the PBS storage configuration. Existing backups on PBS remain in the datastore.

Delete the API token:

proxmox-backup-manager user delete-token <PBS_USER> <TOKEN_NAME>

Expected result: PBS revokes the API token.

Remove ACL entries:

proxmox-backup-manager acl update /datastore/<DATASTORE>/<NAMESPACE> DatastoreReader \
  --auth-id <ID> --delete 1

proxmox-backup-manager acl update /datastore/<DATASTORE>/<NAMESPACE> DatastoreBackup \
  --auth-id <ID> --delete 1

Expected result: PBS removes the namespace permissions.

Remove the dedicated user if it is no longer needed:

proxmox-backup-manager user remove <PBS_USER>

Expected result: PBS removes the user.

Troubleshooting

Proxmox VE Shows PBS Storage as Inactive

Check network access:

nc -vz <PBS_HOST> 8007

Expected output:

Connection to <PBS_HOST> 8007 port [tcp/*] succeeded!

Check the PBS fingerprint:

proxmox-backup-manager cert info | grep Fingerprint

If the fingerprint changed, update it in Proxmox VE:

pvesm set <PVE_STORAGE_ID> --fingerprint <PBS_FINGERPRINT>

Authentication Fails with the API Token

Confirm that the username is the full token ID:

<PBS_USER>!<TOKEN_NAME>

Example:

pve-backup@pbs!pve-token

Confirm that the password field contains the token secret, not the PBS user password.

Confirm permissions:

proxmox-backup-manager acl list

The token must have ACL entries on the namespace path, and the parent user must also have compatible permissions.

Backup Fails with Permission Errors

Check the namespace path:

/datastore/<DATASTORE>/<NAMESPACE>

Do not use the filesystem path of the datastore, such as /mnt/datastore/<DATASTORE>, when assigning ACLs. PBS ACL paths use the /datastore/<DATASTORE> format.

Datastore Keeps Growing After Pruning

This is usually expected if GC has not run yet or if chunks are still inside the safety window. PBS does not delete chunks immediately after prune because chunks may still be referenced by other snapshots or protected by the GC cutoff window.

Check GC status:

proxmox-backup-manager garbage-collection status <DATASTORE>

If GC is not scheduled, configure it:

proxmox-backup-manager datastore update <DATASTORE> \
  --gc-schedule "04:30"

Encrypted Backups Cannot Be Restored

Confirm that the Proxmox VE storage still has access to the encryption key.

Check your internal backup key inventory. If the original Proxmox VE cluster is lost, restore requires the saved encryption key. Without it, client-side backup encryption can prevent recovery.

Conclusion

You configured a secure Proxmox Backup Server connection from Proxmox VE using a dedicated PBS user, Proxmox API tokens, namespace-limited permissions, and client-side encryption. You also configured prune and garbage collection schedules so the backup encryption in Proxmox setup remains sustainable as backup history grows.

This configuration improves Proxmox VE backup authentication, protects encrypted VM backups from server-side exposure, and provides a practical secure backup repository for long-term Proxmox Backup Server configuration.

Recommended next steps:

• Test a full VM restore.
• Test a file-level restore.
• Store the encryption key in at least two secure locations.
• Monitor datastore growth after each prune and GC cycle.
• Add PBS verification jobs to detect silent backup corruption.
• Document the token revocation process in your incident response plan.

Document Version: 1.0
Last Updated: June 2026
Owner: Technical Documentation Team