Restore

Zum Inhaltsverzeichnis

7.1 Aus einem lokalen Store#

bkp_restore --store <dir>/<store>.cbs (--name <backup> [--at <zeit>] | --run <run>) --target <datei-oder-gerät>
            [--threads <n>] [--assume-zeroed] [--no-progress] [--decrypt-key file:<pfad>] [--index-dir <dir>]
            [--strict | --damage-file <pfad>] [--background]

• --store ist das Store-Verzeichnis, zum Beispiel /backup/default.cbs. Seine Generationen werden mitgelesen; wird eine Generation <store>.g<datum>.cbs genannt, nur sie.
• --name nimmt den neuesten Run dieses Backup-Namens, mit --at den neuesten bis zu diesem Zeitpunkt. --run wählt genau einen Run (Name aus --list oder UUID).
• --target ist die Zieldatei oder das Zielgerät. Es wird überschrieben. Eine Datei wird abgeschnitten und sparse geschrieben; ein Gerät muss mindestens so groß sein wie die Quelle.
• --decrypt-key file:<pfad> ist Pflicht, wenn der Store verschlüsselt ist; ein fehlender oder falscher Schlüssel bricht ab, bevor das Ziel geöffnet wird.
• --assume-zeroed sagt dem Restore, dass das Ziel bereits nur Nullen enthält (zum Beispiel ein frisch angelegtes Thin-Volume). Löcher werden dann nicht geschrieben.
• Jeder Chunk wird beim Lesen gegen seine ID geprüft. --verify wird nur noch aus Kompatibilität angenommen.

Anzeigen statt zurückspielen

bkp_restore --store /backup/default.cbs --list [--name data]       # alle Runs, älteste zuerst
bkp_restore --store /backup/default.cbs --name data --show-run     # der gewählte Run als JSON, nichts wird geschrieben

7.2 Direkt vom Server#

Statt --store liest bkp_restore den Store direkt von einem bkp_target. Zuerst zeigt --list, was vorhanden ist:

bkp_restore --server backup.example.org:9990 --server-dir vm1 \
            --tls-ca /etc/bkp/target.crt --api-key file:/etc/bkp/vm1.key --list

Ausgabe:

RUN                                                     CREATED              NAME   TYPE           SOURCE      DATA      SENT       NEW  STATUS
20261015T121825Z-6aa5d6f2-8419-482a-ab3f-0373e33b449d   2026-10-15 14:18:25  data   Full         16.0 MiB  13.0 MiB  12.0 MiB  12.0 MiB  ok
20261015T121831Z-8c47f436-cdc7-4638-a3f8-d347e0c5ba7c   2026-10-15 14:18:31  data   Incremental  16.0 MiB  13.0 MiB   2.2 MiB   2.2 MiB  ok

Die Liste ist nach Alter sortiert, die älteste zuerst; --name filtert, --store <name> wählt einen anderen Store als default. Die neueste Sicherung eines Namens stellt man so wieder her:

bkp_restore --server backup.example.org:9990 --server-dir vm1 \
            --tls-ca /etc/bkp/target.crt --api-key file:/etc/bkp/vm1.key \
            --name data --target /dev/vg0/data_restored

bkp_restore liest das Manifest vom Server und holt die Chunks gebündelt; es wird nichts zwischengespeichert. Bricht die Verbindung ab, setzt der Restore nach dem Wiederaufbau fort (--net-retry, Standard 30 Minuten).

7.3 Zu einem bestimmten Zeitpunkt (Point-in-Time)#

Jeder Run ist ein möglicher Wiederherstellungspunkt, und jeder ist gleich schnell wiederhergestellt: Es wird keine Kette zusammengeführt. Den Stand von gestern früh wählt --at, einen bestimmten Run --run:

bkp_restore --server ... --name data --at "2026-10-14 06:00" --target /dev/vg0/data_pit
bkp_restore --server ... --run 20261015T121825Z-6aa5d6f2-8419-482a-ab3f-0373e33b449d --target /dev/vg0/data_pit

--at nimmt JJJJ-MM-TT[ HH:MM[:SS]] in Ortszeit oder mit angehängtem Z in UTC (2026-10-14T06:00Z) und wählt den neuesten Run bis zu diesem Zeitpunkt. Lokal aus einem Store funktioniert das genauso.

7.4 Aus den Sinks eines Profils#

Ohne --store und --server liest bkp_restore das Profil --name und dessen Sinks aus der Agent-Konfiguration (/etc/bkp/bkp_agent.cfg samt sinks.cfg, andere mit --config-path). Orte, Schlüssel und API-Keys kommen aus den [sink:]-Abschnitten:

bkp_restore --name srv01 --target /dev/vg0/root_restored              # aus dem ersten Sink, der die Sicherung hat
bkp_restore --name srv01 --sink rz1 --target /srv/restore/root.img    # ausdrücklich aus rz1
bkp_restore --name srv01 --list                                       # Spalte SINKS: wo jede Sicherung liegt

Zurückgespielt wird die neueste Sicherung des Namens über alle Sinks, gelesen aus dem ersten Sink in sinks=-Reihenfolge, der sie hat (lokale Kopie zuerst = schnell). Was dieser Sink nicht liefern kann (Chunk fehlt oder ist beschädigt, Server während des Restores weg), kommt aus dem Zwillings-Run eines anderen Sinks; jede solche Stelle steht als Warnung im Log.

7.5 Aus einem Archiv#

Ein mit bkp_maintenance export geschriebenes Archiv (Kapitel 10) braucht keinen Store:

bkp_restore --archive /mnt/usb/data-20261015T121849Z-44fdc352-....cba --target restored.img
dd if=/dev/nst0 bs=1M | bkp_restore --archive - --target /dev/vg0/data_restored     # vom Band, von vorn nach hinten

Ausgabe:

[bkp_restore] INFO  restoring run 20261015T121849Z-44fdc352-... ('data' of 2026-10-15 14:18:49, 16777216 bytes)
                    from the archive /mnt/usb/data-20261015T121849Z-44fdc352-....cba to restored.img
[bkp_restore] INFO  done: 16777216 bytes restored (data 13631488, holes 3145728), 44 chunks, 12583143 stored bytes read

7.6 Beschädigte Daten: Teil-Restore#

Ein Chunk, den kein Store liefern kann (fehlt, beschädigt, auch in keinem Zwilling vorhanden), hält den Restore nicht an: seine Bytes werden mit Nullen geschrieben, und es geht weiter. Ein unlesbares Segment macht seinen ganzen Bereich zu Nullen. Am Ende werden die beschädigten Bereiche geloggt, der Exit-Code ist 3.

• --damage-file <pfad> schreibt die beschädigten Bereiche zusätzlich als JSON (Offset und Länge), etwa um betroffene Dateien zu finden.
• --strict bricht stattdessen beim ersten Schaden ab (Exit 1).
• Ein unlesbarer Run, ein falscher Schlüssel, eine verlorene Verbindung ohne Zwilling oder ein Schreibfehler lassen den Restore immer scheitern (Exit 1).

7.7 Virtuelle Maschinen#

bkp_proxmox und bkp_xenV sichern eine ganze VM als einen VM-Run (alle Disks plus Konfiguration). bkp_restore --disk <slot> spielt daraus eine einzelne Disk zurück (zum Beispiel scsi0, xvda); --allow-incomplete erlaubt dabei auch einen VM-Run, dem andere Disks fehlen. Ganze VMs stellen bkp_proxmox_restore und bkp_xenV_restore wieder her, auch direkt vom Server, mit --at und aus einem Archiv (siehe README). Für Hyper-V-VMs gibt es bkp_hyperV und bkp_hyperV_restore (Kapitel 20).

bkp_proxmox sichert Disks auf LVM, LVM-thin, ZFS, Ceph RBD und als qcow2-Datei (Verzeichnis, NFS, CIFS), dazu kleine raw-Dateien wie den vTPM-Zustand. Der Snapshot entsteht je nach Storage als LVM-Snapshot, als ZFS-Snapshot (gelesen über einen Klon), als RBD-Snapshot (gelesen über rbd device map) oder als interner qcow2-Snapshot (gelesen über qemu-nbd); eine raw-Datei bis 64 MiB wird kopiert, während der Gast eingefroren ist. Große raw- oder vmdk-Dateien werden abgelehnt, mit dem nächsten Schritt in der Meldung. bkp_proxmox_restore macht aus einer qcow2-Disk wieder eine qcow2-Datei, wo das Ziel-Storage qcow2 kennt, sonst ein raw-Volume. Damit der Gast nur kurz eingefroren ist, spricht bkp_proxmox den Gast-Agenten und QEMU direkt an und legt die qcow2-Snapshots aller Disks in einem Schritt, die RBD-Snapshots gleichzeitig an; die Dauer steht im Log.

Mit --ram-state (Profil: ram-state=yes) sichert bkp_proxmox auch den Arbeitsspeicher einer laufenden VM, wie ein Proxmox-Snapshot mit „Include RAM“: Proxmox nimmt den Snapshot selbst (qm snapshot … --vmstate 1), bkp_proxmox sichert die Disks und das RAM-Abbild als einen VM-Run und entfernt den Snapshot danach wieder. Dafür müssen alle Disks auf LVM-thin liegen und dort Platz für etwa den RAM der VM frei sein; das wird vorher geprüft. Der Gast steht still, solange Proxmox den Speicher schreibt (etwa belegter RAM geteilt durch die Schreibrate des Storages), die Dauer steht im Log. Eine gestoppte VM wird normal gesichert, mit Hinweis.

bkp_proxmox_restore legt eine so gesicherte VM angehalten ab: qm start <vmid> setzt sie am Sicherungszeitpunkt fort, mit allen laufenden Programmen. MAC-Adressen und SMBIOS-UUID bleiben dabei erhalten. Existiert die Original-VM im Cluster, sind die Netzwerkkarten getrennt (link_down=1); die Meldung nennt den Befehl zum Verbinden. Die Uhr im Gast geht nach, bis NTP sie nachstellt. Mit --no-ram-state bootet die VM stattdessen, mit neuer MAC-Adresse und SMBIOS-UUID wie bei jedem anderen Restore.

7.7.1 Schnelle Folgesicherung (CBT)#

Bei einer laufenden VM merkt sich QEMU für bkp_proxmox, welche Bereiche jeder Disk der Gast seit der letzten Sicherung geschrieben hat (Dirty-Bitmaps, je Disk und Job eine, Name aegisgrid-…). Die nächste Sicherung liest nur diese Bereiche; den Rest übernimmt der Store aus der vorigen Sicherung, ohne ihn zu lesen. Das spart vor allem bei großen Disks mit wenig Änderung Zeit und Last auf dem Storage. Es gilt für alle Storage-Arten (LVM, LVM-thin, ZFS, Ceph RBD, qcow2) und ist ohne Einstellung eingeschaltet.

Übernommen wird je Segment des Stores (1 GiB): Ein Segment, in das der Gast geschrieben hat, wird ganz gelesen, eine Disk unter 1 GiB also bei jeder Änderung. Wie viel sich geändert hat und wie viele Segmente übernommen wurden, steht im Log.

Ganz gelesen wird, mit einem sachlichen Hinweis im Log (kein Fehler):

• bei der ersten Sicherung des Jobs; die Folgesicherungen lesen dann nur noch die Änderungen
• wenn die VM gestoppt ist: Es gibt kein QEMU, das mitschreibt
• nach einem Neustart der VM (Stoppen und Starten, nicht ein Neustart im Gast), einer Migration oder dem Zurücksetzen auf einen Proxmox-Snapshot: Die Bitmaps leben nur so lange wie der QEMU-Prozess
• nach dem Vergrößern der Disk
• mit --type full und wenn sich --no-fs-bitmap gegenüber der vorigen Sicherung geändert hat
• wenn QEMU nicht antwortet oder an der Bitmap etwas nicht stimmt: bei jedem Zweifel lieber ganz

Wird eine Sicherung abgebrochen, auch hart (kill -9, Stromausfall des Backup-Prozesses), nimmt der nächste Lauf des Jobs oder bkp_proxmox --discard-interrupted die Änderungsverfolgung des abgebrochenen Laufs zurück; keine Änderung geht verloren. Ein angehaltener Lauf (bkp_sched hold) setzt mit seinen Daten fort. Ein Verschieben der Disk (qm disk move) unterbricht die Änderungsverfolgung nicht. Bitmaps anderer Programme, etwa pbs-bitmap-… des Proxmox Backup Servers, bleiben unberührt.

bkp_proxmox --check sagt, ob die nächste Sicherung nur die Änderungen liest. Bei Xen-Domains gibt es die schnelle Folgesicherung noch nicht; Hyper-V nutzt dafür RCT (Kapitel 20).

In der Verwaltungskonsole und in der Weboberfläche schaltet das Häkchen „Schnelle Folgesicherung (CBT)“ im VM-Profil die Funktion aus und wieder ein (ohne Häkchen: cbt=off); es erscheint bei Proxmox-Profilen, sobald der Planer es unterstützt. Die Laufliste zeigt bei einem erfolgreichen Lauf, wie gelesen wurde, etwa „Erfolgreich, nur Änderungen gelesen (1,2 GiB)“ oder „Erfolgreich, vollständig gelesen“. Den Grund für ein vollständiges Lesen nennen je Platte der Tooltip der Laufliste, die Statuszeile des Protokollfensters und die Laufdetails der Weboberfläche; die Mail des Laufs enthält dieselbe Angabe in der Zeile „Folgesicherung:“.

bkp_xenV --ram-state (Profil: ram-state=yes) sichert eine laufende Xen-Domain ebenso mit Arbeitsspeicher: xl save -p schreibt ihren Zustand als Abbild und lässt sie angehalten stehen, in diesem Moment entstehen die Snapshots aller Disks, danach läuft sie weiter. Das Abbild liegt während der Sicherung in einem Thin-LV im Pool der ersten Disk, sonst in einem normalen LV in deren Volume Group, sonst in einer Datei unter /var/lib/bkp_xenv/ramstate; die Wahl steht im Log. Alle Disks müssen LVM-Volumes sein, Hooks und --file-freeze entfallen. Die Domain steht still, solange der Speicher geschrieben wird; die Dauer steht im Log.

bkp_xenV_restore schreibt das Abbild neben die neue Konfiguration; das Log nennt xl restore <cfg> <abbild> zum Fortsetzen und xl create <cfg> für einen frischen Start. Mit --resume läuft die Domain sofort weiter. Die MAC-Adressen bleiben; läuft eine Domain mit derselben MAC, warnt der Restore, und mit --resume bleiben die Netzwerkkarten von der Bridge getrennt, bis das Original aus ist. --no-ram-state startet die Domain ohne Arbeitsspeicher.

7.8 VM an Ort und Stelle wiederherstellen#

Ist die VM noch da, ihr Inhalt aber nicht mehr brauchbar (Fehlbedienung, missglücktes Update, Verschlüsselungstrojaner), bekommt sie mit --in-place die Platten eines früheren Stands zurück und behält ihre VMID bzw. ihren Namen:

bkp_proxmox_restore --name vm101 --store /backup/default.cbs --at "2026-11-10 06:00" --in-place --stop --start
bkp_xenV_restore --name web01 --store /backup/default.cbs --in-place --dry-run       # erst prüfen
bkp_xenV_restore --name web01 --store /backup/default.cbs --in-place --changed-only  # nur Geändertes zurückschreiben

• Sicher umhängen (Standard): Jede Platte wird zuerst neu geschrieben, neben der vorhandenen. Erst wenn alle fertig sind, wird umgestellt; die bisherigen Platten bleiben erhalten (Proxmox: als unbenutzte Platten, Xen: als …-alt-<zeit>), ebenso die bisherige Konfiguration. Scheitert der Restore oder wird er gestoppt, bleibt die VM, wie sie war.
• Die gesicherte Konfiguration ersetzt die jetzige, mit den gesicherten MAC-Adressen; --keep-config behält die jetzige und tauscht nur die Platten.
• Abgelehnt wird eine laufende VM (--stop fährt sie vorher herunter), eine gesperrte oder von HA verwaltete VM, eine VM auf einem anderen Knoten und eine VM, die nicht die gesicherte ist (anderer Name und andere UUID; --force-other-vm). Die Meldung nennt den nächsten Schritt.
• --remove-old löscht die bisherigen Platten nach dem Erfolg (nicht, solange ein Proxmox-Snapshot sie braucht).
• Ohne Platz für eine zweite Kopie schreibt --overwrite direkt in die vorhandenen Platten, --changed-only schreibt dabei nur die Blöcke, die sich vom Stand unterscheiden – nach einer kleinen Änderung viel schneller. Beides hat keinen Rückweg: Ein abgebrochener Restore hinterlässt teilweise überschriebene Platten.

bkp_restore --changed-only macht dasselbe für eine einzelne Platte oder ein Volume: Jeder Block wird mit dem Ziel verglichen, nur Abweichendes wird aus der Sicherung geholt und geschrieben. In der Verwaltungskonsole heißt das „Nur geänderte Blöcke schreiben“ beim Restore an den ursprünglichen Ort oder auf einen anderen Datenträger.

7.9 Ernstfall: Host neu aufgesetzt#

Ist ein Proxmox- oder Xen-Host verloren und neu installiert, liegen seine VM-Sicherungen noch auf dem Backup-Server. So kommen die VMs zurück, mit ihrer alten VMID bzw. ihrem alten Namen:

1. Das Paket auf dem neuen Host installieren (Kapitel 2), mit dem Scheduler.
2. In der Verwaltungskonsole den Client öffnen und unter „Scheduler“ › „Ziele (Sinks)…“ mit „Neu…“ den Sink zum Backup-Server anlegen: derselbe Backup-Server, dasselbe Verzeichnis und derselbe API-Schlüssel wie bisher, bei einem verschlüsselten Sink „eigenen eingeben“ mit dem aufbewahrten Schlüssel (nicht neu erzeugen: ein anderer Schlüssel kann die Sicherungen nicht lesen).
3. „Scheduler“ › „Wiederherstellen…“ zeigt alle Sicherungen auf den Zielen des Clients, auch ohne Job. Die VM wählen, den Stand und „als neue VM“.
4. Der Assistent schlägt die VMID vor, die die VM bei der Sicherung hatte, wenn sie im Cluster frei ist; bei Xen behält die Domain ihren Namen. Dabei behält die VM ihre MAC-Adressen, sofern keine andere VM sie benutzt; ein Gast mit fester DHCP-Zuordnung bekommt so seine gewohnte Adresse. Die VM entsteht ausgeschaltet: Netzwerk prüfen, dann starten.
5. Danach die Sicherungsjobs wieder einrichten (Profil und Job), damit die VMs weiter gesichert werden.

Dasselbe auf der Kommandozeile, direkt vom Backup-Server:

bkp_proxmox_restore --server backup.example.org:9990 --server-dir pve1 --tls-ca target.crt \
    --api-key file:/etc/bkp/pve1.key --name vm101 --vmid original -- --decrypt-key file:/root/pve1-sink.key
bkp_xenV_restore --server backup.example.org:9990 --server-dir xen1 --tls-ca target.crt \
    --api-key file:/etc/bkp/xen1.key --name web01 -- --decrypt-key file:/root/xen1-sink.key

--vmid original nimmt die VMID aus der Sicherung und lehnt ab, wenn sie belegt ist (dann ersetzt --in-place die Platten der vorhandenen VM); --prefer-original-vmid nimmt sie nur, wenn sie frei ist, sonst die nächste freie. bkp_xenV_restore behält den Namen der Domain, solange es auf dem Host keine gleichnamige gibt. In beiden Fällen bleiben die MAC-Adressen erhalten, wenn keine andere VM bzw. laufende Domain sie benutzt (sonst neue; --keep-network-identity behält sie immer).

7.10 Restore prüfen#

cmp data.img restored.img && echo IDENTISCH            # bei Image-Dateien
fsck -n /dev/vg0/data_restored                          # Dateisystem prüfen (nur lesend)
mount -o ro /dev/vg0/data_restored /mnt && ls /mnt      # Inhalt ansehen