## 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.
ItemCommand / ActionExpected ResultOwnerReview Frequency
Check Proxmox version and healthpveversion and pvecm statusVersion supported, no cluster errorsSystems Admin: Alex JohnsonMonthly
Verify backup storage availablepvesm statusAll backup storages activeSystems Admin: Alex JohnsonWeekly
Confirm backup jobs are configuredcat /etc/cron.d/vzdumpJob entries correctBackup Admin: Maria GarciaMonthly
Run manual test backupvzdump 100 --mode snapshot --storage backup-nfsBackup completes without errorsBackup Admin: Maria GarciaMonthly
Verify backup file integrityvma verify /path/to/backup"backup file looks OK"Backup Admin: Maria GarciaMonthly
Perform restore test to test VMIDqmrestore ... 999 --storage local-lvm then startVM boots and data intactDisaster Recovery Lead: Sam PatelQuarterly
Check backup disk usagedf -h /mnt/backup-nfsFree space > 20%Systems Admin: Alex JohnsonWeekly
Review and update backup policyDocument changes, adjust retentionPolicy currentIT Manager: Priya ShahQuarterly
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.