Backup jobs and Proxmox VE integration

Why this matters in production

The PVE → PBS integration is the most-used path in most Proxmox deployments. Misconfigurations here mean backups don’t run, run too late, or capture inconsistent data.

How backups work

sequenceDiagram
  participant PVE as PVE node
  participant QM as QEMU
  participant FS as Guest filesystem
  participant VZ as vzdump
  participant PBS as PBS

  VZ->>QM: snapshot VM
  QM->>FS: guest-fsfreeze (if guest agent)
  VZ->>QM: read block device
  QM-->>VZ: stream of blocks
  VZ->>PBS: backup stream (compressed, encrypted)
  PBS->>PBS: chunk + dedup + store
  VZ->>QM: resume VM

Key steps:

1. Snapshot the VM’s disks (storage-level if supported; otherwise stop).
2. Freeze the guest filesystem if the QEMU Guest Agent is installed (consistent backup).
3. Stream the disk data to PBS.
4. PBS chunks, dedups, encrypts, and stores the data.

Scheduling backups

GUI: Datacenter → Backup → Add. CLI on PVE:

vzdump --schedule '02:00' --storage pbs-main --all 1 --mode snapshot --mailto admin@example.com --notification-mode notification-system

Common options:

Backup modes

snapshot is the recommended default. stop is only for VMs that cannot be paused.

QEMU Guest Agent

The QEMU Guest Agent enables consistent guest-filesystem snapshots during backup:

• Install inside the VM: apt install qemu-guest-agent (Linux), or VirtIO drivers (Windows).
• Enable in PVE: VM → Options → Use QEMU Guest Agent → Yes.

Without the agent, snapshot mode takes a crash-consistent backup (the disk is captured as if the power was pulled). Filesystems may need to run fsck on restore.

Notifications

PBS and PVE both support a notification system. Configure it:

pvesh create /cluster/notifications/matchers/backup-failure --mode all --type filter --match-field type --match-value vzdump --invert-match 0

Or via GUI: Datacenter → Notifications → Matchers. Common targets: SMTP email, Gotify, webhook.

Monitoring

cat /var/log/pve/tasks/active 2>/dev/null || ls /var/log/pve/tasks/

pvesh get /nodes/localhost/vzdump --output-format yaml

A green backup status is necessary but not sufficient. Verify restore (covered in the next lesson).

Production considerations

Common mistakes

• Using stop mode for production VMs unnecessarily.
• Not installing the QEMU Guest Agent.
• Alerting only on failure (you also want to know about long successes — to confirm the system is working).

Key takeaways

• snapshot mode with QEMU Guest Agent is the production default.
• Schedule backups with care for I/O contention.
• Notification failure is silent; monitor it separately.

Knowledge check