Proxmox VE provides the built-in vzdump tool for backing up VMs and LXC containers. The schedule is configured through the web interface or the CLI and supports flexible retention policies.

Backup modes

Mode	Description	Impact on VM	When to use
snapshot	Snapshot + backup on the fly	No downtime	Production VMs (KVM)
suspend	Freeze, backup, resume	Brief pause	Consistent backup
stop	Stop, backup, start	Full downtime	The most reliable option

Configuring the schedule via the web interface

Go to Datacenter → Backup → Add:

Node: select a node or All
Storage: specify PBS or local storage
Schedule: choose a time (e.g. 00:00 for a nightly backup)
Selection: All, Pool, or specific VMs
Mode: snapshot / suspend / stop
Retention: number of backups to keep

Configuring via CLI (vzdump)

# Manual backup of VM 100 to PBS
vzdump 100   --storage my-pbs   --mode snapshot   --compress zstd   --notes-template "{{guestname}} - {{node}}"

# Backup all VMs on the node
vzdump --all 1 --storage my-pbs --mode snapshot

# Backup to a local file
vzdump 100 --dumpdir /mnt/backup --mode stop

Retention Policy

PBS supports flexible control over the number of stored backups:

# Retention examples in /etc/vzdump.conf or job settings
# 7 daily + 4 weekly + 3 monthly
keep-daily 7
keep-weekly 4
keep-monthly 3

# Via API
pvesh set /cluster/backup/1   --keep-daily 7   --keep-weekly 4   --keep-monthly 3   --keep-yearly 1

Global vzdump configuration

# /etc/vzdump.conf
storage: my-pbs
mode: snapshot
compress: zstd
bwlimit: 0
ionice: 7
lockwait: 3
stopwait: 10
tmpdir: /var/tmp

Backup notifications: Proxmox VE 9 supports sending backup result notifications via email, Gotify, and ntfy. Configure this in Datacenter → Notifications.

Test your restores! Regularly verify that backups can actually be restored. An undetected backup problem is the same as having no backup at all.

Common vzdump errors and what they mean

Recurring backup jobs tend to hit the same handful of errors — here are the three most common ones and how to tell them apart. All three show up in the backup task output in the web interface (Datacenter → Tasks) or in the /var/log/vzdump/ log, so the first diagnostic step is always to read the exact error text, not just the task's exit code.

VM 100 qmp command 'guest-fsfreeze-freeze' failed - got timeout
ERROR: Backup of VM 100 failed - unable to open file '/var/tmp/vzdumptmp1024_100.tmp' - No space left on device
INFO: skipping vzdump.lock: unable to acquire lock - got timeout after 3 seconds

guest-fsfreeze-freeze failed: qemu-guest-agent is not responding or is not installed inside the VM, so suspend mode cannot freeze the filesystem. Install the agent and enable it in the VM settings: qm set 100 --agent 1.
No space left on device: the temporary directory (/var/tmp by default) is full. Set a separate tmpdir in /etc/vzdump.conf with enough free space.
unable to acquire lock: a previous backup job for the same VM is still running. Check active tasks with pvesh get /nodes/pve/tasks and either wait for it to finish or remove the stale lock manually.

In practice these three errors come in waves: right after a Proxmox upgrade, after moving the temporary file directory to a different partition, or after adding a new large VM to a shared schedule — check these spots first.

When vzdump is not the right tool

The built-in tool covers most scenarios, but a few cases call for a different approach — knowing where the boundaries are saves time chasing problems vzdump was never meant to solve.

Databases under heavy transaction load: snapshot mode does not guarantee application-level consistency — run a proper database dump (pg_dump, mysqldump) before or instead of vzdump.
An RPO measured in minutes: vzdump is a scheduled full copy, not continuous replication; a minute-level RPO needs ZFS replication between nodes.
Very large VMs over a slow link to PBS: the first full backup can take hours — plan a maintenance window in advance.

Verifying the backup result

A successful log entry does not mean the backup can actually be restored — verify it separately.

# Status of the latest backup tasks
pvesh get /nodes/pve/tasks --typefilter vzdump --limit 5

# List restore points in PBS
proxmox-backup-client snapshot list --repository pbs:backup-store

# Test restore into a temporary VM ID
qmrestore pbs:backup/vm/100/2025-03-15T01:00:00Z 999 --storage local-lvm
qm destroy 999 --purge

If the test restore completes without errors and VM 999 boots, the backup is usable; run this check monthly against real backups rather than trusting a green task status alone. See more on restoring in restoring a VM from backup.