Back Up Proxmox VMs to a PBS Server

Proxmox Backup Server (PBS) is an enterprise-grade backup solution tightly integrated with Proxmox VE (PVE). It offers efficient, incremental, and…

Proxmox Backup Server (PBS) is an enterprise-grade backup solution tightly integrated with Proxmox VE (PVE). It offers efficient, incremental, and deduplicated backups for virtual machines, containers, and host-level data. This article details the process of integrating a PBS instance with a PVE cluster, configuring backup jobs, and verifying data integrity and performance.

Prerequisites and Initial Setup

Before configuring backups, ensure you have a running Proxmox VE cluster (version 7.x or 8.x recommended) and a dedicated Proxmox Backup Server instance (version 2.x or 3.x recommended). For optimal performance, PBS should reside on separate hardware or a dedicated VM with direct-attached storage or high-speed network storage (e.g., NVMe or enterprise SSDs in a ZFS pool).

PBS Storage Considerations

  • Disk Space: Dedupication efficiency depends on data similarity. For a typical environment with many similar VMs, plan for 1.5x to 2x the total active data size for a reasonable retention period (e.g., 30 days). For heterogeneous data, consider 3x or more.
  • I/O Performance: Backup and restore operations are I/O intensive. Avoid consumer-grade HDDs for the PBS datastore. ZFS on SSDs/NVMe with sufficient RAM (e.g., 1GB RAM per TB of ZFS storage) is highly recommended.
  • Network: A 10GbE network link between PVE hosts and the PBS is ideal for larger environments or frequent backups. For smaller setups, 1GbE may suffice, but monitor backup windows.

Adding PBS Storage to Proxmox VE

From the Proxmox VE web interface, navigate to Datacenter -> Storage -> Add -> Proxmox Backup Server. Fill in the following details:

  • ID: A descriptive name for the storage (e.g., pbs-main-dc).
  • Server: The IP address or hostname of your Proxmox Backup Server.
  • Username: A user on the PBS with backup privileges. The default root@pam is often used for simplicity in smaller setups, but creating a dedicated user with an API token is more secure for larger deployments (e.g., backupuser@pbs).
  • Password: The password for the specified user or the API token secret.
  • Datastore: The name of the datastore configured on your PBS (e.g., mydatastore).
  • Fingerprint (SHA256): The certificate fingerprint of the PBS. This enhances security by ensuring you're connecting to the correct server. Obtain it from your PBS web interface (Dashboard) or via SSH: proxmox-backup-manager cert info.
  • Max Backups: The number of backups to keep per VM on this storage. This is a local retention policy for PVE, but PBS has its own, more flexible retention policies. It's often set to 1 to defer retention to the PBS.
  • Compression: PBS handles compression on the server side. Keep this as zstd for best results.
  • Verify previous backups: Enable this to ensure data integrity during backup jobs. Recommended.
  • Prune previous backups: Enable this to prune old backups based on the "Max Backups" setting on the PVE side. This is generally less flexible than PBS's internal prune/gc jobs, so it's often disabled if PBS handles retention.

Click "Add". If successful, the PBS storage will appear under Datacenter -> Storage.

# Example API token creation on PBS (SSH into PBS)
# pbs-user-add backupuser@pbs
# pbs-token-add backupuser@pbs mypvetoken --privsep --datastore mydatastore --privileges DatastoreBackup

# Example on Proxmox VE (CLI)
# pvesm add pbs pbs-main-dc --server 192.168.1.10 --datastore mydatastore \
#   --username backupuser@pbs --password 'mysecrettoken' \
#   --fingerprint 'SHA256:AB:CD:EF:...' --maxfiles 1 --verify-new true

Configuring Backup Jobs

Once the PBS storage is integrated, you can create backup jobs. These jobs define which VMs/containers to back up, when, and to which storage.

Navigate to Datacenter -> Backup -> Add.

  • Node: Select "All" to back up VMs from all nodes, or specific nodes.
  • Storage: Choose your newly added PBS storage (e.g., pbs-main-dc).
  • Schedule: Define the backup schedule using cron syntax. Common examples:
    • daily: Every day at 00:00 (midnight).
    • Mon-Fri 01:00: Weekdays at 1 AM.
    • */30 * * * *: Every 30 minutes (not recommended for most backup types due to overhead).
    For daily backups, a common choice is 00:00 or 01:00.
  • Selection: Choose which VMs/containers to include.
    • All: All VMs/containers on the selected nodes.
    • All enabled: Only VMs/containers marked as "Start at boot".
    • All enabled (excluding suspended): Similar to above, but skips suspended VMs.
    • Selected VMs: Manually pick specific VMs/containers by ID.
    You can also use the "Exclude" field to specify VMs to skip (e.g., 100,102).
  • Compression: Leave this as zstd. PBS handles compression server-side.
  • Mode:
    • Snapshot: Creates a live snapshot of the VM before backup. The VM remains online. Recommended.
    • Suspend: Suspends the VM during backup. Minimal data change, but downtime.
    • Stop: Stops the VM during backup. Ensures data consistency but causes downtime.
    For most production systems, Snapshot is the preferred mode.
  • Email notification: Configure email alerts for job status.
  • Max workers: Number of parallel backup jobs per node. Default is usually sufficient.

Click "Create".

Initial Backup and Deduplication

After creating the backup job, you can trigger an immediate backup by selecting the job under Datacenter -> Backup and clicking "Run now". Observe the task log for progress and any errors.

PBS's strength lies in its block-level deduplication. If you back up 100 identical Linux VMs, the first VM will take up the full space. Subsequent identical VMs will only store unique blocks, resulting in significantly smaller backup sizes. This is highly efficient for VDI environments or clusters with many cloned VMs.

Verifying Backup Integrity and Performance

Manual Backup and Restore Test

Regularly perform test restores to ensure your backups are valid and can be recovered. This is critical for disaster recovery planning.

  1. Navigate to the PBS storage under Datacenter -> Storage -> [your_pbs_storage].
  2. Select a VM backup from the list.
  3. Click "Restore".
  4. Choose a target node and a new VM ID (e.g., 900). Do NOT overwrite production VMs unless intentionally testing an in-place recovery on a test system.
  5. Start the restore process. Once complete, power on the restored VM and verify its functionality.

Performance Benchmarking with proxmox-backup-client

To assess the throughput between your PVE host and the PBS, use the proxmox-backup-client tool directly from the PVE host's CLI. This bypasses the VM overhead and tests the raw network and disk I/O.

# First, ensure proxmox-backup-client is installed (usually it is by default on PVE)
# apt update && apt install proxmox-backup-client

# Set environment variables for PBS connection
# Replace with your PBS details
export PBS_SERVER=192.168.1.10
export PBS_DATASTORE=mydatastore
export PBS_PASSWORD='mysecretpassword' # Use API token secret or user password
export PBS_USER=backupuser@pbs
export PBS_FINGERPRINT='SHA256:AB:CD:EF:...' # Your PBS certificate fingerprint

# Run the benchmark. This writes a 1GB test file.
# The 'null' special device is used to simulate a data stream without actual disk I/O on the PVE host.
# For actual disk throughput, replace /dev/zero with a large file on your PVE's storage.
proxmox-backup-client benchmark write --repository ${PBS_SERVER}:${PBS_DATASTORE} \
  --user ${PBS_USER} --password ${PBS_PASSWORD} --fingerprint ${PBS_FINGERPRINT} \
  --output-format json --test-file /dev/zero --size 1G

# Example output (trimmed for brevity):
# {
#   "bytes": 1073741824,
#   "duration": 5.2345,
#   "rate_bytes_per_second": 205123456.78
# }
# This indicates a transfer rate of approx 200 MB/s.

# Test read performance (reads back the generated benchmark file)
proxmox-backup-client benchmark read --repository ${PBS_SERVER}:${PBS_DATASTORE} \
  --user ${PBS_USER} --password ${PBS_PASSWORD} --fingerprint ${PBS_FINGERPRINT} \
  --output-format json

# Example output (trimmed for brevity):
# {
#   "bytes": 1073741824,
#   "duration": 4.8765,
#   "rate_bytes_per_second": 220123456.78
# }

The benchmark results give a good indication of your backup infrastructure's peak throughput. Compare this to your expected backup window. For example, 200 MB/s is 720 GB/hour. If you have 5 TB of unique data, it will take roughly 7 hours to complete a full backup, assuming no network contention or PBS storage bottlenecks.

PBS Retention and Garbage Collection

While PVE has a "Max Backups" setting, the primary and more powerful retention policies are managed directly on the Proxmox Backup Server. These policies allow for granular control over how many backups are kept for daily, weekly, monthly, and yearly intervals. This is crucial for compliance and efficient storage usage.

From the PBS web interface, navigate to Datastore -> [your_datastore] -> Prune & GC.

Prune Jobs

Prune jobs remove old backup snapshots based on defined retention policies. Example policy (keep-last=7,keep-hourly=24,keep-daily=30,keep-weekly=8,keep-monthly=12,keep-yearly=5):

  • Keeps the last 7 backups regardless of age.
  • Keeps one hourly backup for the last 24 hours.
  • Keeps one daily backup for the last 30 days.
  • Keeps one weekly backup for the last 8 weeks.
  • Keeps one monthly backup for the last 12 months.
  • Keeps one yearly backup for the last 5 years.

Define a schedule (e.g., daily at 02:00) for prune jobs.

Garbage Collection (GC)

Garbage Collection reclaims space from pruned backups. After a prune job runs, the data blocks are marked as free but not immediately removed from disk. GC is an I/O intensive process that physically deletes these unreferenced blocks. Schedule GC jobs less frequently than prune jobs, typically weekly or bi-weekly during off-peak hours (e.g., Saturday 03:00).

# Example PBS CLI for adding a prune job (SSH into PBS)
# proxmox-backup-manager datastore prune add mydatastore --schedule "0 2 * * *" \
#   --ns backupuser@pbs --keep-last 7 --keep-hourly 24 --keep-daily 30 \
#   --keep-weekly 8 --keep-monthly 12 --keep-yearly 5

# Example PBS CLI for adding a GC job
# proxmox-backup-manager datastore gc add mydatastore --schedule "0 3 * * 6"

Common Pitfalls and Troubleshooting

  • Incorrect Fingerprint: The SHA256 fingerprint must match exactly. A mismatch will prevent connection. Double-check it from the PBS dashboard or proxmox-backup-manager cert info.
  • Firewall Issues: Ensure TCP port 8007 is open between your PVE hosts and the PBS. Both PVE and PBS have internal firewalls that might need adjustment.
  • Insufficient PBS Permissions: If using a dedicated PBS user, ensure it has the necessary DatastoreBackup privileges on the target datastore.
  • Network Saturation: Large initial backups can saturate a 1GbE link. Monitor network usage on both PVE and PBS during backup windows. Consider QoS or scheduling backups during off-peak hours.
  • PBS Disk I/O Bottleneck: If PBS disk I/O (iostat -x 1 or similar) is consistently high (e.g., >80% util) during backups/GC, your storage may be a bottleneck. Upgrade to faster disks or add more spindles.
  • Time Synchronization: Ensure PVE hosts and PBS are time-synchronized using NTP. Time discrepancies can lead to issues with certificates and backup integrity checks.
  • "Task ERROR: backup schedule 'monthly' (or similar) is not valid": This error occurs if you selected a specific schedule like 'monthly' but PBS prune policies expect a 'daily' prune tag or similar. Ensure consistency between your backup job schedule and your PBS prune policy tags, or simply use a generic 'daily' schedule for the PVE backup job and let PBS retention handle the long-term.

Back to the knowledge base · Ask the AI assistant