PBS setup & datastore layout for multiple hosts

Introduction

Proxmox Backup Server provides centralized, deduplicated backup storage for Proxmox VE nodes, Linux clients, virtual machines, containers, and host backups. In this tutorial, you will complete the initial Proxmox Backup Server setup, create a PBS datastore on a separate disk, configure updates and SMTP notifications, and organize backups from multiple hosts with datastore namespaces instead of manual folders or multiple small datastores. The resulting Proxmox PBS layout also prepares your environment for later Proxmox backup restore tasks, including VM backup restore, file-level restore, granular restore, and data recovery Proxmox workflows.

Target audience: Intermediate system administrators.
Estimated completion time: 45 to 75 minutes.
End goal: By the end of this tutorial, you will have a Proxmox Backup Server datastore on dedicated storage, update repositories configured, email notifications enabled, and per-host namespace access controlled with ACLs.

Prerequisites

Before you begin, make sure you have the following:

• Proxmox Backup Server 4.x installed and reachable through the web interface at https://<PBS_HOSTNAME_OR_IP>:8007.
• Root or equivalent administrative access to the Proxmox Backup Server host.
• One separate disk for backup storage, identified as <DATA_DISK>, for example sdb or nvme1n1.
• Network connectivity from each Proxmox VE host or backup client to the PBS host on TCP port 8007.
• SMTP server details for notifications, including host, port, sender address, authentication user, and password or app password.
• One or more Proxmox VE hosts or backup clients that will use the PBS datastore.

This tutorial uses these placeholders:

• <PBS_HOSTNAME_OR_IP>: DNS name or IP address of the Proxmox Backup Server.
• <DATA_DISK>: Disk name without /dev/, for example sdb.
• <DATA_PARTITION>: Partition path, for example /dev/sdb1.
• <DATASTORE_NAME>: Datastore name, for example main-backup.
• <NAMESPACE_NAME>: Namespace name for one host or client, for example pve-node-01.
• <PBS_USER>: PBS user name, for example pve-node-01.
• <TOKEN_NAME>: API token name, for example backup.
• <TOKEN_SECRET>: API token secret generated by PBS.
• <STORAGE_ID>: Proxmox VE storage ID, for example pbs-main.

Step 1: Confirm the PBS Version and Disk Layout

Log in to the Proxmox Backup Server shell as root.

Check the installed PBS version:

proxmox-backup-manager versions

Expected result: The command prints the installed Proxmox Backup Server package versions.

List local disks:

lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS,MODEL

Expected result: You can identify the system disk and the separate storage disk. Do not use the disk that contains the PBS operating system.

Step 2: Configure the No-Subscription Repository

A fresh PBS installation usually enables the enterprise repository. Use it only when you have an active Proxmox subscription. For a lab, evaluation, or non-production environment without a subscription, disable the enterprise repository and enable the PBS no-subscription repository.

Open the enterprise repository file:

nano /etc/apt/sources.list.d/pbs-enterprise.sources

Set the enterprise repository to disabled by adding:

Enabled: false

Expected result: APT no longer tries to use the subscription-only repository.

Create or edit the Proxmox repository file:

nano /etc/apt/sources.list.d/proxmox.sources

Add the PBS no-subscription repository for Debian 13 Trixie based PBS 4.x installations:

Types: deb
URIs: http://download.proxmox.com/debian/pbs
Suites: trixie
Components: pbs-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg

Update package metadata:

apt update

Expected result: APT refreshes package indexes without 401 Unauthorized errors from enterprise.proxmox.com.

Upgrade installed packages:

apt full-upgrade

Expected result: PBS installs available updates from the configured repositories. Reboot if the upgrade installs a new kernel or critical system packages.

reboot

Step 3: Prepare a Separate Disk for the Datastore

PBS stores datastore data inside a directory on a supported Linux file system. Use ext4, xfs, or zfs for datastore storage. Choose one of the following storage layouts.

Option A: Create a Directory Datastore on XFS or ext4

Use this option for a simple single-disk datastore. XFS is a good default for large backup datasets. ext4 is also supported when it uses normal directory link settings.

Clear old signatures from the disk:

apt install parted
wipefs -a /dev/<DATA_DISK>

Create a new GPT partition table and one partition:

parted -s /dev/<DATA_DISK> \
  mklabel gpt \
  mkpart primary 1MiB 100%

Expected result: The disk has one new partition.

Refresh the kernel partition table:

partprobe /dev/<DATA_DISK>

Format the partition with XFS:

mkfs.xfs -f <DATA_PARTITION>

Use ext4 instead of XFS only when that is your local standard:

mkfs.ext4 -F <DATA_PARTITION>

Create the mount point:

mkdir -p /mnt/datastore/<DATASTORE_NAME>

Get the partition UUID:

blkid <DATA_PARTITION>

Expected output:

<DATA_PARTITION>: UUID="<FILESYSTEM_UUID>" BLOCK_SIZE="4096" TYPE="xfs"

Add the mount to /etc/fstab:

nano /etc/fstab

For XFS, add this line:

UUID=<FILESYSTEM_UUID> /mnt/datastore/<DATASTORE_NAME> xfs defaults,noatime 0 2

For ext4, add this line:

UUID=<FILESYSTEM_UUID> /mnt/datastore/<DATASTORE_NAME> ext4 defaults,noatime 0 2

Mount the datastore path:

systemctl daemon-reload
mount -a

Verify the mount:

df -h /mnt/datastore/<DATASTORE_NAME>

Expected result: The command shows the new disk mounted at /mnt/datastore/<DATASTORE_NAME>.

Option B: Create a Datastore on LVM

Use this option when you want logical volume management for the datastore disk.

Clear old signatures from the disk:

wipefs -a /dev/<DATA_DISK>

Create a physical volume, volume group, and logical volume:

pvcreate /dev/<DATA_DISK>
vgcreate pbs-vg /dev/<DATA_DISK>
lvcreate -n <DATASTORE_NAME> -l 100%FREE pbs-vg

Expected result: LVM creates /dev/pbs-vg/<DATASTORE_NAME>.

Format the logical volume with XFS:

mkfs.xfs -f /dev/pbs-vg/<DATASTORE_NAME>

Create the mount point:

mkdir -p /mnt/datastore/<DATASTORE_NAME>

Add the mount to /etc/fstab:

nano /etc/fstab

Add this line:

/dev/pbs-vg/<DATASTORE_NAME> /mnt/datastore/<DATASTORE_NAME> xfs defaults,noatime 0 2

Mount the datastore path:

mount -a

Verify the mount:

df -h /mnt/datastore/<DATASTORE_NAME>

Expected result: The logical volume is mounted at /mnt/datastore/<DATASTORE_NAME>.

Option C: Create a ZFS Pool and Datastore

Use this option when you need ZFS features such as checksumming, snapshots, compression, mirrors, or RAIDZ. ZFS is best used with direct disk access, not on top of hardware RAID that hides disk health from the operating system.

Clear old signatures from the disk:

wipefs -a /dev/<DATA_DISK>

Create a single-disk ZFS pool and add it as a PBS datastore:

proxmox-backup-manager disk zpool create <DATASTORE_NAME> \
  --devices <DATA_DISK> \
  --raidlevel single \
  --compression lz4 \
  --add-datastore true

Expected result: PBS creates a ZFS pool and registers a datastore with the same name.

Verify the pool:

zpool status <DATASTORE_NAME>

Expected result: The pool is online and the disk appears under it.

If you used this ZFS option with --add-datastore true, skip Step 4 and continue with Step 5.

Step 4: Create the PBS Datastore

Set ownership on the datastore directory for PBS backup services:

chown backup:backup /mnt/datastore/<DATASTORE_NAME>
chmod 750 /mnt/datastore/<DATASTORE_NAME>

Create the datastore configuration:

proxmox-backup-manager datastore create \
  <DATASTORE_NAME> \
  /mnt/datastore/<DATASTORE_NAME>

Expected result: PBS registers the directory as a datastore.

List datastores:

proxmox-backup-manager datastore list

Expected result: <DATASTORE_NAME> appears in the datastore list.

Show datastore details:

proxmox-backup-manager datastore show <DATASTORE_NAME>

Expected result: PBS shows the datastore path and current datastore options.

Step 5: Configure Prune, Garbage Collection, and Verification

Configure retention and garbage collection after creating the datastore. Prune removes expired backup indexes according to retention rules. Garbage collection removes unreferenced chunks after prune makes them unused.

Configure basic retention, daily prune, garbage collection, and verification for new backups:

proxmox-backup-manager datastore update <DATASTORE_NAME> \
  --gc-schedule 'Sun 03:00' \
  --verify-new true

proxmox-backup-manager prune-job create prune-<DATASTORE_NAME> \
  --store <DATASTORE_NAME> \
  --schedule daily \
  --keep-daily 7 \
  --keep-weekly 4 \
  --keep-monthly 6 \
  --comment 'Default retention for <DATASTORE_NAME>'

Expected result: PBS stores the datastore retention policy and schedules cleanup tasks.

Show the updated datastore configuration:

proxmox-backup-manager datastore show <DATASTORE_NAME>

Expected result: The output includes prune, garbage collection, and retention settings.

Step 6: Configure SMTP Notifications

Configure notifications before you depend on the backup server. This helps you catch failed backups, garbage collection errors, verification failures, and available package updates.

In the PBS web interface, open Configuration > Notifications.

Create a notification target:

1. Click Add.
2. Select SMTP.
3. Enter a target name, for example smtp-main.
4. Set the SMTP server, port, username, password, encryption mode, sender address, and recipient address.
5. Save the target.

Expected result: PBS stores the SMTP notification target.

Create a matcher for important PBS events:

1. Open Configuration > Notifications > Notification Matchers.
2. Create a matcher named admin-mail.
3. Select the SMTP target you created.
4. Match datastore, system, verification, garbage collection, and package update events.
5. Save the matcher.

Expected result: PBS routes matching notifications to the SMTP target.

Send a test notification from the notification target if the web interface offers the test action.

Expected result: The recipient mailbox receives a test email from PBS.

Step 7: Create Users and API Tokens for Backup Clients

Use a separate PBS user and API token for each Proxmox VE host, Proxmox VE cluster, or standalone backup client. This makes credentials easy to rotate and allows narrow permissions per namespace.

Create a PBS user for one host or client:

proxmox-backup-manager user create <PBS_USER>@pbs \
  --comment "Backup identity for <NAMESPACE_NAME>"

Expected result: PBS creates the user account. Set a password in the web interface under Configuration > Access Control > User Management if the user needs interactive login.

Generate an API tokenvia CLI:

proxmox-backup-manager user generate-token \
  <PBS_USER>@pbs \
  <TOKEN_NAME> \
  --comment "Backup token for <NAMESPACE_NAME>"

You can generate token in the web interface under Configuration > Access Control > API Token

Expected result: PBS prints the API token secret once. Copy it immediately and store it securely. You cannot retrieve the same secret later.

Step 8: Create a Namespace for Each Host or Client

PBS namespaces organize backup groups inside one datastore. Use a namespace per Proxmox VE host, Proxmox VE cluster, or standalone client instead of creating manual folders inside the datastore path.

Create a namespace for one host or client:

proxmox-backup-client namespace create <NAMESPACE_NAME> \
  --repository root@pam@localhost:<DATASTORE_NAME>

Expected result: PBS creates the namespace inside <DATASTORE_NAME>.

List namespaces:

proxmox-backup-client namespace list \
  --repository root@pam@localhost:<DATASTORE_NAME>

Expected result: The output includes <NAMESPACE_NAME>.

Create additional namespaces for other hosts or clients:

proxmox-backup-client namespace create pve-node-02 \
  --repository root@pam@localhost:<DATASTORE_NAME>
proxmox-backup-client namespace create linux-client-01 \
  --repository root@pam@localhost:<DATASTORE_NAME>

Expected result: Each host or client has a separate namespace in the same datastore.

Step 9: Grant Each Client Access Only to Its Namespace

Grant the API token access only to its own namespace path. The ACL path format is /datastore/<DATASTORE_NAME>/<NAMESPACE_NAME>.

Grant backup access to the token:

proxmox-backup-manager acl update \
  /datastore/<DATASTORE_NAME>/<NAMESPACE_NAME> \
  DatastoreBackup \
  --auth-id '<PBS_USER>@pbs'

proxmox-backup-manager acl update \
  /datastore/<DATASTORE_NAME>/<NAMESPACE_NAME> \
  DatastoreBackup \
  --auth-id '<PBS_USER>@pbs!<TOKEN_NAME>'

Expected result: The token can create backups and restore backups it owns in that namespace, but it cannot manage the whole datastore.

List ACL entries:

proxmox-backup-manager acl list

Expected result: The ACL list contains the token and namespace-specific path.

Step 10: Connect a Proxmox VE Host to the Namespace

On the Proxmox VE host, add PBS storage through the web interface or with pvesm.

To use the web interface, open Datacenter > Storage > Add > Proxmox Backup Server and enter these values:

• ID: <STORAGE_ID>.
• Server: <PBS_HOSTNAME_OR_IP>.
• Datastore: <DATASTORE_NAME>.
• Namespace: <NAMESPACE_NAME>.
• Username: <PBS_USER>@pbs!<TOKEN_NAME>.
• Password: <TOKEN_SECRET>.
• Fingerprint: PBS certificate fingerprint if the interface asks for it.

Expected result: Proxmox VE adds the PBS datastore namespace as backup storage.

To use the command line on the Proxmox VE host, add the storage:

pvesm add pbs <STORAGE_ID> \
  --server <PBS_HOSTNAME_OR_IP> \
  --datastore <DATASTORE_NAME> \
  --namespace <NAMESPACE_NAME> \
  --username '<PBS_USER>@pbs!<TOKEN_NAME>' \
  --password '<TOKEN_SECRET>'

Expected result: Proxmox VE creates a storage entry that points to the correct PBS namespace.

Check the storage status:

pvesm status

Expected result: <STORAGE_ID> appears as available.

Step 11: Create a Test VM Backup

On the Proxmox VE host, create a small test VM backup to the PBS storage. Replace <VMID> with a virtual machine or container ID. This confirms that Proxmox VE backup jobs can write to the namespace before you rely on the storage for disaster recovery Proxmox planning.

vzdump <VMID> \
  --storage <STORAGE_ID> \
  --mode snapshot

Expected result: The backup task completes successfully and uploads backup data to the namespace.

In the PBS web interface, open Datastore > <DATASTORE_NAME>. Select the namespace <NAMESPACE_NAME>.

Expected result: You can see the new backup group and backup snapshot inside the namespace.

Step 12: Confirm Backup Browsing and Restore Readiness

After the first backup finishes, confirm that PBS can browse VM backups inside the namespace. This is not a full restore test, but it verifies the organization that later supports restore from backup PBS operations, Proxmox PBS restore procedures, Proxmox backup restore tasks, and VM backup access from the correct namespace.

In the PBS web interface, open Datastore > <DATASTORE_NAME>, select <NAMESPACE_NAME>, and open the backup group created in Step 11.

Expected result: PBS shows the backup snapshots stored under the namespace for that host or client.

Select one backup snapshot and review the available restore actions.

Expected result: PBS shows restore options that can be used later for VM backup restore, restore from VM backup, and data restoration Proxmox procedures.

Verification

Verify that the datastore exists:

proxmox-backup-manager datastore list

Expected result: <DATASTORE_NAME> appears in the datastore list.

Verify the mount:

findmnt /mnt/datastore/<DATASTORE_NAME>

Expected result: The datastore path is mounted from the separate disk, logical volume, or ZFS pool.

Verify namespace access:

proxmox-backup-manager user permissions \
  '<PBS_USER>@pbs!<TOKEN_NAME>' \
  --path /datastore/<DATASTORE_NAME>/<NAMESPACE_NAME>

Expected result: The token has Datastore.Backup on its namespace path.

Verify that backups appear in the namespace:

proxmox-backup-client snapshots \
  --repository root@pam@localhost:<DATASTORE_NAME> \
  --ns <NAMESPACE_NAME>

Expected result: The command lists snapshots for the selected namespace.

Verify that you can browse VM backups in the namespace through the PBS web interface.

Expected result: You can open the backup group and see snapshots for the selected host or client. This confirms the namespace is ready for later file-level restore, granular restore, and restore individual files workflows.

Run a manual garbage collection status check:

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

Expected result: PBS prints garbage collection status for the datastore.

Why Use Namespaces Instead of Separate Datastores

Namespaces are the preferred organization mechanism when multiple hosts or clients share one physical backup storage pool.

They provide the following advantages:

• One shared chunk store for better deduplication across similar virtual machines and hosts.
• One place to configure retention, verification, and garbage collection policies.
• Clear separation in the PBS web interface without unsupported manual folders.
• Namespace-specific ACL paths for least-privilege client access.
• Easier scaling when you add more Proxmox VE hosts or Linux clients.
• Fewer datastore objects to monitor and maintain.

Use separate datastores when you need separate physical storage, different backup media, different performance tiers, different administrative ownership, or strict separation of retention and garbage collection schedules.

Reverting Changes

To remove one namespace ACL from a token, use the PBS web interface under Configuration > Access Control > Permissions and remove the ACL entry for /datastore/<DATASTORE_NAME>/<NAMESPACE_NAME>.

To delete an API token:

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

Expected result: PBS revokes the token.

To remove a PBS user:

proxmox-backup-manager user remove <PBS_USER>@pbs

Expected result: PBS removes the user account.

To remove a prune job:

proxmox-backup-manager prune-job remove prune-<DATASTORE_NAME>

Expected result: PBS removes the prune job.

To remove a datastore configuration without deleting backup data:

proxmox-backup-manager datastore remove <DATASTORE_NAME>

Expected result: PBS removes the datastore from its configuration, but the underlying directory remains on disk.

To remove the mount from an XFS, ext4, or LVM based datastore, edit /etc/fstab, remove the datastore line, and unmount the path:

umount /mnt/datastore/<DATASTORE_NAME>

Expected result: The datastore path is no longer mounted.

To remove a ZFS pool after deleting or migrating all required backups:

zpool export <DATASTORE_NAME>

Expected result: ZFS exports the pool. Import it later with zpool import <DATASTORE_NAME> if needed.

Troubleshooting

APT Shows 401 Unauthorized for the Enterprise Repository

Cause: The enterprise repository is enabled without a valid subscription.
Fix: Disable /etc/apt/sources.list.d/pbs-enterprise.sources with Enabled: false, add the no-subscription repository, and run apt update again.

The Datastore Creation Fails on an Unsupported File System

Cause: The datastore path is on a file system that does not support the required directory layout, or the file system was created with incompatible options.
Fix: Use xfs, ext4, or zfs. Avoid ext3 and avoid ext4 configurations with dir_nlink disabled.

The Datastore Mount Disappears After Reboot

Cause: /etc/fstab is missing, has the wrong UUID, or points to the wrong device.
Fix: Run blkid <DATA_PARTITION>, correct the UUID in /etc/fstab, then run mount -a.

A Client Can See the Wrong Namespace

Cause: The client storage configuration uses the wrong namespace or has ACLs at the datastore root.
Fix: Remove broad ACLs from /datastore/<DATASTORE_NAME>, grant permissions only on /datastore/<DATASTORE_NAME>/<NAMESPACE_NAME>, and confirm the Proxmox VE storage entry uses the correct namespace.

SMTP Test Email Does Not Arrive

Cause: SMTP authentication, TLS settings, sender policy, or firewall rules are incorrect.
Fix: Check the SMTP host, port, encryption mode, username, password, sender address, recipient address, and outbound network access from PBS.

Backups Work, but Garbage Collection Does Not Free Space Immediately

Cause: Garbage collection only removes chunks that are no longer referenced after prune has removed backup indexes. PBS also keeps safety windows to avoid deleting chunks that may still be in use.
Fix: Confirm prune settings, run or wait for garbage collection, and review datastore task logs.

Conclusion and Next Steps

You configured Proxmox Backup Server for initial production-style use: updates are routed through the correct repository, notifications use SMTP, backup storage lives on a separate disk, and multiple hosts are separated with namespaces and namespace-specific ACLs. This structure keeps one efficient PBS datastore while giving each Proxmox VE host or client its own controlled backup area.

As next steps, configure scheduled backup jobs on each Proxmox VE host, add verification jobs for stored backups, document your granular restore and restore individual files process, test file-level restore and full VM restores, and consider remote sync or tape backup for off-site protection.

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