Proxmox VE: Backup-Fehler diagnostizieren und beheben

Warum Proxmox-Backups fehlschlagen

Das integrierte Tool vzdump sichert KVM-Gäste und LXC-Container konsistent – live per Snapshot oder offline per Stop/Suspend. Trotzdem treten Fehler auf: fehlender Speicherplatz, fehlender QEMU-Guest-Agent, fehlerhafte Hook-Skripte oder Storage-Probleme. Dieser Beitrag zeigt, wie Sie die Task-Logs lesen, die Backup-Modi verstehen und die häufigsten Ursachen beheben.

Backup-Modi und ihre Voraussetzungen

vzdump kennt drei Modi für KVM-VMs:

• snapshot (Standard): Live-Backup ohne Downtime. Setzt QEMU-Guest-Agent im Gast voraus, damit das Dateisystem eingefroren werden kann (fsfreeze). Ohne Agent wird der Snapshot inkonsistent (crash-consistent).
• suspend: VM wird kurz angehalten, Speicher auf Festplatte geschrieben, dann fortgesetzt. Konsistent, aber Downtime von Sekunden bis Minuten je nach RAM-Größe.
• stop: VM wird heruntergefahren, gesichert, wieder gestartet. Vollkonsistent, längste Downtime.

Für LXC-Container existiert nur der snapshot-Modus (nutzt LXC-Checkpointing).

Quelle: Proxmox VE Administration Guide, Kapitel 1.3 „Integrated Backup and Restore“ – vzdump erstellt konsistente Snapshots laufender Container und KVM-Gäste.

Task-Logs auswerten – der erste Diagnoseschritt

Jeder Backup-Job erzeugt einen Task-Eintrag. Fehlerhafte Jobs listen Sie so auf:

pvenode task list --errors --vmid 100

Den vollständigen Log eines Tasks (UPID) lesen Sie mit:

pvenode task log UPID:pve1:00010D94:001CA6EA:6124E1B9:vzdump:100:root@pam:

Im Log finden Sie Exit-Codes, Fehlermeldungen von vzdump, qemu-img oder Hook-Skripten sowie Storage-Meldungen.

Quelle: Proxmox VE Administration Guide, Abschnitt 3.11.2 „Task History“ – Task-Logs helfen bei fehlgeschlagenen Backup-Jobs.

Häufige Fehler und Lösungen

1. „No space left on device“

Ursache: Ziel-Storage (Directory, NFS, ZFS, Ceph) ist voll. vzdump bricht mit Exit-Code 28 ab.

Diagnose:

df -h /var/lib/vz/dump   # oder das jeweilige Backup-Storage

Lösung: Alte Backups löschen (vzdump --prune), Storage erweitern, Retention-Policy anpassen (maxfiles in Datacenter → Backup).

2. „Failed to freeze filesystem – QEMU guest agent not running“

Ursache: Snapshot-Modus ohne laufenden qemu-guest-agent im Gast. Der Snapshot wird nur crash-consistent.

Diagnose: Im Task-Log: INFO: guest agent not running, backup will be crash consistent.

Lösung: Im Gast installieren (apt install qemu-guest-agent / Windows: VirtIO-Treiber-ISO) und Dienst starten. In Proxmox: VM → Options → QEMU Guest Agent → Enabled setzen.

3. Hook-Skript schlägt fehl (Exit-Code ≠ 0)

Ursache: Ein konfiguriertes Hook-Skript (/etc/vzdump/hook-script.pl oder per Storage definiertes Skript) liefert Fehler zurück – z. B. Netzwerk nicht erreichbar bei Pre-Backup-Benachrichtigung.

Diagnose: Task-Log zeigt hook script failed with exit code X. Testen Sie das Skript manuell:

/etc/vzdump/hook-script.pl backup-start 100 /var/lib/vz/dump/vzdump-qemu-100.vma.zst

Lösung: Skript korrigieren, Berechtigungen prüfen (chmod +x), Timeouts erhöhen.

4. „VM is locked (backup)“ / Resource busy

Ursache: Ein weiterer Job (z. B. Replication, Migration, zweiter Backup-Job) hält den Lock auf der VM.

Diagnose: pvenode task list zeigt laufende Tasks. Locks auch via GUI (VM → Task History) oder qm unlock (vorsichtig!).

Lölung: Zeitpläne entzerren, Replication/Backup nicht überlappen lassen.

5. Storage nicht erreichbar / Permission denied

Ursache: NFS-Share gemountet aber weg, Ceph-Cluster degraded, Berechtigungen auf Directory-Storage falsch (www-data vs. root).

Diagnose: mount | grep , pvesm status, ls -la /mnt/backup.

Lösung: Storage wiederherstellen, Berechtigungen korrigieren (chown -R root:root /mnt/backup für Directory-Storage, NFS-Export-Optionen prüfen).

Prävention: Monitoring und Retention

• Backup-Jobs überwachen: Proxmox Mail-Gateway oder externes Monitoring (Prometheus/Checkmk) auf Task-Status ERROR prüfen.
• Retention durchsetzen: In Datacenter → Backup → Prune Options maxfiles, maxage setzen, damit Speicher nicht vollläuft.
• Test-Restores: Quartalsweise einen Test-Restore durchführen – nur so ist sichergestellt, dass Backups wirklich lesbar sind.

Fazit

Die meisten vzdump-Fehler lassen sich über die Task-Logs (pvenode task log) schnell eingrenzen. Die drei Backup-Modi (snapshot/suspend/stop) bieten für jeden Anwendungsfall die passende Balance aus Konsistenz und Downtime. Wer QEMU-Guest-Agent im Gast aktiviert, Speicherplatz monitoriert und Hook-Skripte testet, vermeidet 90 % der typischen Ausfälle.

Quellen

• Proxmox VE Administration Guide – Integrated Backup and Restore, Task History
• Thomas-Krenn-Wiki – Proxmox VE Backup mit vzdump

Hinweis: Dieser Beitrag wurde mit Unterstützung künstlicher Intelligenz (KI) erstellt.