Proxmox vzdump Explained: Backup Modes, Compression, and Hooks

Understanding vzdump

vzdump is the built-in backup tool for Proxmox VE. It creates consistent backups of VMs and LXC containers, storing them as compressed archive files. Understanding its modes, compression options, and hook system lets you build a backup strategy that balances speed, storage usage, and downtime.

Backup Modes: Snapshot vs Suspend vs Stop

vzdump offers three backup modes, each with different trade-offs:

• Snapshot – Creates a point-in-time snapshot while the VM keeps running. Zero downtime, but requires storage that supports snapshots (LVM-thin, ZFS, Ceph). This is the preferred mode for production.
• Suspend – Pauses the VM briefly to ensure filesystem consistency, takes the backup, then resumes. Minimal downtime (seconds to minutes depending on RAM size), good consistency.
• Stop – Shuts down the VM, backs it up, then restarts it. Guarantees perfect consistency at the cost of downtime. Use this for VMs where data integrity is critical and brief downtime is acceptable.

# Snapshot backup (no downtime)
vzdump 100 --mode snapshot --storage backup-nfs --compress zstd

# Suspend backup (brief pause)
vzdump 100 --mode suspend --storage backup-nfs --compress zstd

# Stop backup (VM shuts down)
vzdump 100 --mode stop --storage backup-nfs --compress zstd

Compression Options

Choosing the right compression algorithm significantly affects backup speed and file size:

• lzo – Fastest compression, largest file size. Good when CPU is the bottleneck and storage is cheap.
• gzip – Balanced compression ratio and speed. The traditional default.
• zstd – Best overall choice. Nearly as fast as lzo with compression ratios close to gzip. Recommended for most setups.

# Compare compression ratios (same 50GB VM):
# lzo:  backup size ~22GB, time ~8 min
# gzip: backup size ~16GB, time ~15 min
# zstd: backup size ~17GB, time ~9 min

# Use zstd for the best speed-to-size ratio
vzdump 100 --compress zstd --storage backup-nfs

Encryption

When backing up to Proxmox Backup Server (PBS), you can encrypt backups with a client-side encryption key. This protects your data even if the backup storage is compromised:

# Generate an encryption key
proxmox-backup-client key create /etc/pve/priv/backup-encryption.key

# Configure the PBS storage in Proxmox to use encryption
# In the web UI: Datacenter > Storage > Edit PBS storage > Encryption Key

# Or set it via CLI when adding storage
pvesm add pbs pbs-encrypted --server 10.10.10.50 \
    --datastore main --username backup@pbs \
    --encryption-key /etc/pve/priv/backup-encryption.key

Retention Policies

Control how many backups are kept using retention settings. You can set these per-storage or per-job:

# Keep last 7 daily, 4 weekly, 6 monthly backups
vzdump 100 --storage backup-nfs \
    --prune-backups keep-daily=7,keep-weekly=4,keep-monthly=6

# Or configure retention on the storage itself
pvesm set backup-nfs --prune-backups keep-daily=7,keep-weekly=4,keep-monthly=6

The older maxfiles parameter still works but is deprecated in favor of the more flexible prune-backups syntax. If you have existing jobs using maxfiles, consider migrating them.

Hook Scripts

vzdump supports hook scripts that run at specific phases of the backup process. This is powerful for tasks like notifying a monitoring system, quiescing a database, or syncing backups offsite:

#!/bin/bash
# /var/lib/vz/snippets/backup-hook.sh

# vzdump passes these environment variables:
# $1 = phase (job-start, job-end, job-abort, backup-start,
#              backup-end, backup-abort, log-end, pre-stop,
#              pre-restart, post-restart)
# VMID, VMTYPE, HOSTNAME, TARGET, LOGFILE

PHASE=$1

case "$PHASE" in
    job-start)
        echo "Backup job started at $(date)"
        ;;
    backup-start)
        echo "Starting backup of VM $VMID"
        # Quiesce a database before backup
        if [ "$VMID" = "101" ]; then
            ssh root@192.168.1.101 "mysql -e 'FLUSH TABLES WITH READ LOCK'"
        fi
        ;;
    backup-end)
        echo "Backup of VM $VMID completed"
        # Release database lock
        if [ "$VMID" = "101" ]; then
            ssh root@192.168.1.101 "mysql -e 'UNLOCK TABLES'"
        fi
        ;;
    job-end)
        echo "All backups finished at $(date)"
        # Sync to offsite storage
        rsync -avz /mnt/backup-nfs/ offsite:/backups/proxmox/
        ;;
    job-abort|backup-abort)
        echo "BACKUP FAILED for VM $VMID" | mail -s "Backup Alert" admin@example.com
        ;;
esac

# Register the hook script
# Upload to snippets storage, then reference in the backup job:
vzdump 100 101 102 --mode snapshot --compress zstd \
    --storage backup-nfs --script /var/lib/vz/snippets/backup-hook.sh

Exclude Patterns

For LXC container backups, you can exclude directories that do not need backing up (caches, temp files, logs):

# Create an exclude file
cat > /etc/vzdump/exclude.txt << 'EOF'
/tmp/*
/var/tmp/*
/var/cache/*
/var/log/*.gz
/var/log/*.1
EOF

# Use it during backup
vzdump 200 --mode snapshot --compress zstd \
    --exclude-path /etc/vzdump/exclude.txt

Performance Tips

• Use pigz for parallel gzip – If you must use gzip, install pigz and Proxmox will automatically use it for multi-threaded compression: apt install pigz
• Prefer zstd – It is multi-threaded by default and offers the best speed-to-ratio performance.
• Back up to fast storage – A slow NFS target will bottleneck the entire process. Use a dedicated backup NAS with SSDs or at minimum 10Gbps networking.
• Stagger backup schedules – Do not back up all VMs at the same time. Spread jobs across the night to avoid I/O contention.
• Monitor backup duration – If backups suddenly take longer, investigate storage performance. Mobile monitoring tools like ProxmoxR can help you track backup task completion and alert you when jobs run longer than expected.

# Schedule staggered backups via cron or the web UI
# Batch 1: Critical VMs at 1:00 AM
# Batch 2: Dev VMs at 3:00 AM
# Batch 3: Containers at 5:00 AM

With the right combination of backup mode, compression, retention, and scheduling, vzdump provides a reliable and efficient backup strategy for any Proxmox environment.