Proxmox Backup: vzdump and Proxmox Backup Server

What Is vzdump?

vzdump is the backup utility shipped with every Proxmox VE installation. It runs from the command line, from a scheduled backup job, or with a single click in the web GUI, and it produces a complete backup of a virtual machine or LXC container without any extra software.

Think of vzdump as the tool that answers the first question any hypervisor has to answer honestly: if this host dies tonight, can the guests come back from something other than hope. It does not need a second server, an agent inside the guest, or a licence. It reads the VM’s disks (or the container’s filesystem) and writes an archive to a storage target you already have.

A vzdump backup of a VM is a single .vma file (optionally compressed); a container backup is a .tar archive, or a pxar-format backup when the target is Proxmox Backup Server. Every backup file follows a predictable name: vzdump-[type]-[vmid]-[timestamp].tar[.extension], for example vzdump-lxc-105-2026_08_09-02_00_11.tar, which makes it easy to spot which guest and which run a file belongs to just by looking at the storage directory.

Backup Modes: Snapshot, Suspend, Stop

vzdump supports three modes, and the mode is the single biggest decision in a backup job: it trades downtime against consistency risk.

Snapshot mode is the default and does the backup while the VM keeps running, using QEMU’s live block-copy mechanism to read a consistent point-in-time image of the disks without pausing the guest. If the QEMU guest agent is installed and enabled inside the VM, Proxmox calls guest-fsfreeze-freeze before the snapshot and guest-fsfreeze-thaw after, which flushes filesystem buffers from inside the guest for a cleaner result. For containers, snapshot mode relies on the underlying storage’s own snapshot capability (ZFS, LVM-thin, and similar), briefly suspending the container just long enough to take that storage snapshot before resuming it and archiving from the snapshot in the background.

Suspend mode pauses the VM first and then runs the same snapshot mechanism underneath. The Proxmox documentation is explicit that this exists mainly for compatibility with older configurations: it produces a longer downtime than snapshot mode without a meaningful improvement in data consistency, so snapshot mode is the recommended choice in virtually every case where suspend mode used to be reached for. For containers, suspend mode instead does two rsync passes — a first full copy while the container keeps running, then a brief suspend to rsync only what changed since the first pass — which keeps downtime short at the cost of needing extra temporary storage space.

Stop mode shuts the guest down cleanly, performs the backup against the now-static disk, and starts it back up. There is no chance of an in-flight write being caught mid-transaction, because nothing is writing. That guarantee comes at the cost of real downtime for the length of the backup, which is why stop mode is usually reserved for guests where a clean, verifiably-consistent backup matters more than uptime during the backup window — a domain controller or database server ahead of a risky change, for instance, rather than the nightly baseline.

Why Proxmox Backup Server Instead of Plain Storage?

Pointing vzdump at plain storage — a local disk, an NFS share, a CIFS share — works, and it is a completely valid backup target. Every run produces a new, self-contained archive. The trade-off is that each run is a full backup: a VM with a 200 GB disk produces something close to a 200 GB backup file every single time, whether one file changed or the whole disk did.

Proxmox Backup Server addresses exactly that. Think of PBS as a backup target that remembers what it has already seen: it splits every backup into content-addressed chunks, and if a chunk is byte-identical to one it already stored from a previous run — which is most of a VM’s disk, most nights — it just references the existing chunk instead of writing it again. The result is that backups after the first one are effectively incremental in storage cost, even though each one still represents a full, independently restorable point-in-time snapshot of the guest.

PBS is a separate application with its own ISO — it is not a feature you turn on inside Proxmox VE, and it does not have to live on the same box you are protecting. From the Proxmox VE side, it shows up as a storage type like any other: add it once with pvesm add pbs, point backup jobs at it, and vzdump handles the rest, using the pxar file archive format and block-level chunking against VM disks rather than the plain tar/vma format it uses for non-PBS targets.

Why Backup Strategy Actually Matters Here

A snapshot is not a backup. It is easy to conflate the two on Proxmox because both live in the same GUI menu, but a ZFS or LVM-thin snapshot depends on the same underlying storage as the live disk — if that storage fails, the snapshot fails with it. A vzdump backup, by contrast, is a separate file on separate storage (ideally on a separate host), which is the only thing that survives the primary storage disappearing entirely.

This matters most for the guests that are hardest to rebuild from scratch: a domain controller carrying SYSVOL and the AD database, a database server with data that cannot be regenerated, or any VM whose configuration took real time to get right. Retention policy is the other half of the same problem — a backup job with no pruning quietly fills its target storage until the job itself starts failing, usually noticed only when the next backup run errors out at 2 AM.

Backup Jobs and Scheduling

A one-off vzdump run is useful for a pre-change backup, but production protection comes from a backup job: a schedule, a guest selection, a storage target, and a retention policy, configured once under Datacenter → Backup in the GUI. Jobs are stored in /etc/pve/jobs.cfg, replicated across the cluster like the rest of the Proxmox config, and executed by the pvescheduler daemon — there is no separate cron entry to maintain by hand.

Each job’s schedule uses systemd calendar-event syntax (for example sun 02:00 for a weekly Sunday 2 AM run), and a job can target all guests, a specific pool, or an explicit list of VM/container IDs, on all cluster nodes or just one. A “repeat missed” option catches a job up if the host was offline at its scheduled time, and per-job retention settings override whatever default is set on the storage target itself.

# /etc/vzdump.conf — host-wide defaults applied when a job or
# command-line run does not override them explicitly

mode: snapshot
compress: zstd
storage: pbs-backup
prune-backups: keep-last=3,keep-daily=7,keep-weekly=4,keep-monthly=6
mailnotification: failure
stopwait: 10
lockwait: 180

Retention: prune-backups

Retention on both plain storage and PBS is governed by the same keep-* vocabulary: keep-last, keep-hourly, keep-daily, keep-weekly, keep-monthly, and keep-yearly. Each rule is evaluated in order and only claims backups that an earlier, more specific rule has not already claimed — so keep-daily=7 does not mean “the 7 most recent backups,” it means “one backup per day, for the 7 most recent days that keep-last didn’t already cover.” The default, if prune-backups is never set at all, is keep-all=1 — nothing gets pruned automatically, which is a reasonable-sounding default that will quietly fill a disk if backups run nightly and nobody ever revisits it.

# Keep the 3 most recent runs regardless of age, one per day for
# 13 days, and one per year for 9 years — applied to guest 777
vzdump 777 --prune-backups keep-last=3,keep-daily=13,keep-yearly=9

# Same idea, set as the storage-level default instead of per-run
pvesm set pbs-backup --prune-backups keep-last=3,keep-daily=7,keep-weekly=4,keep-monthly=6

On Proxmox Backup Server, pruning and garbage collection are two separate steps, and mixing them up is a common source of confusion. Pruning only deletes the metadata pointer to a snapshot — the chunks that snapshot referenced are not removed yet, because another surviving snapshot might still reference some of the same chunks. Garbage collection is the job that actually walks every remaining snapshot, marks every chunk still referenced by touching its access time, then sweeps and deletes any chunk that was not touched. A chunk gets roughly a 24-hour-5-minute grace period before it is eligible for sweeping, driven by the filesystem’s relatime behaviour, and PBS logs anything inside that window as a pending removal rather than deleting it outright. Neither GC nor pruning runs on a default schedule — both have to be explicitly configured on the datastore, in the GUI or with proxmox-backup-manager datastore update <name> --gc-schedule "sun 03:00" --prune-schedule "sun 04:00".

Setting Up a PBS Datastore and Attaching It to Proxmox VE

On the Proxmox Backup Server side, a datastore is created against a directory with enough inode headroom for PBS’s chunk namespace — the underlying filesystem needs to support at least 65,538 subdirectories in a single directory, which rules out ext3 and ext4 with the dir_nlink feature disabled. ext4 (with the feature enabled), XFS, and ZFS are all supported.

# On the PBS host: create a datastore backed by a mounted disk
proxmox-backup-manager datastore create store1 /backup/disk1/store1

# Set GC and prune schedules explicitly — neither has a default
proxmox-backup-manager datastore update store1 \
  --gc-schedule "sun 03:00" \
  --prune-schedule "sun 04:00"

On the Proxmox VE side, that datastore is added as a storage target of type pbs. A username with the realm suffix (@pbs) and, for a self-signed PBS certificate, its TLS fingerprint are both required:

# On the Proxmox VE host: register the PBS datastore as backup storage
pvesm add pbs pbs-backup \
  --server pbs.company.internal \
  --datastore store1 \
  --username backup@pbs \
  --fingerprint 11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF

# Confirm it registered and shows the expected type/content
pvesm status

Scripts / Commands

# Back up a single VM or container by ID, using the mode and storage
# defaults from /etc/vzdump.conf
vzdump 777

# Explicit mode, storage target, and compression for one guest
vzdump 777 --mode snapshot --storage local --compress zstd

# Back up every guest on this node, stop mode, notify on completion
vzdump --all --mode stop --mailto ops@company.internal

# Back up everything except two specific guests
vzdump --all --mode suspend --exclude 101,102

# Cap backup I/O so it doesn't starve production traffic (KiB/s)
vzdump 777 --bwlimit 51200

# List available backups on a storage target
pvesm list pbs-backup --content backup

# Restore a container from a vzdump archive as a new CT ID
pct restore 600 /mnt/backup/vzdump-lxc-777.tar

# Restore a VM from a vzdump archive as a new VM ID
qmrestore /mnt/backup/vzdump-qemu-888.vma 601

# List PBS-stored backups for a VM to get the exact volume ID to restore
pvesm list pbs-backup --vmid 888

# Restore using that volume ID, starting the VM immediately via live-restore
# while the rest of the disk data streams in behind it in the background
qmrestore <volid-from-previous-command> 601 --live-restore 1

# Trigger garbage collection on a PBS datastore manually
proxmox-backup-manager garbage-collection start store1

# Check PBS datastore usage and chunk counts
proxmox-backup-manager datastore list

Troubleshooting Cheat Sheet

Final Thoughts

vzdump is the part of Proxmox that most closely resembles insurance: unglamorous, easy to defer configuring properly, and the only thing that matters the day storage actually fails. The three modes are a genuine trade-off, not a formality — snapshot for almost everything, stop for the handful of guests where a perfectly clean backup is worth real downtime.

Proxmox Backup Server is not mandatory to have working backups, but it changes what “keep two weeks of nightly backups” costs in disk space, from roughly fourteen full copies to roughly one full copy plus thirteen days of changed blocks. For anything beyond a single homelab host with a small VM count, that difference is usually the deciding factor.