Skip to main content
RunBook Academy

← All runbooks in Proxmox VE

medium riskservice affecting~30 min

Restore a VM from PBS backup

1 · Prerequisites

Confirm every item is in place before any state change.

  • Source VM exists in PBS datastore
  • Target storage has capacity for the restored VM disk
  • Target node has the required network bridges
  • Restore target VMID is free

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

  • · proxmox-backup-manager list <vm-id> shows available snapshots
  • · PBS datastore has enough free capacity

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

  1. 1Identify the snapshot to restore: proxmox-backup-manager list <vmid> --repo <pbs-name>
  2. 2qmrestore <backup-archive> <new-vmid> --storage <target-storage>
  3. 3Update VM network: qm set <new-vmid> --net0 virtio,bridge=<bridge>
  4. 4Boot the restored VM: qm start <new-vmid>

4 · Verification

Confirm the procedure actually fixed the problem.

  • ✓VM boots successfully
  • ✓VM has network connectivity (ping gateway)
  • ✓Application services start inside the VM
  • ✓Backup verification: pvesh get /nodes/<node>/qemu/<new-vmid>/status/current

5 · Rollback

If verification fails, undo the procedure in reverse order.

  • ↶qm stop <new-vmid>; qm destroy <new-vmid>
  • ↶If original was deleted, restore from another PBS snapshot if available

6 · Escalation

When the runbook isn't enough, contact:

  • · Application owner for service verification
  • · PBS admin if backup archive is corrupted

Restore a VM from PBS backup

This runbook covers restoring a VM from a PBS backup to a fresh VMID.

When to use

  • Original VM is lost or corrupted
  • Disaster recovery exercise
  • Migrating a VM between clusters

Prerequisites

  • PBS is reachable from the target node
  • The backup exists in the PBS datastore (proxmox-backup-manager list <vm-id>)
  • Target storage has enough free space for the restored VM
  • The target node has the network bridge the VM expects
  • The target VMID is not already in use

Pre-checks

# Substitute your own values before running:
VMID=100
PBS_NAME=pbs-main
TARGET_STORAGE=local-zfs

# List available backups
proxmox-backup-manager list "$VMID" --repo "$PBS_NAME"

# Check target storage capacity
pvesh get "/storage/$TARGET_STORAGE" --output-format json-pretty

Procedure

Step 1: Identify the snapshot

# Substitute your own values before running:
VMID=100
PBS_NAME=pbs-main

proxmox-backup-manager list "$VMID" --repo "$PBS_NAME"

Note the snapshot ID (e.g., host/pve-01/100/2026-08-01T00:00:00Z).

Step 2: Restore to a new VMID

# Substitute your own values before running:
BACKUP_ARCHIVE=pbs-main:backup/vzdump-qemu-100-2026_08_01-00_00_00.vma.zst
NEW_VMID=999
TARGET_STORAGE=local-zfs

qmrestore "$BACKUP_ARCHIVE" "$NEW_VMID" --storage "$TARGET_STORAGE"

Example:

qmrestore pbs-main:backup/vzdump-qemu-100-2026_08_01-00_00_00.vma.zst 999 --storage local-zfs

Step 3: Verify VM configuration

qm config 999
# Verify the restored VM config matches expectations

If the network bridge doesn’t exist:

qm set 999 --net0 virtio,bridge=vmbr0

Step 4: Boot the VM

qm start 999

Step 5: Verify from inside

  • SSH or console into the VM.
  • Verify network (ping gateway).
  • Verify application services start.

Verification checklist

  • VM boots
  • VM has network connectivity
  • Application services start
  • VM is reachable from external clients
  • Backup is now scheduled for the new VMID

Rollback

If the restored VM fails:

qm stop 999
qm destroy 999

Try restoring from a different (older) snapshot if the issue is recent data corruption.

Escalation

  • Application owner: for verification of service-level health
  • PBS admin: if backup archive fails to verify (chunk corruption)
  • Security team: if restored VM needs to be hardened before connecting to production

References

  1. qmrestore(1)
  2. PBS — Restore