DEV Community

Cover image for How to Test That Proxmox Backups Actually Restore
Mike Maiolo | Pontavia Consulting
Mike Maiolo | Pontavia Consulting

Posted on Edited on Originally published at pontaviaconsulting.com AI-assisted

How to Test That Proxmox Backups Actually Restore

Key takeaways

  • A successful backup job only proves an archive was written, not that the guest inside it will boot.
  • Restore to a spare VM ID with --unique 1 and unplug the network (link_down=1) before the first boot.
  • Wait a few minutes and check again: a guest that boots and then crashes is still a failed restore.
  • Destroy the test copy afterwards. Automate the routine, or it stops after the first time.

Why a green backup job is not proof

A backup job that finishes successfully tells you an archive was written. On Proxmox Backup Server, a verify job goes further and checks that the stored data is intact. Neither one tells you that the guest inside the archive will boot and stay up. The only way to know is to restore it somewhere safe and look. The Proxmox backup and restore documentation explains the restore commands used below.

What a restore test needs to prove

  • The backup restores completely, with enough disk space and time.
  • The restored guest boots and keeps running for a few minutes.
  • The test copy cannot reach your real network, so it cannot clash with the original (same IP address, same services, even outgoing email).
  • The copy is deleted afterwards, so test restores never pile up.

Testing a virtual machine by hand

1. Find a backup. Replace local with the storage that holds your backups.

pvesm list local --content backup
Enter fullscreen mode Exit fullscreen mode

2. Pick an unused VM ID such as 9100. Never restore onto the original ID: that overwrites the real guest.

3. Restore it as a new guest with a new MAC address. This example restores from a local vzdump archive:

qmrestore /var/lib/vz/dump/vzdump-qemu-100-2026_11_17-02_00_01.vma.zst 9100 --storage local-lvm --unique 1
Enter fullscreen mode Exit fullscreen mode

From Proxmox Backup Server, point at the backup instead:

qmrestore pbs:backup/vm/100/2026-11-17T02:00:01Z 9100 --storage local-lvm --unique 1
Enter fullscreen mode Exit fullscreen mode

4. Unplug the network before the first boot. Look at the network devices, then set each one with link_down=1, which is the same as pulling the cable. Keep the model and bridge you see in the config.

qm config 9100 | grep ^net
qm set 9100 --net0 virtio,bridge=vmbr0,link_down=1
qm set 9100 --onboot 0
Enter fullscreen mode Exit fullscreen mode

5. Start it and check it is alive. The agent check only works if the QEMU guest agent is installed and enabled for that guest.

qm start 9100
qm status 9100
qm guest cmd 9100 ping
Enter fullscreen mode Exit fullscreen mode

6. Wait a few minutes and check again. A guest that boots and then crashes is still a failed restore.

7. Clean up.

qm stop 9100
qm destroy 9100 --purge
Enter fullscreen mode Exit fullscreen mode

Testing a container

Containers work the same way with pct. The pct set command replaces the whole network device, so copy the name and bridge from the config first. See the pct manual for every option.

pct restore 9101 /var/lib/vz/dump/vzdump-lxc-105-2026_11_17-02_10_00.tar.zst --storage local-lvm --unique 1
pct config 9101 | grep ^net0
pct set 9101 --net0 name=eth0,bridge=vmbr0,link_down=1
pct start 9101
pct exec 9101 -- systemctl is-system-running
# ...wait a few minutes, check again, then:
pct stop 9101
pct destroy 9101 --purge
Enter fullscreen mode Exit fullscreen mode

Things that trip people up

  • Disk space. The restore needs room for the whole guest on the target storage.
  • Load. A large restore slows the node. Run it at a quiet hour.
  • Hardware dependencies. A guest that uses PCI passthrough or a USB device may not boot as a test copy. Test those configurations separately.
  • Encrypted backups. You need the key to restore them, so keep it somewhere other than the node being backed up.
  • Test different guests. Rotate through them so every important guest gets tested over time.

Doing it every night without remembering

Done by hand this is a few minutes per guest, which is why it usually stops after the first time. Pontavia's Backup Proof ($79) is an n8n workflow that runs the same idea nightly: it restores one backup to a throwaway copy with the network unplugged, checks it boots and stays up, then deletes it. You get a record of every restore that worked and an alert the night one does not, sent to Discord, Slack, ntfy or any webhook. It works for containers and VMs and runs in your own n8n.

If you want a quick look at your whole cluster first, the Proxmox Daily Health Report is free: offline nodes and storage, storage filling up, guests with no recent backup or in no backup job, old snapshots and failed backup jobs. It only reads.

Frequently asked questions

How often should I test Proxmox backup restores?

Test your most important guests at least monthly, and any time you change backup storage, retention or job settings. Rotating through different guests is better than testing the same one every time.

Does a Proxmox Backup Server verify job replace a restore test?

No. A verify job checks that the stored backup data is intact. It does not boot the guest, so it cannot tell you the guest will start or stay up.

Can I restore a backup next to the original guest?

Yes, if you use a new VM ID with --unique 1 and set link_down=1 on the network devices before the first boot, so the copy cannot clash with the original.

Do I need the QEMU guest agent to test a restore?

No. The agent only powers the qm guest cmd <id> ping check. Without it, check the guest on the console and confirm it stays running.


Originally published at pontaviaconsulting.com. More guides like this: https://pontaviaconsulting.com/guides.html.

Top comments (0)