proxmox-snapshot-service/handbuch/docs/nachschlagen/konfiguration.md

# 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}
```