basforge

Search titles, text and the “If it doesn’t work” cases.

    RU

    Backups in Proxmox: a nightly vzdump job, retention and a restore check

    The built-in vzdump copies whole guests every night — disks and config — to a separate disk or a NAS, and a retention rule deletes the excess: 7 daily, 4 weekly, 6 monthly copies. VMs don’t stop, and the guest agent freezes the file system for the duration of the snapshot. A backup you’ve never restored from doesn’t count: the last step is a restore into a new VM.

    What you’ll end up with

    where         the nas-backup storage — a NAS over NFS, or a second host disk
    when          every day at 03:00, all guests
    how           snapshot mode, zstd compression, guests don't stop
    retention     7 daily, 4 weekly, 6 monthly copies
    notification  an email if the job fails
    checked       the VM restored into a new 901, booted, data in place

    A vzdump backup is a whole guest: all its disks and its config. It restores onto any Proxmox host — even a freshly installed one after the old one died. The host’s own configs (/etc/network/interfaces, storages, users) aren’t part of guest backups: it’s easier to reinstall the host (Installing Proxmox) and bring the guests back onto it.

    Steps

    1. Choose where backups go

      A backup on the same disk as the guests survives only a mistake in a guest, not the disk dying. So it goes somewhere else:

      • A NAS — Datacenter › Storage › Add › NFS (or SMB/CIFS), Content — VZDump backup file.
      • A second host disk — node › Disks › Directory › Create Directory, Content — VZDump backup file.

      How to connect a storage — Proxmox storage. The example below uses the NFS storage nas-backup:

      pvesm add nfs nas-backup --server 10.0.0.20 --export /volume1/proxmox --content backup
      pvesm status                       # nas-backup  nfs  active
    2. Create the job

      Datacenter › Backup › Add:

      Field Set to Why
      Storage nas-backup not the disk the guests are on
      Schedule 03:00 every day at 3 a.m.; the format is a systemd calendar: sat 02:00, mon..fri 22:30
      Selection mode All new guests get backed up automatically; exceptions — Exclude selected
      Mode Snapshot without stopping guests
      Compression ZSTD faster than gzip and lzo at comparable compression, uses several cores
      Notification errors an email or another notification if the job fails (Installing Proxmox, the notifications step)

      The Retention tab sets how many copies to keep (next step). The Note Template tab is the label on a copy, {{guestname}} by default: the backup list shows the guest’s name, not just its number.

      The job lands in /etc/pve/jobs.cfg:

      vzdump: backup-7f3a9c21-1d2e
              schedule 03:00
              all 1
              compress zstd
              enabled 1
              mode snapshot
              notes-template {{guestname}}
              prune-backups keep-daily=7,keep-monthly=6,keep-weekly=4
              storage nas-backup
    3. Set retention

      Retention: Keep Daily 7, Keep Weekly 4, Keep Monthly 6. How it’s counted:

      • The rules go in order: last, hourly, daily, weekly, monthly, yearly. Each keeps the latest copy for its period — a day, a week (Monday to Sunday), a month.
      • The next rule looks only at copies older than those the previous one already kept.
      • With daily backups that gives: the last 7 days, 4 more weeks before them and 6 more months before those — up to 17 copies per guest, history going back about 7 months.

      The excess is deleted after every job run. Mark a copy that must not be deleted — before an upgrade or a big change — as Protected in the storage’s backup list: retention rules leave it alone.

      Retention can also be set on the storage (Datacenter › Storage › Edit › Backup Retention), but the job’s rule takes precedence — keep it in one place, on the job.

    4. Exclude what doesn’t need backing up

      There’s no point copying a 2 TB media library VM disk every night — it’s backed up some other way or not at all. Clear the Backup checkbox on the VM disk (Hardware › disk › Edit), or do the same by command:

      qm set 101 --scsi1 local-lvm:vm-101-disk-1,backup=0

      Take the disk line for the command from qm config 101: backup=0 is appended to it, the rest stays as it was. On a container mount point — the same, backup=0.

    5. Run it by hand the first time

      In the job list — Run now. In the console, the same for one guest:

      vzdump 101 --storage nas-backup --mode snapshot --compress zstd

      At the bottom of the UI, in Tasks, a double click on the task opens its log. At the end there should be Finished Backup of VM 101 and Backup job finished successfully. If the VM’s guest agent is running, the log shows the file system freeze — issuing guest-agent 'fs-freeze' command and fs-thaw after the snapshot (Guest agent).

      The file appears on the storage under dump/:

      vzdump-qemu-101-2026_10_31-03_00_02.vma.zst     VM: disks and config
      vzdump-lxc-201-2026_10_31-03_01_15.tar.zst      container: root files and config
    6. Restore into a new VM

      Check the backup by restoring it — not over the working VM, but next to it, under a new number:

      qmrestore /mnt/pve/nas-backup/dump/vzdump-qemu-101-2026_10_31-03_00_02.vma.zst 901 \
        --storage local-lvm --unique 1
      qm set 901 --name web1-restore-test
      qm config 901 | grep net0          # net0: virtio=BC:24:11:…,bridge=vmbr0

      --unique 1 gives the copy new MAC addresses. The address inside the guest is the same, so disconnect the network until the check is done: in the UI, Disconnect on VM 901’s network card; in the console, append link_down=1 to the net0 line.

      Start it with qm start 901, log in through the console and look at the data: the database opens, the files are in place. Then delete it: qm destroy 901. A container restores the same way: pct restore 902 /mnt/pve/nas-backup/dump/vzdump-lxc-201-….tar.zst --storage local-lvm --unique 1.

    When to move to Proxmox Backup Server

    vzdump writes the whole guest every time: for a VM with a 50 GB disk the whole disk is read every night, and a new archive the size of its compressed data lands on the storage. Proxmox Backup Server (PBS) stores copies in chunks and identical chunks only once:

    • Deduplication. If a VM changes little in a day, seven daily copies take a little more than one: almost all chunks repeat.
    • Incrementals. While the VM runs, QEMU marks changed blocks (a dirty bitmap), and the next backup reads only those: minutes instead of an hour. After the VM stops the bitmap is lost, and the next backup reads the whole disk, but still transfers only new chunks.
    • Files from a backup can be pulled out one by one, without restoring the whole VM.
    • Verification. Verify jobs reread the chunks and check their checksums.

    PBS goes on a separate machine or at least on separate disks: a backup on the same hardware as the guests dies with it. Moving makes sense once there are more than a dozen guests or the disks are hundreds of gigabytes.

    If it doesn’t work

    The job fails: storage 'nas-backup' is not online

    Cause
    The NAS is asleep, off or unreachable over the network at backup time; Proxmox checks the storage before starting.
    Fix
    Align the NAS and backup schedules, and turn off disk sleep on the NAS for that window. Check from the host: pvesm status — the storage is active.

    The container log says mode failure - some volumes do not support snapshots, then trying 'suspend' mode instead

    Cause
    Snapshot mode for a container requires all its volumes to be on a storage with snapshots. A volume on a directory or a host directory (bind mount) gets in the way.
    Fix
    Keep container volumes on LVM-thin or ZFS. Mark a volume that doesn’t need backing up with backup=0 on the mount point.

    During the backup the VM is sluggish, and the database in it takes seconds to answer

    Cause
    In snapshot mode a guest write to a block not yet copied waits until that block goes to the backup. A slow NAS slows down writes in the VM.
    Fix
    Fleecing (since 8.2): on the job, Advanced › Fleecing Storage — the fast local local-lvm. Blocks are copied there first, and the guest doesn’t wait for the network.

    Old backups aren’t deleted, and the NAS runs out of space

    Cause
    The job has no retention set, and the storage has keep-all=1 — the “keep everything” rule.
    Fix
    Retention on the job: Keep Daily 7, Keep Weekly 4, Keep Monthly 6. The excess is deleted after the next run; right away — Prune Group on the storage.

    The VM can’t be started or changed: VM 101 is locked (backup)

    Cause
    The backup was cut off — the host rebooted or the NAS went down — and the lock stayed.
    Fix
    Check in Tasks at the bottom of the UI that no backup is running, and remove the lock: qm unlock 101, for a container pct unlock 201.

    After a restore the VM causes an address conflict with the original

    Cause
    The copy got the same MAC and the same address as the running VM.
    Fix
    Restore with --unique 1 — new MACs — and keep the network disconnected until checked: link_down=1 on net0.

    How to check

    pvesh get /cluster/backup --output-format yaml      # the job exists: schedule, storage, prune-backups
    pvesm list nas-backup --content backup              # copies of each guest

    The morning after the first night: in Datacenter › Backup the job shows Next Run for today, Tasks has a successful Backup Job task, and the storage has one copy per guest. A week later each guest has 7 copies in the list, not more: retention works. And most importantly — VM 901 from the backup booted, with our data in it.