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>
2026-08-09 12:39:30 +02:00
parent c484596702
commit 59e7224297
72 changed files with 7355 additions and 2 deletions
@@ -0,0 +1,256 @@
+# Alle Einstellungen
+
+Die Datei liegt unter `/etc/pvesnap/pvesnap.conf` und ist eine gewöhnliche
+INI-Datei mit drei Arten von Abschnitten:
+
+```ini
+[global]           # gilt für alles
+[defaults]         # Vorgaben für alle Gruppen (optional)
+[group:NAME]       # eine Gruppe, beliebig viele davon
+```
+
+Nach jeder Änderung:
+
+```bash
+pvesnap check
+systemctl reload pvesnap
+```
+
+!!! note "Zeitangaben"
+
+    Überall dasselbe Format: `30s`, `15m`, `1h`, `6h`, `2d12h`, `1w`.
+    `0` heißt „unbegrenzt" bzw. „keine".
+
+!!! note "Kommentare am Zeilenende"
+
+    Hinter jedem Wert darf ein Kommentar stehen:
+
+    ```ini
+    keep_time = 7d      # eine Woche
+    ```
+
+    Einzige Ausnahme ist `description` — dort bleibt die Zeile unverändert,
+    damit ein `#` in der Beschreibung erhalten bleibt.
+
+---
+
+## `[global]`
+
+| Schlüssel | Vorgabe | |
+|---|---|---|
+| `prefix` | `auto` | Namenspräfix aller pvesnap-Snapshots. Bestimmt zugleich, was jemals gelöscht wird — siehe [Namensschema](../sichern/index.md#namensschema). |
+| `check_interval` | `60s` | wie oft der Dienst nach Fälligem schaut |
+| `state_file` | `/var/lib/pvesnap/state.json` | merkt sich die letzten Läufe |
+| `log_level` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `log_file` | — | zusätzliche Protokolldatei; ohne sie geht alles ins Journal |
+| `task_timeout` | `15m` | Geduld mit einem einzelnen Proxmox-Task |
+| `retries` | `2` | zusätzliche Versuche, wenn eine Sperre belegt ist |
+| `retry_delay` | `60s` | Wartezeit vor dem nächsten Versuch |
+| `pause_between` | `0s` | Pause zwischen zwei Gästen |
+| `run_on_start` | `no` | beim Dienststart sofort einen Durchlauf machen |
+| `dry_run` | `no` | `yes` = nichts wirklich tun, nur protokollieren |
+| `description` | siehe unten | Standard-Beschreibung aller Snapshots |
+
+```ini
+[global]
+prefix = auto
+check_interval = 60s
+state_file = /var/lib/pvesnap/state.json
+log_level = INFO
+task_timeout = 15m
+retries = 2
+retry_delay = 60s
+pause_between = 0s
+run_on_start = no
+dry_run = no
+description = pvesnap | Gruppe: {group} | erstellt: {datetime} | Vorhaltezeit: {keep_time} | max: {keep_count}
+```
+
+---
+
+## `[defaults]`
+
+Vorgaben für **alle** Gruppen. Jede Gruppe darf sie einzeln überschreiben.
+
+```ini
+[defaults]
+enabled = yes
+skip_stopped = no
+vmstate = no
+```
+
+Erlaubt sind hier dieselben Schlüssel wie in einer Gruppe.
+
+!!! warning "Der Editor löst `[defaults]` auf"
+
+    Beim Speichern im [ncurses-Editor](../sichern/editor.md) verschwindet der
+    Abschnitt — die Werte stehen danach in jeder Gruppe einzeln. Inhaltlich
+    ändert sich nichts.
+
+---
+
+## `[group:NAME]`
+
+### Allgemein
+
+| Schlüssel | Vorgabe | |
+|---|---|---|
+| `enabled` | `yes` | Gruppe aktiv. In der Auslieferung stehen alle auf `no`. |
+
+### Zeitplan
+
+Entweder `interval` **oder** `schedule` — nicht beides.
+
+| Schlüssel | Vorgabe | |
+|---|---|---|
+| `interval` | — | `30m`, `1h`, `6h`, `2d12h`, `1w` |
+| `align` | `no` | `yes` = an der Uhr ausgerichtet (00:00, 00:30 …) |
+| `schedule` | — | `hourly`, `daily`, `weekly`, `monthly`, `yearly` |
+| `at` | — | Uhrzeit `HH:MM` bei `daily` und größer |
+| `minute` | `0` | Minute bei `hourly` |
+| `day_of_week` | `mo` | `mo di mi do fr sa so` bei `weekly` |
+| `day_of_month` | `1` | 1–31 bei `monthly`; zu große Werte fallen auf den Monatsletzten |
+| `month` | `1` | 1–12 bei `yearly` |
+
+Einzelheiten unter [Zeitpläne](../sichern/zeitplan.md).
+
+### Vorhaltezeit
+
+| Schlüssel | Vorgabe | |
+|---|---|---|
+| `keep_count` | `0` | höchstens so viele je VM und Gruppe (`0` = unbegrenzt) |
+| `keep_time` | `0` | nichts älter als (`0` = unbegrenzt) |
+| `keep_min` | `0` | so viele bleiben in jedem Fall stehen |
+
+**Mindestens eine von `keep_count` und `keep_time` muss gesetzt sein.**
+Einzelheiten unter [Vorhaltezeit](../sichern/vorhaltezeit.md).
+
+### Auswahl der Gäste
+
+| Schlüssel | Vorgabe | |
+|---|---|---|
+| `all` | `no` | alle VMs und Container |
+| `vmids` | — | `100,101,105-110` |
+| `names` | — | `web-*, db-0?` — mit `*`, `?`, `[abc]` |
+| `tags` | — | `produktion, wichtig` |
+| `pools` | — | `Kunden` |
+| `types` | — | `qemu` oder `lxc`; leer = beides |
+| `exclude_vmids` | — | |
+| `exclude_names` | — | |
+| `exclude_tags` | — | |
+
+Einschlüsse wirken als **ODER**, Ausschlüsse gewinnen immer. Einzelheiten unter
+[Welche Gäste?](../sichern/auswahl.md).
+
+### Snapshot-Optionen
+
+| Schlüssel | Vorgabe | |
+|---|---|---|
+| `vmstate` | `no` | Arbeitsspeicher mitsichern — nur QEMU, nur bei laufender VM |
+| `skip_stopped` | `no` | gestoppte Gäste überspringen |
+| `description` | aus `[global]` | eigene Beschreibung für diese Gruppe |
+
+---
+
+## Platzhalter der Beschreibung
+
+| | | |
+|---|---|---|
+| `{group}` | Name der Gruppe | `täglich` |
+| `{group_slug}` | Kurzname im Snapshot | `taeglich` |
+| `{vmid}` | VMID | `101` |
+| `{name}` | Name des Gastes | `db01` |
+| `{type}` | `VM` oder `LXC` | `VM` |
+| `{node}` | Cluster-Knoten | `pve1` |
+| `{pool}` | Proxmox-Pool | `Hausnetz` |
+| `{tags}` | Tags des Gastes | `produktion,datenbank` |
+| `{date}` | Datum | `2026-08-09` |
+| `{time}` | Uhrzeit | `02:30:00` |
+| `{datetime}` | beides | `2026-08-09 02:30:00` |
+| `{timestamp}` | Unix-Zeit | `1786257000` |
+| `{keep_time}` | Vorhaltezeit der Gruppe | `3w` |
+| `{keep_count}` | Anzahl | `14` |
+| `{schedule}` | Zeitplan im Klartext | `täglich um 02:30` |
+
+Ein unbekannter Platzhalter führt nicht zum Abbruch — dann wird eine
+Ersatzbeschreibung eingesetzt.
+
+---
+
+## Deutsche Schreibweisen
+
+Damit die Datei lesbar bleibt, versteht pvesnap eine Reihe deutscher Synonyme:
+
+| deutsch | entspricht |
+|---|---|
+| `aktiv`, `aktiviert` | `enabled` |
+| `intervall` | `interval` |
+| `zeitplan` | `schedule` |
+| `uhrzeit`, `zeit` | `at` |
+| `wochentag` | `day_of_week` |
+| `monatstag` | `day_of_month` |
+| `monat` | `month` |
+| `anzahl`, `max_anzahl`, `behalte_anzahl` | `keep_count` |
+| `vorhaltezeit`, `behalte_zeit`, `max_alter` | `keep_time` |
+| `mindestens` | `keep_min` |
+| `alle` | `all` |
+| `namen` | `names` |
+| `typen` | `types` |
+| `beschreibung` | `description` |
+| `ausschluss_vmids` | `exclude_vmids` |
+| `ausschluss_namen` | `exclude_names` |
+| `gestoppte_ueberspringen` | `skip_stopped` |
+
+Bindestriche und Unterstriche sind austauschbar, Groß- und Kleinschreibung egal.
+
+---
+
+## Eine vollständige Beispieldatei
+
+```ini
+[global]
+prefix = auto
+check_interval = 60s
+state_file = /var/lib/pvesnap/state.json
+log_level = INFO
+task_timeout = 15m
+retries = 2
+retry_delay = 60s
+pause_between = 0s
+run_on_start = no
+dry_run = no
+description = pvesnap | Gruppe: {group} | erstellt: {datetime} | Vorhaltezeit: {keep_time} | max: {keep_count}
+
+[defaults]
+enabled = yes
+skip_stopped = no
+vmstate = no
+
+[group:stuendlich]
+interval = 1h
+align = yes
+keep_count = 24
+keep_time = 2d
+keep_min = 1
+tags = stuendlich
+skip_stopped = yes
+
+[group:taeglich]
+schedule = daily
+at = 02:30
+keep_count = 14
+keep_time = 21d
+keep_min = 1
+tags = produktion
+exclude_tags = nosnap
+
+[group:monatlich]
+schedule = monthly
+day_of_month = 1
+at = 04:00
+keep_count = 6
+keep_time = 400d
+all = yes
+exclude_tags = nosnap, pvesnap-recovery
+description = Monatssicherung {name} ({vmid}) vom {date}
+```