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>
This commit is contained in:
duffyduck
2026-08-09 12:39:30 +02:00
co-authored by Claude Opus 5
parent c484596702
commit 59e7224297
72 changed files with 7355 additions and 2 deletions
+164
View File
@@ -0,0 +1,164 @@
# Der Explorer
```bash
pvesnap-explorer # Gast und Snapshot auswählen
pvesnap-explorer 101 # Snapshot von VM 101 auswählen
pvesnap-explorer 101 <snapname> # direkt öffnen
```
Braucht `root` — Snapshots einbinden und mounten geht nicht anders.
---
## Drei Ebenen
<div class="ablauf" markdown>
**Gastauswahl****Snapshot-Auswahl****Dateien**
</div>
Mit ++q++ geht es jeweils eine Ebene zurück. Beim Verlassen des Dateibrowsers
wird der Snapshot wieder ausgehängt, sodass man gleich den nächsten öffnen kann.
### 1. Welcher Gast?
![Gastauswahl](../bilder/explorer-gastauswahl.svg)
Alle VMs und Container des Clusters, mit Zustand und Node. Ein gestoppter Gast
ist kein Hindernis — sein Snapshot lässt sich genauso lesen.
### 2. Welcher Snapshot?
![Snapshot-Auswahl](../bilder/explorer-snapshotauswahl.svg)
Neueste zuerst, mit Datum und Beschreibung. Die Beschreibung ist der Grund,
warum es sich lohnt, sie in der Konfiguration ordentlich zu setzen — hier sucht
man später danach.
Halbfertige Einträge aus abgebrochenen Läufen werden ausgeblendet; wenn welche
da sind, sagt eine Meldung, wie man sie loswird.
### 3. Die Dateien
![Der Explorer mit zwei Fenstern](../bilder/explorer-fenster.svg)
Links der Snapshot, rechts der lokale Rechner. Oben steht, welcher Gast und
welcher Snapshot offen ist, unten der volle Pfad des markierten Eintrags.
---
## Tastenbelegung
| Taste | |
|---|---|
| ++tab++ | Fenster wechseln |
| ++up++ ++down++ | bewegen |
| ++enter++ | Verzeichnis öffnen oder Datei ansehen |
| ++backspace++ ++left++ | ein Verzeichnis hoch |
| ++home++ ++end++ | Anfang / Ende |
| ++page-up++ ++page-down++ | seitenweise |
| ++space++ | markieren |
| ++asterisk++ | Markierung umkehren |
| ++a++ / ++u++ | alle markieren / keine |
| ++f5++ oder ++c++ | Markiertes ins andere Fenster kopieren |
| ++f3++ oder ++v++ | Datei ansehen (Text oder Hex) |
| ++f7++ oder ++n++ | neues Verzeichnis (nur im lokalen Fenster) |
| ++f6++ oder ++g++ | Verzeichnis direkt eingeben |
| ++f2++ oder ++m++ | anderes Dateisystem des Snapshots wählen |
| ++r++ | neu einlesen |
| ++f10++ oder ++q++ | eine Ebene zurück |
| ++question++ oder ++f1++ | Hilfe |
Die Hilfe ist jederzeit erreichbar:
![Die Tastenhilfe](../bilder/explorer-hilfe.svg)
---
## Kopieren
Markieren mit ++space++ — markierte Einträge stehen in Gelb:
![Markierte Dateien](../bilder/explorer-markiert.svg)
Dann ++f5++:
![Der Kopierdialog](../bilder/explorer-kopieren.svg)
Kopiert wird **immer vom aktiven ins andere Fenster**. In den Snapshot hinein
geht nichts — er ist schreibgeschützt eingebunden.
Während des Kopierens läuft ein Fortschrittsbalken; ++esc++ bricht ab. Bereits
kopierte Dateien bleiben dabei liegen, die gerade laufende wird entfernt, damit
kein halbes Stück zurückbleibt.
Existiert eine Datei am Ziel schon, wird gefragt:
| Antwort | |
|---|---|
| `ja` | diese überschreiben |
| `nein` | diese überspringen |
| `alle` | alles Weitere überschreiben, nicht mehr fragen |
| `keine` | alles Weitere überspringen |
**Was übersprungen wird:** Gerätedateien, Sockets und FIFOs. Symbolische
Verweise bleiben Verweise — sie werden nicht aufgelöst.
!!! tip "Aus mehreren Snapshots ins selbe Ziel"
Das rechte Fenster behält sein Verzeichnis, auch wenn man zurückgeht und
den nächsten Snapshot öffnet. Damit lassen sich mehrere Stände bequem
nebeneinander sammeln — etwa dieselbe Konfigurationsdatei von gestern,
vorgestern und vom Monatsersten.
---
## Dateien ansehen
++f3++ zeigt eine Datei, ohne sie zu kopieren:
![Eine Datei ansehen](../bilder/explorer-ansehen.svg)
Text wird als Text dargestellt, alles andere als Hexdump. Das reicht meist
schon, um die Frage „ist das die richtige Fassung?" zu beantworten — ohne die
Datei erst auf den Host zu holen.
---
## Mehrere Dateisysteme
Eine VM hat oft mehr als eine Partition: `/` und `/boot`, dazu vielleicht ein
eigenes Datenlaufwerk. Hat der Snapshot mehrere brauchbare Dateisysteme, fragt
der Explorer beim Öffnen, welches er zeigen soll.
Wechseln geht später mit ++f2++, ohne den Snapshot zu schließen.
!!! note "Was nicht auftaucht"
Swap-Partitionen, EFI-Partitionen ohne lesbaren Inhalt und alles, was der
Kernel nicht kennt. LVM innerhalb der VM wird erkannt und aktiviert;
verschlüsselte Volumes bleiben verschlüsselt.
---
## Aufrufparameter
| Parameter | Vorgabe | Bedeutung |
|---|---|---|
| `vmid` | — | Gast direkt vorwählen |
| `snapshot` | — | Snapshot direkt vorwählen |
| `-l`, `--local <pfad>` | aktuelles Verzeichnis | Startverzeichnis im rechten Fenster |
| `-p`, `--path <pfad>` | — | beliebiges Verzeichnis öffnen, ohne Proxmox zu fragen |
| `--cleanup` | — | hängengebliebene Einbindungen lösen und beenden |
| `-v`, `--verbose` | — | ausführliches Protokoll |
| `-V`, `--version` | — | Version anzeigen |
```bash
pvesnap-explorer --local /srv/restore # rechtes Fenster startet dort
pvesnap-explorer --path /mnt/x # ohne Proxmox, zum Ausprobieren
pvesnap-explorer --cleanup # nach einem Absturz aufräumen
```
`--path` ist auch der Weg, den Commander auf etwas ganz anderes loszulassen —
ein gemountetes Backup etwa. Dann braucht es weder Proxmox noch root.
+95
View File
@@ -0,0 +1,95 @@
# Daten zurückholen
Ein Snapshot ist kein Verzeichnis. Er liegt als Blockgerät oder als Eintrag im
qcow2-Kopf im Storage, und dort kann man nicht einfach hineinsehen.
pvesnap nimmt einem das ab: Der Snapshot wird **schreibgeschützt** eingebunden
und gemountet, und danach ist er ein ganz gewöhnlicher Pfad.
---
## Drei Wege hinein
| | wofür |
|---|---|
| [**Der Explorer**](explorer.md) | Auf dem Host, im Terminal. Zwei Fenster wie im Midnight Commander. Der schnellste Weg, wenn man ohnehin per SSH angemeldet ist. |
| [**Die Web-Oberfläche**](web.md) | Im Browser, auch vom Arbeitsplatz. Anmeldung mit den Proxmox-Benutzern. Verzeichnisse kommen als ZIP. |
| [**Als Maschine starten**](../wiederherstellen/index.md) | Wenn Dateien nicht reichen — eine Datenbank etwa wird erst brauchbar, wenn ihr Server läuft und selbst einen Dump schreibt. |
Die ersten beiden lesen nur. Sie können nichts kaputt machen.
---
## Was dabei im Hintergrund passiert
Je nach Storage geht es unterschiedlich hinein:
| Storage | Weg |
|---|---|
| `rbd` (Ceph) | `rbd map pool/image@snap`; bei nicht unterstützten Image-Features über `rbd-nbd` |
| `zfspool` | Container direkt über `.zfs/snapshot/…`, VMs über einen temporären Klon |
| `lvmthin`, `lvm` | die Snapshot-LV `snap_<volume>_<snapname>` aktivieren |
| `dir`, `nfs`, `cifs` | `qemu-nbd --load-snapshot` — nur bei qcow2 |
Danach werden die Partitionen erkannt und gemountet, und zwar mit
`ro,noload` bzw. `ro,norecovery,nouuid`.
!!! info "Warum diese Optionen wichtig sind"
Der Snapshot einer **laufenden** Maschine hat fast immer ein unsauberes
Journal — die VM war ja mitten in der Arbeit. Ohne `noload` bzw.
`norecovery` würde der Kernel das Journal abspielen wollen, also
**schreiben**. In einen Snapshot, der schreibgeschützt sein soll.
Deshalb wird bewusst darauf verzichtet. Die Folge: Die letzten Sekunden vor
dem Snapshot können in den Dateien fehlen, auch wenn sie im Journal stünden.
Für eine Datenbank ist das der Grund, den Weg über
[`pvesnap-recovery`](../wiederherstellen/index.md) zu nehmen — dort startet
der Datenbankserver und räumt selbst auf.
---
## Aufräumen
Beim Beenden wird alles wieder ausgehängt — automatisch, auch beim Verlassen
über ++q++ oder ++ctrl+c++.
Bleibt nach einem Absturz etwas hängen:
```bash
pvesnap-explorer --cleanup
pvesnap-web --cleanup
```
Beide räumen dieselben Reste weg: Einbindungen unter `/run/pvesnap/`,
`rbd`-Zuordnungen, NBD-Geräte, temporäre ZFS-Klone.
Nachsehen, ob wirklich nichts mehr liegt:
```bash
findmnt | grep pvesnap
rbd showmapped
losetup -a
ls /run/pvesnap/
```
---
## Was nicht geht
!!! warning "Schreiben"
In einen Snapshot hinein geht nichts. Kein Kopieren, kein Löschen, kein
Umbenennen. Das ist keine Vorsichtsmaßnahme, sondern eine Eigenschaft der
Sache: Ein Snapshot ist ein festgehaltener Stand.
Wer einen Stand **ändern** will, um daraus weiterzuarbeiten, braucht
[`pvesnap-recovery`](../wiederherstellen/index.md) — dort entsteht ein Klon,
der voll beschreibbar ist.
!!! warning "Verschlüsselte Dateisysteme"
LUKS, BitLocker oder eine verschlüsselte Datenbankpartition bleiben auch im
Snapshot verschlüsselt. Es gibt keinen Weg daran vorbei — die Daten müssen
im laufenden Gast entschlüsselt werden. Auch das ist ein Fall für
`pvesnap-recovery`.
+223
View File
@@ -0,0 +1,223 @@
# Die Web-Oberfläche
`pvesnap-web` zeigt Snapshots im Browser. Gedacht für die Fälle, in denen der
[Explorer](explorer.md) nicht passt: Jemand ohne SSH-Zugang soll etwas
herausbekommen, oder die Dateien sollen direkt auf dem Arbeitsplatzrechner
landen statt auf dem Hypervisor.
Sie liest **ausschließlich**. Ändern oder löschen kann sie nichts.
---
## Als Dienst einrichten
```bash
./install.sh --with-webexplorer --port 8823
```
Danach läuft die Oberfläche dauerhaft auf `http://<host>:8823/` und startet mit
dem System.
```bash
./install.sh --with-webexplorer --port 8443 --bind 10.0.0.5 # nur auf einer IP
./install.sh --with-webexplorer --port 8823 --no-start # erst später starten
```
Alle Aufrufparameter des Dienstes stehen in **`/etc/pvesnap/web.conf`**:
```
PVESNAP_WEB_ARGS=--bind 0.0.0.0 --port 8823 --auth pve
```
Dort lässt sich nachträglich alles ändern — Port, Adresse, Anmeldeart, Rechte:
```bash
nano /etc/pvesnap/web.conf
systemctl restart pvesnap-web
```
### Dienst verwalten
```bash
systemctl status pvesnap-web # läuft er?
systemctl restart pvesnap-web # nach Änderungen in web.conf
systemctl stop pvesnap-web # anhalten (hängt offene Snapshots aus)
systemctl disable pvesnap-web # nicht mehr automatisch starten
journalctl -u pvesnap-web -f # Protokoll, auch fehlgeschlagene Anmeldungen
```
---
## Von Hand starten
Für einen einmaligen Einsatz, ohne etwas zu installieren:
```bash
pvesnap-web # Gast und Snapshot im Browser wählen
pvesnap-web 101 # nur diesen Gast anbieten
pvesnap-web 101 auto-taeglich-20260809-023000 # Snapshot gleich öffnen
```
++ctrl+c++ beendet und hängt den Snapshot wieder aus.
---
## Wer darf was sehen?
Das ist der Punkt, an dem sich diese Oberfläche von einem schnell
hingeworfenen Dateiserver unterscheidet.
### Anmeldung mit den Proxmox-Benutzern
Die Oberfläche zeigt dieselbe Anmeldemaske wie Proxmox — Benutzername,
Passwort, Realm-Auswahl. Geprüft wird über `POST /access/ticket` auf der
lokalen Proxmox-API, also genau den Weg, den auch das Proxmox-Webinterface
geht. Alle Realms (`pam`, `pve`, LDAP, AD …) funktionieren damit automatisch.
Zwei-Faktor-Anmeldungen werden **abgewiesen** statt halb durchgewinkt.
### Ein Passwort allein reicht nicht
Sonst könnte jeder Proxmox-Benutzer sämtliche Dateien aller Gäste lesen.
Zusätzlich muss der Benutzer auf dem jeweiligen Gast das Recht **`VM.Snapshot`**
besitzen — geprüft auf `/`, `/vms`, `/vms/<id>` und dem Pool des Gastes.
In der Gastliste tauchen nur Gäste auf, für die das zutrifft. `root@pam` sieht
wie in Proxmox alles.
Anpassen:
```
--require-privilege VM.Backup # anderes Recht verlangen
--allow-user backup@pve # einzelne Benutzer generell zulassen
--auth token # stattdessen Schlüssel in der Adresse
--auth none # ohne Anmeldung (nur im vertrauten Netz)
```
Ohne Proxmox (`--path`) gibt es keine Benutzer — dort wird automatisch ein
Zugangsschlüssel erzeugt und beim Start als vollständige Adresse ausgegeben.
---
## Bedienung
Snapshot anklicken, durchklicken.
| | |
|---|---|
| **Einzelne Datei** | wird direkt heruntergeladen |
| **Verzeichnis** | kommt als ZIP |
| **Mehrfachauswahl** | ebenfalls als ZIP |
Die ZIP-Dateien werden **im Strom erzeugt** — es wird nichts auf dem Host
zwischengespeichert. Ein 200-GB-Verzeichnis braucht also keinen freien Platz,
nur Geduld.
---
## Parameter
| Parameter | Vorgabe | Bedeutung |
|---|---|---|
| `-P`, `--port <nummer>` | `8823` | Port, auf dem gelauscht wird |
| `-b`, `--bind <adresse>` | `0.0.0.0` | Netzwerkadresse; `127.0.0.1` = nur lokal |
| `-a`, `--auth pve\|token\|none` | `pve` | Anmeldeart |
| `--require-privilege <recht>` | `VM.Snapshot` | nötiges Recht auf dem Gast |
| `--allow-user <user@realm>` | — | dieser Benutzer darf alles (mehrfach möglich) |
| `-t`, `--token <schlüssel>` | zufällig | Zugangsschlüssel selbst vorgeben |
| `--no-token` | — | Kurzform für `--auth none` |
| `-p`, `--path <verzeichnis>` | — | beliebiges Verzeichnis statt eines Snapshots |
| `--cleanup` | — | hängengebliebene Einbindungen lösen und beenden |
| `-v`, `--verbose` | — | ausführliches Protokoll |
| `-V`, `--version` | — | Version anzeigen |
---
## Beispiele
=== "Über einen SSH-Tunnel"
Der sicherste Weg — nichts liegt im Netz offen:
```bash
# auf dem Host
pvesnap-web --bind 127.0.0.1 --port 8823
# am eigenen Rechner
ssh -L 8823:localhost:8823 root@pve
# dann im Browser: http://localhost:8823/
```
Als Dienst: in `web.conf` `--bind 127.0.0.1` setzen.
=== "Ein Team ohne Snapshot-Rechte"
```bash
pvesnap-web --port 8823 --require-privilege VM.Backup
```
Wer sichern darf, darf auch aus einer Sicherung lesen — das ist meist die
passendere Grenze.
=== "Ein einzelner Dienstleister"
```bash
pvesnap-web --port 8823 --allow-user dienstleister@pve
```
Unabhängig von den Proxmox-Rechten. Danach wieder entfernen.
=== "Schnell etwas herausgeben"
```bash
pvesnap-web --port 8823 --auth token
```
Der Zugangsschlüssel steht in der Adresse, die beim Start ausgegeben wird.
Kein Proxmox-Benutzer nötig.
=== "Ein beliebiges Verzeichnis"
```bash
pvesnap-web --path /mnt/restore --port 8823
```
Etwa ein bereits gemountetes Backup. Braucht kein Proxmox.
---
## Sicherheit
!!! danger "HTTP, nicht HTTPS"
Die Verbindung ist **unverschlüsselt**. Passwörter gehen im Klartext über
das Netz.
Über unsichere Netze deshalb immer einen SSH-Tunnel legen — siehe oben.
Innerhalb eines vertrauenswürdigen Verwaltungsnetzes ist es vertretbar, an
einer offenen Firewall-Regel nach draußen nicht.
Was sonst gilt:
* Es wird ausschließlich **gelesen**. Die Oberfläche kann nichts ändern oder
löschen.
* Pfade außerhalb des eingebundenen Snapshots werden abgewiesen — über die
Adresszeile kommt man nicht an den Rest des Hosts.
* **Fehlgeschlagene Anmeldungen** landen mit Absender-IP im Journal:
```bash
journalctl -u pvesnap-web | grep -i "anmeldung\|failed"
```
* Beim Beenden (++ctrl+c++ oder `systemctl stop pvesnap-web`) wird ein offener
Snapshot wieder ausgehängt.
!!! tip "Nicht dauerhaft laufen lassen, wenn nicht nötig"
Wer die Oberfläche nur gelegentlich braucht, installiert sie ohne
Autostart:
```bash
systemctl disable pvesnap-web
systemctl start pvesnap-web # bei Bedarf
```