Proxmox BS: Datei-Wiederherstellung aus VM-Backup

Einleitung

Dieses Tutorial erklärt, wie Sie Proxmox Backup Server für die Wiederherstellung auf Dateiebene aus einem VM-Backup nutzen, ohne die gesamte virtuelle Maschine bereitzustellen. Sie lernen, wie Sie einzelne Dateien über den Proxmox-Backup-Dateibrowser in der Weboberfläche von Proxmox VE abrufen und wie Sie eine Proxmox-Dateiwiederherstellung auf der Kommandozeile mit proxmox-backup-client durchführen. Dieser Workflow ist hilfreich, wenn Sie einzelne Dateien aus Proxmox-Backups wiederherstellen müssen, ohne eine vollständige VM-Wiederherstellung durchzuführen.

Zielgruppe: Systemadministratoren mit mittleren Vorkenntnissen
Geschätzte Dauer: 20–40 Minuten
Ziel: Am Ende dieses Tutorials können Sie bestimmte Dateien aus einem VM-Backup auf dem Proxmox Backup Server wiederherstellen, ohne die vollständige VM wiederherzustellen.

Voraussetzungen

Stellen Sie vor dem Start sicher, dass Folgendes vorhanden ist:

• Ein funktionierender Proxmox-VE-Host mit konfiguriertem Proxmox-Backup-Server-Speicher.
• Proxmox Backup Server 3.x oder 4.x mit einem vorhandenen Datastore.
• Ein abgeschlossenes VM-Backup im PBS-Datastore.
• Zugriff auf die Proxmox-VE-Weboberfläche mit Berechtigungen zum Durchsuchen von Backups und zum Wiederherstellen von Dateien.
• Shell-Zugriff auf den Proxmox-VE-Host für die CLI-Methode.
• Der Befehl proxmox-backup-client ist auf dem Proxmox-VE-Host verfügbar.
• Root-Shell-Zugriff für die CLI-Methode mit Mapping, da das Zuordnen von Loop-Devices und das Einhängen von Dateisystemen erhöhte Berechtigungen erfordern.
• Die Schlüsseldatei, falls das VM-Backup clientseitige Verschlüsselung verwendet.
• Grundkenntnisse zu Linux-Dateisystemen, Einhängepunkten und dem Proxmox-VE-Backup-Speicher.

Schritt 1: Optionen für die Wiederherstellung auf Dateiebene verstehen

Proxmox Backup Server speichert Backups von virtuellen Proxmox-VE-Maschinen als Disk-Image-Backups auf Blockebene. Ein VM-Backup enthält daher üblicherweise Dateien wie drive-scsi0.img.fidx, qemu-server.conf.blob und client.log.blob, aber keinen normalen Verzeichnisbaum.

Für die granulare Dateiwiederherstellung in Proxmox VE gibt es zwei praktikable Optionen:

• Die Proxmox-VE-Weboberfläche verwenden, um den Backup-Snapshot zu durchsuchen und Dateien herunterzuladen.
• Mit proxmox-backup-client map ein VM-Disk-Image aus dem Backup einem lokalen Loop-Device zuordnen und anschließend das Gastdateisystem schreibgeschützt einhängen.

Die Schaltfläche „File Restore“ in Proxmox VE öffnet einen Dateibrowser für die Backup-Inhalte. Der Befehl proxmox-backup-client map ordnet ein VM-Backup-Laufwerksabbild einem lokalen Loopback-Device zu; nach der Wiederherstellung sollte unmap folgen.

Schritt 2: Einzelne Dateien über die Proxmox-VE-Weboberfläche wiederherstellen

Verwenden Sie diese Methode, wenn Sie bestimmte Dateien auf die einfachste Weise abrufen möchten, ohne die gesamte VM bereitzustellen.

Backup-Ansicht öffnen

1. Melden Sie sich an der Proxmox-VE-Weboberfläche an.
2. Wählen Sie in der linken Navigationsstruktur die VM aus.
3. Öffnen Sie den Tab „Backup“.
4. Wählen Sie den Proxmox-Backup-Server-Speicher in der Speicherauswahl aus, falls Ihre Umgebung mehrere Backup-Speicher besitzt.

Sie sollten eine Liste der verfügbaren Backup-Snapshots für die ausgewählte VM sehen.

Proxmox-Backup-Dateibrowser öffnen

1. Wählen Sie den Backup-Snapshot aus, der die benötigte Datei enthält.
2. Klicken Sie auf „File Restore“.
3. Warten Sie, bis Proxmox VE den Backup-Dateibrowser öffnet.
4. Erweitern Sie das VM-Laufwerk, das das Gastbetriebssystem oder das Datenvolume enthält.

Sie durchsuchen nun Backup-Snapshots über die Proxmox-VE-Oberfläche. Diese Ansicht unterstützt den Workflow zur Wiederherstellung von Dateien aus Proxmox Backup Server und ermöglicht es, ausgewählte Daten ohne vollständige VM-Wiederherstellung zu retten.

Benötigte Datei herunterladen

1. Navigieren Sie zu dem Verzeichnis, das die Datei enthält.
2. Wählen Sie die Datei aus.
3. Klicken Sie auf „Download“.
4. Speichern Sie die Datei auf Ihrem Arbeitsplatzrechner.

Sie sollten die ausgewählte Datei über Ihren Browser erhalten. Damit ist eine browserbasierte Wiederherstellung auf Dateiebene aus dem VM-Backup abgeschlossen.

Schritt 3: CLI-Umgebung vorbereiten

Verwenden Sie diese Methode, wenn Sie Daten aus PBS-Datastore-Backups über die Kommandozeile wiederherstellen.

Wiederherstellungsvariablen definieren

Führen Sie die folgenden Befehle auf dem Proxmox-VE-Host aus. Ersetzen Sie die Platzhalter durch Werte aus Ihrer Umgebung.

export PBS_REPOSITORY="<PBS_USER>@<PBS_REALM>@<PBS_SERVER>:<DATASTORE>"
export PBS_SNAPSHOT="vm/<VM_ID>/<SNAPSHOT_TIMESTAMP>"
export PBS_ARCHIVE="drive-scsi0.img"
export RESTORE_MOUNT="/mnt/pbs-file-restore"
export RESTORE_TARGET="/root/restored-from-pbs"
export PBS_PASSWORD="<PBS_USER_PASSWORD>"
export PBS_FINGERPRINT="<PBS_SERVER_FINGERPRINT>"

Beispielwerte:

export PBS_REPOSITORY="root@[email protected]:backup"
export PBS_SNAPSHOT="vm/101/2026-06-04T01:30:00Z"
export PBS_ARCHIVE="drive-scsi0.img"
export RESTORE_MOUNT="/mnt/pbs-file-restore"
export RESTORE_TARGET="/root/restored-from-pbs"
export PBS_PASSWORD="12345678"
export PBS_FINGERPRINT="b1:89:bd:c9:b1:f8:33..."

Die Variablen definieren das PBS-Repository, den VM-Backup-Snapshot, das zuzuordnende Laufwerksarchiv, den temporären Einhängepunkt und das lokale Wiederherstellungsziel. Setzen Sie die Umgebungsvariablen PBS_PASSWORD und PBS_FINGERPRINT. Den Zertifikat-Fingerprint erhalten Sie auf dem Proxmox Backup Server mit dem Befehl proxmox-backup-manager cert info.

Bei der ersten Verbindung fordert der Befehl login interaktiv zur Bestätigung des Zertifikat-Fingerprints und zur Eingabe des Passworts auf. Ohne diese Variablen schlagen automatisierte Befehle mit certificate validation failed fehl, wenn der Fingerprint fehlt, bzw. mit no password input mechanism available, wenn kein Passwort angegeben wird.

Am Proxmox Backup Server anmelden

Führen Sie den Anmeldebefehl aus:

proxmox-backup-client login --repository "$PBS_REPOSITORY"

Erwartete Ausgabe:

Password:

Geben Sie das Passwort des PBS-Benutzers ein. Bei erfolgreicher Authentifizierung speichert der Client ein temporäres Ticket.

Schritt 4: VM-Backup-Snapshot und Disk-Archiv identifizieren

Listen Sie die Backup-Gruppen im PBS-Repository auf:

proxmox-backup-client list --repository "$PBS_REPOSITORY"

Beispielausgabe: Backup-Tabelle.

Listen Sie die Snapshots der VM-Gruppe auf:

proxmox-backup-client snapshot list vm/<VM_ID> \
  --repository "$PBS_REPOSITORY"

Beispielausgabe: Snapshot-Tabelle.

Listen Sie die Dateien im ausgewählten Snapshot auf:

proxmox-backup-client snapshot files "$PBS_SNAPSHOT" \
  --repository "$PBS_REPOSITORY"

Beispielausgabe:

client.log.blob
drive-scsi0.img.fidx
index.json.blob
qemu-server.conf.blob

Schritt 5: VM-Backup-Laufwerk einem Loop-Device zuordnen

Erstellen Sie die Wiederherstellungsverzeichnisse:

mkdir -p "$RESTORE_MOUNT" "$RESTORE_TARGET"

Ordnen Sie das VM-Disk-Image aus PBS zu:

proxmox-backup-client map "$PBS_SNAPSHOT" "$PBS_ARCHIVE" \
  --repository "$PBS_REPOSITORY"

Beispielausgabe:

/dev/loop0

Speichern Sie das zurückgegebene Loop-Device in einer Variable:

export LOOP_DEVICE="/dev/loop0"

Der Befehl map ordnet ein VM-Backup-Laufwerksabbild einem lokalen Loopback-Device zu.

Schritt 6: Zugeordnetes Laufwerk prüfen

Listen Sie die Partitionen und Dateisysteme auf:

lsblk -f "$LOOP_DEVICE"

Beispielausgabe:

NAME        FSTYPE LABEL UUID                                 MOUNTPOINTS
loop0
├─loop0p1   vfat         1111-2222
└─loop0p2   ext4         aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Wenn keine Partitionen angezeigt werden, weisen Sie den Kernel an, die Partitionstabelle einzulesen:

partx -a "$LOOP_DEVICE"

Prüfen Sie anschließend erneut:

lsblk -f "$LOOP_DEVICE"

Sie sollten nun Partitionsgeräte wie /dev/loop0p1 und /dev/loop0p2 sehen.

Schritt 7: Gastdateisystem schreibgeschützt einhängen

Wählen Sie die Partition aus, die die benötigten Dateien enthält. In diesem Beispiel ist das Linux-Root-Dateisystem /dev/loop0p2.

Hängen Sie sie schreibgeschützt ein:

mount -o ro /dev/loop0p2 "$RESTORE_MOUNT"

Erwartete Ausgabe: Der Befehl sollte bei erfolgreichem Einhängen keine Ausgabe liefern.

Prüfen Sie das eingehängte Dateisystem:

ls "$RESTORE_MOUNT"

Beispielausgabe:

bin
boot
etc
home
root
usr
var

Sie stellen nun über die Kommandozeile einzelne Dateien aus Proxmox-Backups wieder her, ohne die gesamte virtuelle Maschine wiederherzustellen.

LVM-Volume einhängen, wenn der Gast LVM verwendet

Wenn lsblk -f den Eintrag LVM2_member anzeigt, suchen Sie nach Volume-Gruppen:

vgscan --mknodes

Beispielausgabe:

Found volume group "ubuntu-vg" using metadata type lvm2

Aktivieren Sie die Volume-Gruppe:

vgchange -ay ubuntu-vg

Listen Sie die Logical Volumes auf:

lvs

Beispielausgabe:

LV        VG        Attr       LSize
ubuntu-lv ubuntu-vg -wi-a----- 50.00g

Hängen Sie das Logical Volume schreibgeschützt ein:

mount -o ro /dev/ubuntu-vg/ubuntu-lv "$RESTORE_MOUNT"

Sie sollten nun das wiederhergestellte Gastdateisystem unter $RESTORE_MOUNT durchsuchen können.

Schritt 8: Bestimmte Dateien aus dem Backup kopieren

Erstellen Sie ein lokales Verzeichnis für wiederhergestellte Dateien:

mkdir -p "$RESTORE_TARGET"

Kopieren Sie eine einzelne Datei:

cp -a "$RESTORE_MOUNT/etc/hostname" "$RESTORE_TARGET/"

Erwartete Ausgabe: Der Befehl sollte beim erfolgreichen Kopieren der Datei keine Ausgabe liefern.

Kopieren Sie ein Verzeichnis:

rsync -a "$RESTORE_MOUNT/var/www/html/" \
  "$RESTORE_TARGET/html/"

Erwartete Ausgabe: Der Befehl sollte beim erfolgreichen Kopieren des Verzeichnisses keine Ausgabe liefern.

Überprüfen Sie die kopierten Dateien:

find "$RESTORE_TARGET" -maxdepth 3 -type f

Beispielausgabe:

/root/restored-from-pbs/hostname
/root/restored-from-pbs/html/index.html

Schritt 9: Dateien aus einem dateibasierten PBS-Backup mit pxar wiederherstellen

Dieser Schritt ist für die Wiederherstellung auf Dateiebene aus einer VM optional, aber nützlich, wenn der Backup-Snapshot ein Dateiarchiv wie root.pxar enthält.

Listen Sie die Dateien im Snapshot auf:

proxmox-backup-client snapshot files "$PBS_SNAPSHOT" \
  --repository "$PBS_REPOSITORY"

Beispielausgabe:

catalog.pcat1.didx
root.pxar.didx

Öffnen Sie die interaktive Wiederherstellungs-Shell:

proxmox-backup-client catalog shell "$PBS_SNAPSHOT" root.pxar \
  --repository "$PBS_REPOSITORY"

Listen Sie innerhalb der Shell die Verzeichnisse auf:

pxar:/ > ls

Beispielausgabe:

etc
home
root
var

Wählen Sie eine Datei aus:

pxar:/ > select /etc/hostname

Stellen Sie die ausgewählten Dateien wieder her:

pxar:/ > restore-selected /root/restored-from-pxar

Beenden Sie die Shell:

pxar:/ > exit

Schritt 10: CLI-Wiederherstellungssitzung bereinigen

Hängen Sie das Gastdateisystem aus:

umount "$RESTORE_MOUNT"

Wenn Sie eine LVM-Volume-Gruppe aktiviert haben, deaktivieren Sie sie nach dem Aushängen:

vgchange -an ubuntu-vg

Entfernen Sie Partitionszuordnungen, falls Sie diese mit partx erstellt haben:

partx -d "$LOOP_DEVICE"

Heben Sie die Zuordnung des PBS-Loop-Devices auf:

proxmox-backup-client unmap "$LOOP_DEVICE"

Erwartete Ausgabe: Der Befehl sollte keine Ausgabe liefern, wenn die Zuordnung des Loop-Devices erfolgreich aufgehoben wurde.

Entfernen Sie temporäre Einhängeverzeichnisse, wenn Sie sie nicht mehr benötigen:

rmdir "$RESTORE_MOUNT"

Entfernen Sie sensible Umgebungsvariablen:

unset PBS_PASSWORD
unset PBS_REPOSITORY
unset PBS_SNAPSHOT
unset PBS_ARCHIVE
unset LOOP_DEVICE

Die lokale Wiederherstellungsumgebung ist nun bereinigt.

Überprüfung

Prüfen Sie, ob die wiederhergestellten Dateien vorhanden sind:

ls -la "$RESTORE_TARGET"

Beispielausgabe:

total 12
drwxr-xr-x  3 root root 4096 Jun  4 02:10 .
drwx------ 10 root root 4096 Jun  4 02:10 ..
-rw-r--r--  1 root root   12 Jun  4 01:00 hostname

Vergleichen Sie bei Bedarf die Dateiinhalte:

cat "$RESTORE_TARGET/hostname"

Beispielausgabe:

app-vm-01

Bestätigen Sie, dass sich die wiederhergestellte Kopie außerhalb des eingehängten Backup-Dateisystems befindet:

realpath "$RESTORE_TARGET"

Beispielausgabe:

/root/restored-from-pbs

Prüfen Sie, dass nach der Bereinigung keine PBS-Loop-Zuordnungen mehr vorhanden sind:

losetup -a | grep pbs-loopdev || true

Erwartete Ausgabe: Wenn der Befehl keine Ausgabe liefert, sind keine proxmox-backup-Loop-Zuordnungen mehr vorhanden.

Änderungen rückgängig machen

Dieses Tutorial verändert weder das ursprüngliche VM-Backup noch den PBS-Datastore. Die Methode über die Weboberfläche lädt Dateien nur auf Ihren Arbeitsplatzrechner herunter. Die CLI-Methode erstellt temporäre Loop-Zuordnungen, Einhängepunkte und lokale Kopien der wiederhergestellten Dateien.

Um die CLI-Wiederherstellungsumgebung zurückzusetzen, führen Sie aus:

umount "$RESTORE_MOUNT"
proxmox-backup-client unmap "$LOOP_DEVICE"
rm -rf "$RESTORE_TARGET"
rmdir "$RESTORE_MOUNT"

Wenn Sie eine LVM-Volume-Gruppe des Gastes aktiviert haben, deaktivieren Sie sie:

vgchange -an ubuntu-vg

Wenn Sie Partitionszuordnungen manuell hinzugefügt haben, entfernen Sie sie:

partx -d "$LOOP_DEVICE"

Fehlerbehebung

Schaltfläche „File Restore“ fehlt

Stellen Sie sicher, dass Sie einen Backup-Snapshot auf einem PBS-Speicher ausgewählt haben und nicht auf einem lokalen ISO- oder Image-Speicher. Prüfen Sie außerdem, ob Ihr Konto über ausreichende Berechtigungen zum Durchsuchen der Backup-Inhalte verfügt.

Der Web-Dateibrowser kann das Dateisystem nicht lesen

Das Gastdateisystem ist möglicherweise nicht unterstützt, innerhalb der VM verschlüsselt, beschädigt oder liegt in LVM, RAID oder einer anderen Speicherschicht. Verwenden Sie die CLI-Methode, um die Partitionen manuell mit lsblk, blkid, vgscan und dateisystemspezifischen Werkzeugen zu untersuchen.

proxmox-backup-client map schlägt mit Authentifizierungsfehlern fehl

Prüfen Sie die Repository-Zeichenfolge und die Zugangsdaten:

echo "$PBS_REPOSITORY"
proxmox-backup-client login --repository "$PBS_REPOSITORY"

Erwartetes Repository-Format:

<PBS_USER>@<PBS_REALM>@<PBS_SERVER>:<DATASTORE>

Wenn Sie einen Namespace verwenden, fügen Sie --ns zu den betreffenden proxmox-backup-client-Befehlen hinzu.

Das Backup ist verschlüsselt

Geben Sie beim Zuordnen des Backups die Schlüsseldatei an:

proxmox-backup-client map "$PBS_SNAPSHOT" "$PBS_ARCHIVE" \
  --repository "$PBS_REPOSITORY" \
  --keyfile <PATH_TO_ENCRYPTION_KEY>

Beispielausgabe:

/dev/loop0

Partitionsgeräte werden nicht angezeigt

Führen Sie aus:

partx -a "$LOOP_DEVICE"
lsblk -f "$LOOP_DEVICE"

Wenn das Laufwerk LVM verwendet, führen Sie aus:

vgscan --mknodes
lvs

Wenn das Laufwerk Software-RAID, ZFS innerhalb des Gastes oder Vollverschlüsselung verwendet, nutzen Sie die passenden Speicherwerkzeuge des Gastes und hängen Sie wiederhergestellte Dateien nach Möglichkeit schreibgeschützt ein.

Einhängen schlägt mit falschem Dateisystemtyp fehl

Prüfen Sie den Dateisystemtyp:

blkid

Beispielausgabe:

/dev/loop0p2: UUID="..." TYPE="ext4"

Hängen Sie anschließend bei Bedarf mit dem richtigen Typ ein:

mount -t ext4 -o ro /dev/loop0p2 "$RESTORE_MOUNT"

Beim Kopieren der Dateien bleibt der falsche Besitzer erhalten

Wenn Sie Dateien als root aus einem eingehängten Gastdateisystem kopieren, können die Besitzerangaben auf numerische Benutzer-IDs des Gastes verweisen. Das ist zu erwarten. Verwenden Sie rsync -a, um die Metadaten für eine spätere Prüfung zu erhalten, oder kopieren Sie ohne Beibehaltung des Besitzers, wenn Sie nur die Dateiinhalte benötigen.

Fazit

Sie haben einzelne Dateien aus einem VM-Backup auf dem Proxmox Backup Server wiederhergestellt, ohne die gesamte VM bereitzustellen. Die Methode über die Weboberfläche ist der schnellste Weg für die meisten Aufgaben zur Dateiwiederherstellung aus Proxmox Backup Server, während die CLI-Methode präzise Kontrolle für die erweiterte Proxmox-Dateiwiederherstellung und die Untersuchung von Dateisystemen bietet. Verwenden Sie im Routinebetrieb zuerst den Workflow „File Restore“ von Proxmox VE und nutzen Sie proxmox-backup-client map, wenn Sie eine tiefergehende Wiederherstellung auf der Kommandozeile aus einem PBS-Datastore benötigen.

Nächste Schritte

Erwägen Sie, Ihr internes Wiederherstellungsverfahren mit den genauen PBS-Repository-Namen, Namespaces, VM-IDs, dem Speicherort der Verschlüsselungsschlüssel und einer Checkliste zur Validierung der Wiederherstellung zu dokumentieren. Sie können die Wiederherstellung auf Dateiebene außerdem regelmäßig als Teil der Backup-Verifizierung testen, denn ein Backup ist nur dann nützlich, wenn Sie die benötigten Daten daraus wiederherstellen können.

Dokumentversion: 1.0
Zuletzt aktualisiert: Juni 2026
Verantwortlich: Team für technische Dokumentation