Free weekly email: the week's new posts, videos and one tip from the books, every Sunday. Get it free →
Homelab the Right Way

Home › Posts

PBS Maintenance: Prune, GC, and Verify Jobs

Proxmox Backup Server requires three specific maintenance jobs to stay healthy. Learn how to schedule prune, garbage collection, and verify tasks to ensure data integrity and free up space.

· 3 min read · proxmoxbackuppbshomelabsysadmin

PBS Maintenance: Prune, GC, and Verify Jobs

Proxmox Backup Server (PBS) is designed to replace vzdump by splitting disks into chunks and storing each unique chunk only once. This approach means that after the initial full backup, subsequent nightly runs for a small daily change set take minutes rather than hours. However, this efficiency comes with a maintenance burden that many users overlook until space runs out or corruption is discovered.

The trap is assuming that PBS manages itself automatically. It does not. You must explicitly schedule three specific jobs on the datastore: prune, garbage collection, and verify. Without these, your backups will eventually become unmanageable in size or silently corrupt. The book emphasizes that while verification is necessary, it is not sufficient on its own; you need a complete maintenance routine to keep the system healthy.

Prune jobs: dropping old snapshots

Pruning is the process of removing old backup snapshots from the index. When you configure retention policies, such as keeping daily backups for seven days and weekly backups for four weeks, PBS needs to know when to stop tracking those older entries. If you do not set up prune jobs, the index grows indefinitely, and the datastore fills up with references to data that is no longer useful.

You must set the same keep-* numbers in your prune job configuration that you chose in your retention policy. For example, if you want to retain seven daily backups, the prune job should reflect that constraint. This job runs on a schedule to clean up the metadata, ensuring that the datastore does not waste space holding onto expired backup entries.

Garbage collection: freeing actual disk space

Pruning only removes the index entries; it does not free the actual data blocks on disk. That is where garbage collection (GC) comes in. GC scans the datastore and deletes chunks that are no longer referenced by any remaining snapshot. However, PBS protects recently deleted data with a grace period to prevent accidental loss during restoration windows. By default, this grace period is 24 hours and 5 minutes.

If you run prune but never run garbage collection, your datastore will appear full even though the index says there is plenty of space. The book advises scheduling garbage collection daily. You should expect that free space will lag behind pruning by about a day because GC waits for the grace period to expire before deleting chunks. This delay is intentional and ensures you can still restore backups created within the last 24 hours even after they have been pruned from the index.

Verify jobs: checking data integrity

Verification reads every chunk in the datastore and checks its hash against the stored metadata. This process detects silent corruption, such as bit rot on a hard drive, that might otherwise go unnoticed until you attempt a restore. Because verification is disk-heavy and can impact performance, it should be scheduled during a quiet time, such as early morning.

The recommended configuration for verify jobs is to run them weekly. You should enable the "skip verified" option, which prevents PBS from re-checking chunks that have already been validated within the current window. Additionally, set "re-verify after" to 30 days. This ensures that every chunk is checked at least once a month, balancing thoroughness with resource usage.

Why vzdump alone is not enough

While vzdump creates full or incremental copies of entire guests, PBS offers deduplication across guests and file-level restores from any backup directly through the Proxmox GUI. However, these advanced features rely on the integrity of the chunk store. If you skip maintenance, the chunk store degrades. Pruning without garbage collection wastes space. Garbage collection without pruning is inefficient. Verification without a schedule leaves corruption undetected.

The book notes that PBS also supports sync jobs to another PBS instance for off-site copies and namespaces for multi-cluster setups. It even allows host backups using proxmox-backup-client to back up plain directories like /etc. All these features depend on a healthy datastore, which is maintained exclusively through the three jobs described above.

Checklist

  • Schedule prune jobs with the same keep-* numbers as your retention policy
  • Run garbage collection daily and expect free space to lag pruning by one day
  • Configure weekly verify jobs with "skip verified" enabled and "re-verify after" set to 30 days
  • Ensure PBS runs on its own hardware or dedicated disks, not on the same pool as the host
  • Use a backup@pbs user with DatastoreBackup permissions for Proxmox nodes
  • Save the client-side encryption key outside the cluster immediately after setup
  • Back up the Proxmox hosts' /etc and /etc/pve using proxmox-backup-client

More articles