Set Up Backups on a Proxmox VE Host

This guide shows how to connect a Proxmox VE host or cluster to your hosted Proxmox Backup Server datastore.

Before you start

You need:

• Access to the Proxmox VE web interface as a user that can manage storage.
• Your PBS server, datastore, username and password or API token.
• The PBS TLS fingerprint if the PBS certificate is not trusted by your PVE host.
• The namespace value if your service uses one.

Port 8007 must be reachable from every PVE node that will create or restore backups.

Optional: get the TLS fingerprint

If the fingerprint was not provided in your service details, you can read it from the PBS certificate:

openssl s_client -connect pbs.example.com:8007 -servername pbs.example.com </dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha256

Replace pbs.example.com with your PBS server hostname.

Add PBS storage in the PVE web interface

1. Log in to the Proxmox VE web interface.
2. Open Datacenter.
3. Go to Storage.
4. Click Add.
5. Select Proxmox Backup Server.
6. Fill in the storage details.

Use these values:

If you use a PBS API token, the username format is usually user@realm!token-name and the password field contains the token secret.

Click Add to save the storage.

Add PBS storage with the CLI

You can also add the storage from a PVE node shell:

pvesm add pbs nc-pbs \
  --server pbs.example.com \
  --datastore customer-datastore \
  --username 'customer@pbs' \
  --password 'your-password-or-token-secret' \
  --fingerprint 'SHA256:FINGERPRINT' \
  --content backup

If your service uses a namespace, add it to the command:

  --namespace pve

Verify the storage

Run this on a PVE node:

pvesm status

The new PBS storage should appear with type pbs and an active status.

You can also open Datacenter > Storage in the PVE web interface and confirm the storage is enabled.

Run a test backup

1. Open a VM or container in Proxmox VE.
2. Go to Backup.
3. Click Backup now.
4. Select the PBS storage ID you created.
5. Choose the backup mode and compression settings.
6. Start the backup and wait for it to complete.

After the backup completes, open the PBS web interface and confirm that a new vm/<id> or ct/<id> snapshot exists in your datastore.

Create a backup schedule

1. Open Datacenter.
2. Go to Backup.
3. Click Add.
4. Select the PBS storage.
5. Choose the VMs or containers to include.
6. Set the schedule and retention settings.
7. Save the job.

Keep retention in Proxmox VE unless you have a specific reason to prune manually in PBS.

Restore from PBS

To restore a VM or container:

1. Open the VM or container in Proxmox VE.
2. Go to Backup.
3. Select the PBS storage.
4. Select the snapshot.
5. Click Restore.

Restoring a VM or container can overwrite existing data. Review the restore target before confirming.

Optional: client-side encryption

Proxmox VE can use client-side encryption for PBS backups. If you enable it, the PBS server stores encrypted backup data and cannot restore it without your key.

Store the encryption key securely. If the key is lost, encrypted backups cannot be restored.

Troubleshooting

Storage cannot be added

• Check that port 8007 is reachable from the PVE node.
• Confirm the PBS server hostname resolves correctly.
• Confirm the fingerprint matches the PBS certificate.
• Check that the datastore name is typed exactly as provided.

Authentication fails

• Confirm the username includes the correct realm, for example customer@pbs.
• If using an API token, use user@realm!token-name as the username.
• Confirm the password field contains the API token secret, not the token name.

Backup starts but fails

• Check the PVE task log for the backup job.
• Check the PBS task log for the matching upload task.
• Confirm the datastore or namespace has enough free space.
• Confirm your PBS user or token has backup permissions for the datastore or namespace.