Proxmox Backup and Restore with Practical Examples

Intro

Proxmox Virtual Environment (VE) is an open-source platform for managing virtual machines and containers. Backups are essential for disaster recovery, testing, and migration. This guide provides practical examples for backing up and restoring VMs and containers using Proxmox's built-in tools.

We will cover version and environment inventory, safe configuration, verification, failure modes, recovery, and an operations checklist. Each section includes concrete commands, expected outputs, and failure signals. By the end, you will be able to schedule backups, restore them, and validate that your data is safe.

This guide assumes you have Proxmox VE 7.x or 8.x installed and access to the web UI or CLI with root privileges.

Version and Environment Inventory

Before making any changes, capture the current state of your Proxmox environment. This helps identify compatibility issues and provides a baseline for troubleshooting.

Check Proxmox version:

pveversion

Expected output example:

pve-manager/8.1.4/9e3c8c8c (running kernel: 6.5.11-6-pve)

If the command fails, ensure you have root access and the package is installed. Note the version because backup behavior and options may differ between major releases.

List VMs and containers:

qm list
pct list

Sample output:

      VMID NAME                 STATUS     MEM(MB)    BOOTDISK(GB) PID
       100 webserver            running    4096              32.00 12345
       101 database             stopped    8192              64.00 0

For containers, pct list shows similar information. Record the VMID, name, status, and disk size for your resources. This is the inventory you will use for backup selection.

Check storage configuration:

cat /etc/pve/storage.cfg

Look for backup-capable storage such as dir, nfs, or pbs (Proxmox Backup Server). The output will show storage definitions. Example:

dir: local
        path /var/lib/vz
        content backup,iso,vztmpl
        maxfiles 3

This shows that local storage can hold backups and keeps a maximum of 3 backup files per guest.

Prerequisites for backup:

• Enough free space on target storage. Check with df -h on the Proxmox host.
• Network connectivity if using remote storage like NFS or Proxmox Backup Server.
• For vzdump backups, no additional packages are needed; it is included.

Blast radius: These read-only commands do not alter system state. Safe to run anytime.

Verification: Confirm you can see all VMs/containers and that storage paths are valid. If a VM is missing from the list, check its configuration file in /etc/pve/qemu-server/ or /etc/pve/lxc/.

Safe Configuration Path

This section covers setting up backup jobs and storage properly. Always test backup configuration on a non-critical VM first.

Creating a backup storage directory (if using local dir storage):

The local storage often already exists. If you need a dedicated backup directory on a mounted disk, add it to /etc/pve/storage.cfg with a text editor or via the web UI.

Example adding an NFS mount for backups (assuming NFS server at 192.168.1.100 and export /backups):

First, create mount point and mount:

mkdir -p /mnt/backup-nfs
mount -t nfs 192.168.1.100:/backups /mnt/backup-nfs

To make it persistent, add to /etc/fstab:

192.168.1.100:/backups /mnt/backup-nfs nfs defaults 0 0

Then define storage in Proxmox by editing /etc/pve/storage.cfg:

nfs: backup-nfs
        path /mnt/backup-nfs
        server 192.168.1.100
        export /backups
        content backup
        maxfiles 7

After editing, verify storage is recognized:

pvesm status

Expected output includes backup-nfs with status active.

Scheduling a backup job

Proxmox uses vzdump for backups. You can schedule via cron or systemd timers. The web UI creates a cron entry in /etc/cron.d/vzdump. For CLI, create a cron job:

echo "0 2 * * * root vzdump 100 --mode snapshot --compress zstd --storage backup-nfs --notes-template '{{guestname}} daily backup'" > /etc/cron.d/vzdump-custom

This schedules a daily backup at 2 AM for VMID 100, using snapshot mode and zstd compression, storing on backup-nfs.

Test the backup manually first:

vzdump 100 --mode snapshot --compress zstd --storage backup-nfs --notes-template '{{guestname}} test'

Monitor output. A successful backup ends with:

INFO: Finished Backup of VM 100 (00:02:30)
INFO: Backup finished at 2025-03-12 02:03:45

Important options:

• --mode snapshot for online backup without downtime (requires QEMU guest agent for consistency in some cases).
• --mode suspend pauses VM during backup (shorter downtime but still interruption).
• --mode stop shuts down VM for consistent backup (longest downtime).
• --compress zstd or gzip or lzo or none.
• --storage must be a storage defined with content backup.

Blast radius: Test backup on one VM only. If misconfigured storage, backup fails but does not affect VM. Ensure storage has enough space to avoid filling disks.

Verification: After backup completes, list backup files:

ls -lh /mnt/backup-nfs/dump/

or use:

vzdump --list

You should see a .vma.zst or .tar.zst file for the VM.

Verification and Diagnostics

After creating backups, verify their integrity and restorability. A backup is only useful if it can be restored.

Check backup file integrity

Proxmox stores backups as VMA (virtual machine archive) files. You can verify with vma tool (from vma package):

vma verify /path/to/backup.vma.zst

This checks the archive structure. Expected output:

verify: backup file looks OK

If errors appear, the backup may be corrupted. Consider re-running the backup.

Test restore to a different VMID

Restoring to a new VMID ensures the backup is usable without affecting the original. Use qmrestore for VMs and pct restore for containers.

Example restore VM 100 backup to VMID 200:

qmrestore /mnt/backup-nfs/dump/vzdump-qemu-100-2025_03_12-02_00_00.vma.zst 200 --storage local-lvm

This creates a new VM with ID 200 on local-lvm storage. After restore, start the VM and check that it boots:

qm start 200
qm status 200

Expected status running.

For containers:

pct restore 200 /mnt/backup-nfs/dump/vzdump-lxc-101-2025_03_12-02_00_00.tar.zst --storage local-lvm

Verify data integrity inside VM

After restore, log into the VM (via console or SSH) and check critical files or databases. For example, if it is a web server, check that the web service is running and pages are served.

Logs and diagnostics

Check backup logs:

cat /var/log/vzdump/*.log

Look for warnings or errors. Common issues:

• Insufficient disk space: backup fails with No space left on device.
• Guest agent not running: snapshot mode may still work but filesystem may be inconsistent. Install qemu-guest-agent in VM.

Failure signal: If vma verify fails or restore produces a non-bootable VM, treat backup as invalid and troubleshoot original VM and backup settings.

Failure Modes and Recovery

Understand common failure modes and how to recover.

1. Backup fails due to not enough space

Symptom: vzdump error No space left on device or backup incomplete.

Recovery:

• Check target storage free space: df -h /mnt/backup-nfs.
• Remove old backups or increase storage capacity.
• Adjust maxfiles to keep fewer backups.
• Re-run backup.

2. Restore fails with "storage does not support content type 'images'"

Symptom: qmrestore error.

Cause: Target storage is not configured for VM images (only backup content).

Recovery:

• Use a storage that supports images, e.g., local-lvm or local.
• Or add images content to storage definition in /etc/pve/storage.cfg.

3. Backup completed but VM data inconsistent

Symptom: Restored VM has corrupted database or missing recent changes.

Cause: Snapshot mode without guest agent may not quiesce filesystem.

Recovery:

• Install and enable QEMU guest agent in the VM.
• Use --mode snapshot with --fleecing (in Proxmox 8) for better consistency.
• For databases, consider using application-level backup inside VM before vzdump.

4. Backup job not running at scheduled time

Symptom: No new backups appear.

Cause: Cron entry misconfigured or vzdump service not running.

Recovery:

• Check cron file /etc/cron.d/vzdump for correct syntax.
• Manually run the vzdump command to see errors.
• Check system logs: journalctl -u cron.

5. Proxmox host fails completely

Symptom: Hardware failure or corrupted OS.

Recovery:

• Reinstall Proxmox on new hardware.
• Restore backups from external storage.
• If using Proxmox Backup Server, attach it as storage and restore.
• Document VM configurations separately (or use qm config outputs stored offline).

Rollback: If a backup or restore causes issues, remove the problematic files or VMs, revert configuration changes, and retry with corrected parameters.

Common Pitfalls

Avoid these common mistakes:

• Not testing restores: Many assume backups work until disaster strikes. Schedule periodic restore tests (e.g., quarterly) to a test VMID.
• Using stop mode for critical VMs: This causes downtime. Use snapshot mode with guest agent for online backup.
• Storing backups on same disk as VMs: If disk fails, you lose both. Use separate physical storage or offsite/cloud.
• Ignoring retention: maxfiles not set leads to disk fill. Set appropriate retention and monitor.
• Not encrypting backups: Backups contain sensitive data. Use encrypted storage or add encryption via Proxmox Backup Server.
• Forgetting to include configuration: vzdump includes VM config by default, but if you manually copy disk images, you may miss config files. Always use vzdump or ensure you have /etc/pve/qemu-server/ and /etc/pve/lxc/ backed up.
• Assuming consistency without quiescing: For databases, use application-level dumps or freeze/thaw scripts in conjunction with vzdump.

Operations Checklist

Use this checklist to ensure reliable backups and restores. Assign a single owner for each item if in a team. Review frequency: monthly for backup health, quarterly for restore tests.

Verification for checklist: After each task, record output and compare with expected. If any check fails, open incident and resolve before next review.

Conclusion

Proxmox backup and restore are critical skills for any administrator. By following the practices in this guide, you can create reliable backups, test restores, and recover from failures with confidence.

Start with the inventory commands to understand your environment, configure backup storage and jobs safely, verify backups by restoring, and be prepared for common failure modes. Use the operations checklist to keep your backup strategy healthy.

Regular testing is the only way to ensure your backups will work when needed. Schedule restore drills, review backup logs, and keep documentation up to date. With Proxmox VE, you have powerful tools at your disposal—use them wisely.