Handbuch auf MkDocs-Basis, mit Bildschirmfotos aus dem Programm

26 Kapitel in vier Teilen, in der Reihenfolge, in der man sie braucht:
erst sichern, dann Dateien holen, dann ganze Maschinen wiederherstellen,
dahinter der Nachschlagteil.

Gebaut wird mit MkDocs + Material. Bewusst ohne Netzabhaengigkeiten:
keine Schriften vom CDN (font: false), Volltextsuche mit deutschem
Stemming liegt neben den Seiten. Im Notfall steht vielleicht das halbe
Netz - dann nuetzt eine Doku im Internet nichts.

  handbuch/bauen.sh              baut handbuch/site/
  handbuch/bauen.sh ansehen      Vorschau auf 127.0.0.1:8000

install.sh nimmt das gebaute Handbuch mit nach
/usr/share/doc/pvesnap/handbuch/ - falls es vorliegt. Auf dem Host selbst
wird nichts gebaut, mkdocs gehoert nicht auf einen Hypervisor.

Die 28 Bildschirmfotos sind nicht abfotografiert, sondern erzeugt: Der
echte Programmcode laeuft in einem Pseudo-Terminal gegen einen erfundenen
Proxmox-Host (Attrappen fuer pvesh, perl und rbd), pyte baut den Bildschirm
nach, heraus faellt ein SVG. Damit stimmen sie garantiert mit dem Programm
ueberein, sind reproduzierbar und enthalten keine echten Daten. Die
Werkstatt dafuer liegt unter handbuch/werkstatt/ samt LIESMICH.md.

Nebenbei: die Schlussmeldung von install.sh warb noch mit --exchange,
das mit dem eingebauten Austauschlaufwerk weggefallen ist.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

handbuch/docs/wiederherstellen/verwerfen.md

@@ -0,0 +1,146 @@
+# Verwerfen und aufräumen
+
+## Verwerfen
+
+Taste ++x++ in der Übersicht oder in der Detailansicht:
+
+![Sicherheitsabfrage vor dem Verwerfen](../bilder/recovery-verwerfen.svg)
+
+Oder auf der Kommandozeile:
+
+```bash
+pvesnap-recovery destroy 9101
+pvesnap-recovery destroy 9101 -y      # ohne Rückfrage
+```
+
+`destroy` räumt vollständig auf:
+
+<div class="ablauf" markdown>
+
+**1.** Maschine stoppen
+
+**2.** Gast samt aller Klone entfernen
+
+**3.** Austauschlaufwerke freigeben (der **Inhalt bleibt** — sie gehören zu
+keiner Maschine)
+
+**4.** Den **Schutz der Quell-Snapshots wieder aufheben**
+
+**5.** Eintrag aus der Merkliste nehmen
+
+</div>
+
+---
+
+### Schritt 4 ist der wichtige
+
+!!! info "Warum der Snapshot-Schutz wieder weg muss"
+
+    Ceph verlangt für einen Klon, dass der Quell-Snapshot geschützt ist
+    (`rbd snap protect`), und Proxmox setzt das beim Klonen selbst.
+
+    Bliebe der Schutz stehen, könnte die [Vorhaltezeit](../sichern/vorhaltezeit.md)
+    diesen Snapshot später nicht mehr löschen — im Protokoll stünde dann immer
+    wieder:
+
+    ```
+    snapshot is protected
+    ```
+
+    Solange eine Wiederherstellung existiert, ist ihr Quell-Snapshot also
+    **bewusst** unlöschbar. Danach nicht mehr.
+
+---
+
+### Was `destroy` nicht anfasst
+
+!!! success "Nur Maschinen mit dem Tag `pvesnap-recovery`"
+
+    Eine von Hand angelegte VM lässt sich damit nicht versehentlich löschen —
+    auch dann nicht, wenn sie zufällig eine VMID hat, die einmal einer
+    Wiederherstellung gehörte.
+
+**Austauschlaufwerke bleiben.** Sie gehören zu keiner Maschine; ihr Inhalt
+überlebt jede Wiederherstellung. Sie werden nur wieder als `frei` markiert.
+
+**Das Original bleibt.** Selbstverständlich — `destroy` fasst ausschließlich die
+Wiederherstellung an.
+
+---
+
+## `cleanup`
+
+Wird eine Wiederherstellung in der **Proxmox-Oberfläche** entfernt statt mit
+`destroy`, bleibt etwas liegen:
+
+* der Klon selbst kann übrigbleiben
+* der Quell-Snapshot bleibt **geschützt** — die Vorhaltezeit scheitert dann
+  dauerhaft
+
+```bash
+pvesnap-recovery cleanup          # zeigt Gefundenes, fragt, räumt auf
+pvesnap-recovery cleanup --all    # auch Datenträger ohne Elternteil
+pvesnap-recovery cleanup -y       # ohne Rückfrage
+```
+
+### Wonach gesucht wird
+
+Nach Datenträgern der Form `vm-<id>-disk-N`, zu deren VMID es **keine
+Konfigurationsdatei** unter `/etc/pve/nodes/*/` mehr gibt.
+
+!!! info "Bewusst nicht über `/cluster/resources`"
+
+    Ein Gast auf einem abgemeldeten Node taucht dort unter Umständen nicht auf
+    — und dann würden die Platten einer **lebenden** Maschine als verwaist
+    gelten.
+
+    Die Konfigurationsdateien im Cluster-Dateisystem sind die verlässlichere
+    Quelle.
+
+Zwei weitere Vorsichtsmaßnahmen:
+
+| | |
+|---|---|
+| **Ohne Elternteil** wird nichts von selbst entfernt | dafür braucht es `--all` |
+| **Der Schutz eines Snapshots wird nur gelöst**, wenn wirklich kein Klon mehr daran hängt | sonst würde ein noch lebender Klon seine Grundlage verlieren |
+
+### Wann man es braucht
+
+* Jemand hat eine Wiederherstellung in der Weboberfläche gelöscht
+* Ein `destroy` ist mittendrin abgebrochen (Host neu gestartet, Netz weg)
+* Im Protokoll des Dienstes taucht wiederholt `snapshot is protected` auf
+
+Der letzte Fall ist der häufigste — und der, den man sonst lange sucht.
+
+---
+
+## Aufräumen prüfen
+
+```bash
+pvesnap-recovery list                    # sind noch welche eingetragen?
+qm list | grep -i recovery               # laufen noch welche?
+rbd -p <pool> ls | grep -E 'vm-9[0-9]{3}-'   # liegen noch Klone herum?
+rbd -p <pool> snap ls vm-101-disk-0      # steht noch ein Schutz?
+```
+
+Bei der letzten Ausgabe steht in der Spalte `PROTECTED` ein `yes`, solange ein
+Snapshot geschützt ist. Ohne zugehörigen Klon ist das ein Fall für `cleanup`.
+
+---
+
+## Vor der Deinstallation
+
+`uninstall.sh` warnt, wenn noch Wiederherstellungen offen sind. Der Grund ist
+derselbe:
+
+!!! warning "Erst verwerfen, dann deinstallieren"
+
+    Nach dem Entfernen von pvesnap gibt es kein `destroy` und kein `cleanup`
+    mehr. Die Klone müsste man dann von Hand aufspüren, und den Snapshot-Schutz
+    von Hand lösen:
+
+    ```bash
+    rbd -p <pool> snap unprotect vm-101-disk-0@auto-stuendlich-20260809-100000
+    ```
+
+    Mit Werkzeug ist das ein Tastendruck. Ohne eine Stunde Sucherei.