Proxmox Backup Server 4: Setup and Upgrade Guide

Proxmox Backup Server 4 landed with meaningful improvements that matter in practice — faster chunk-based deduplication, a reworked sync job engine, and better integration with Proxmox VE 9. Whether you're setting up PBS for the first time or migrating a production PBS 3 instance, this guide walks you through every step without skipping the parts that actually break things.

What's New in Proxmox Backup Server 4

Before diving into the install, it's worth knowing what changed so you can decide which features to enable first.

Improved Deduplication and Compression

PBS 4 ships with updated chunk parameters and improved zstd compression defaults. In practice, backup repositories with lots of similar VM disk images (think cloned templates) see noticeably better dedup ratios compared to PBS 3. The on-disk format is still compatible, so migrations don't require re-uploading everything.

Sync Job Enhancements

Sync jobs in PBS 4 got a significant overhaul. You can now schedule pull-based sync jobs with bandwidth throttling, filter by namespace, and set retention policies that apply at sync time rather than after. This is huge for remote offsite backups where you don't want to ship snapshots you'll immediately prune.

Namespace Improvements

Namespaces (introduced in PBS 2) are now first-class citizens in the UI. You can set per-namespace permissions, quotas, and retention policies independently. For homelabs running multiple Proxmox VE nodes or separating production from test workloads, this eliminates the need to run multiple PBS instances.

Security and Token Management

API token management is cleaner in PBS 4, with token scopes now surfaced directly in the web UI. You'll also find improved audit logging for backup and restore operations — useful if you're running PBS in a shared environment.

---

Option A: Fresh PBS 4 Installation

If you're starting from scratch, this is the path to take.

Hardware Requirements

PBS is intentionally lightweight. A reasonable minimum:

• CPU: Any x86-64 with at least 2 cores
• RAM: 2 GB minimum, 4–8 GB recommended for large repos
• OS disk: 16 GB (SSD preferred)
• Backup storage: Whatever you need — ZFS, ext4, XFS all work

For ZFS-based backup storage, add ~1 GB RAM per TB of storage as a rule of thumb for the ARC cache.

Download and Boot the Installer

Grab the ISO from the official Proxmox downloads page. Write it to a USB drive:

# On Linux
dd if=proxmox-backup-server_4.x-x_amd64.iso of=/dev/sdX bs=1M status=progress

Boot from the USB. The installer is identical in style to Proxmox VE — graphical, straightforward, no surprises.

Installation Steps

1. Accept the EULA
2. Select your target disk (the OS disk, not your backup storage)
3. Set locale, timezone, and keyboard layout
4. Enter a root password and email address for alerts
5. Configure the management network (static IP strongly recommended)
6. Review and confirm — installation takes 5–10 minutes

After reboot, PBS is accessible at https://your-ip:8007.

First Login and Initial Configuration

Log in with root and your password. The first thing to do is create a datastore — PBS's term for a backup repository directory.

Administration → Datastores → Add Datastore

Point it at your backup storage mount point, e.g., /mnt/backup-pool. If you're using ZFS, create a dataset first:

zfs create rpool/backup

Then use /rpool/backup as the datastore path.

Adding a Garbage Collection Schedule

Garbage collection (GC) reclaims space from deleted chunks. Set a schedule so it runs automatically:

Datastores → [your datastore] → GC → Edit Schedule

Daily at off-peak hours (e.g., 0 2 * * *) is a reasonable default. Without scheduled GC, disk space won't be reclaimed after pruning.

---

Option B: Migrating from PBS 3 to PBS 4

Migrating in-place is the cleanest approach and avoids re-uploading backup data. The PBS 3 → 4 upgrade path uses the standard Debian package upgrade mechanism.

Pre-Migration Checklist

Before you touch anything:

• Note your current PBS version (pbs-manager --version)
• Record all datastore paths, user/token permissions, and sync job configs (screenshot or export)
• Verify all your PVE nodes can reach the PBS instance by IP (so a hostname change doesn't break things)
• Snapshot or image your PBS OS disk if running virtualized — gives you a rollback point
• Confirm no backups are actively running (Administration → Tasks)

Upgrade Procedure

SSH into your PBS host as root.

Step 1: Update your apt sources to point at PBS 4 repositories.

Edit /etc/apt/sources.list.d/pbs-enterprise.list (or the no-subscription equivalent):

# No-subscription repo (homelab)
echo "deb http://download.proxmox.com/debian/pbs bookworm pbs-no-subscription" \
  > /etc/apt/sources.list.d/pbs-no-subscription.list

If you're on an older Debian base (bullseye), check whether PBS 4 requires bookworm — it does. In that case you'll need to upgrade the Debian base first, which is a larger operation. PBS 4 is based on Debian 12 Bookworm.

Step 2: Update the package list and perform the upgrade.

apt update
apt full-upgrade

Expect this to pull in updated proxmox-backup-server, proxmox-backup-client, and libpbs packages. Review the package list before confirming — you shouldn't see anything unexpected.

Step 3: Reboot.

systemctl reboot

Step 4: After reboot, verify the version:

pbs-manager --version
# proxmox-backup-manager x.x.x

Log into the web UI and confirm all your datastores, users, and sync jobs are intact.

Post-Upgrade Datastore Verification

Run a verify job on each datastore to confirm chunk integrity after the upgrade:

Datastores → [your datastore] → Verify → Verify All Snapshots

This takes time proportional to repository size but is worth doing once after a major upgrade. Any corrupted chunks will surface here rather than at restore time.

---

Connecting Proxmox VE Nodes to PBS 4

Once PBS 4 is running, you need to add it as a storage target in each Proxmox VE node.

Add PBS as Storage in PVE

In the Proxmox VE web UI:

Datacenter → Storage → Add → Proxmox Backup Server

Fill in:

• ID: A friendly name (e.g., pbs-main)
• Server: PBS IP or hostname
• Username: user@pbs (create a dedicated backup user — don't use root)
• Password or API Token: Token-based auth is preferred
• Datastore: The datastore name you created
• Fingerprint: Copy from PBS under Administration → Certificates

Creating a Dedicated Backup User and Token

In PBS:

Configuration → User Management → Add

Create a user like pve-backup@pbs. Then assign it the DatastoreBackup role on your datastore:

Datastores → [datastore] → Permissions → Add → User Permission

Then create an API token for this user:

Configuration → API Token → Add

Use the token secret in PVE instead of a password. Tokens can be revoked independently and don't expire when the user changes their password.

---

Configuring Backup Jobs in Proxmox VE

With PBS added as storage, set up scheduled backup jobs.

Create a Backup Job

Datacenter → Backup → Add

Key settings:

• Storage: Select your PBS storage ID
• Schedule: 0 2 * * * for daily at 2 AM
• Mode: Snapshot (preferred for running VMs), Suspend, or Stop
• Compression: zstd — best balance of speed and ratio
• Encryption: Enable and save your encryption key somewhere safe
• VMs/Containers: Select all, or pick specific IDs

Retention Policy

Set a retention policy under the backup job or directly on the PBS datastore:

Keep Last: 3 Keep Daily: 7 Keep Weekly: 4 Keep Monthly: 3

This keeps recent snapshots dense and older ones sparse — a standard approach that balances recovery granularity against storage consumption.

---

Setting Up Sync Jobs for Offsite Backup

PBS 4's improved sync engine makes it practical to maintain an offsite copy.

Pull-Based Sync (Recommended)

The destination PBS pulls from the source. This is safer — the offsite PBS has read-only access to the source, so a compromise of the offsite box can't delete your primary backups.

On the destination PBS:

Configuration → Remotes → Add

Add the source PBS as a remote with a user that has DatastoreAudit + DatastoreRead permissions on the source datastore.

Then:

Datastores → [destination datastore] → Sync Jobs → Add

Configure:

• Remote: The remote you just added
• Remote Datastore: Source datastore name
• Schedule: How often to sync
• Remove Vanished: Enable if you want the destination to mirror pruning from the source
• Bandwidth Limit: Set this if syncing over a WAN link

Namespace-Aware Sync

If you're using namespaces to separate workloads in PBS 4, you can sync a specific namespace rather than an entire datastore:

Sync Jobs → Remote Namespace: prod/ Local Namespace: offsite-prod/

This lets you maintain separate retention policies for what you sync offsite versus what stays local.

---

Monitoring and Alerting

Built-In Task Log

PBS logs every backup, verify, prune, and sync operation under Administration → Tasks. Failed tasks are highlighted — check this regularly or set up email notifications.

Email Notifications

Configure SMTP under Configuration → Notifications (PBS 4 uses the same notification framework as PVE 8+). You can route backup failure alerts to email or other endpoints.

Integrating with Prometheus

PBS exposes a metrics endpoint. If you're already running Prometheus + Grafana for your PVE cluster, add PBS as a scrape target:

# prometheus.yml
scrape_configs:
  - job_name: 'proxmox-backup-server'
    static_configs:
      - targets: ['your-pbs-ip:8007']
    scheme: https
    tls_config:
      insecure_skip_verify: true
    metrics_path: '/metrics'
    bearer_token: 'your-api-token'

The PBS Grafana dashboard (available on grafana.com) gives you dedup ratio trends, task duration, and storage utilization at a glance.

---

Common Issues and Fixes

Backup Fails with "permission denied" on Datastore

Almost always a user/token permission issue. Verify the PVE backup user has DatastoreBackup role on the correct datastore in PBS. Double-check the namespace if you're using one.

Fingerprint Mismatch After Certificate Renewal

If you renew the PBS TLS certificate, you need to update the fingerprint in every PVE storage config:

# On PBS, get the new fingerprint
openssl x509 -noout -fingerprint -sha256 \
  -in /etc/proxmox-backup/proxy.pem | cut -d= -f2

Update it in PVE under Datacenter → Storage → [PBS storage] → Edit.

GC Not Reclaiming Space After Prune

Prune marks chunks as unused but GC does the actual deletion. If GC isn't scheduled, space doesn't come back. Run it manually:

proxmox-backup-manager garbage-collection start [datastore-name]

Sync Job Fails with "chunk not found"

This can happen if a GC runs on the source while a sync is in progress. Add a small bandwidth limit or schedule sync jobs to not overlap with GC windows.

---

Conclusion

Proxmox Backup Server 4 is a meaningful upgrade — especially if you care about sync job flexibility, namespace organization, or squeezing better dedup ratios out of your backup storage. The migration from PBS 3 is low-risk if you follow the pre-migration checklist and run a verify job afterward.

For most homelab and small-business setups, the sweet spot is a dedicated PBS VM or bare-metal box with ZFS storage, pull-based sync to an offsite or second local machine, and daily backup jobs with a sensible retention policy. That combination gives you fast local restores, offsite protection, and automatic space management — without paying for a cloud backup subscription.

Once you have the basics running, consider layering in Prometheus metrics and Grafana dashboards so backup health is visible at a glance alongside the rest of your infrastructure.