Micha
52fc007123
Erstlauf 2026-06-03 hat einen by-design-Konflikt offengelegt: pg_restore des
produktiven postgresql17-authelia.dump in eine Test-Instanz mit Wegwerf
AUTHELIA_STORAGE_ENCRYPTION_KEY scheitert im Authelia-Startup-Check mit
"the configured encryption key does not appear to be valid for this database".
Productive Storage-Werte werden mit dem produktiven Key verschluesselt; ein
Wegwerf-Key kann sie nicht entschluesseln. Smoke ist deshalb explizit auf
Config-Restore + Boot reduziert, nicht Daten-Decrypt.
Zwei Nebenbefunde aus demselben Lauf:
- AUTHELIA__SERVER__ADDRESS (Doppel-Underscore) wurde von Authelia 4.39
abgelehnt ("configuration environment variable not expected"). ENV
entfernt; server.address kommt eh aus der generierten configuration.yml.
- ntp-Startup-Check schlug fehl ("Could not determine the clock offset
... lookup time.cloudflare.com on 127.0.0.1:53: server misbehaving"),
weil das isolierte Test-Compose-Netz keinen DNS-Resolver fuer NTP hat.
Neuer Test-Config-Block setzt ntp.disable_startup_check: true.
Doku nachgezogen (Plan + Runbook): Encryption-Key-Konflikt ist explizit
als "nicht Teil dieses Smokes" dokumentiert; Fehler-Matrix hat Eintraege
fuer Doppel-Underscore-ENV und NTP-Lookup.
Frische des produktiven authelia-Dumps wird unveraendert ueber
check-restore-freshness.sh ueberwacht; Daten-Decrypt-Drill ist eine eigene
DR-Aufgabe mit kontrollierter Schluessel-Verwendung.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
87 lines
4.7 KiB
Markdown
87 lines
4.7 KiB
Markdown
# Authelia Restore Runbook
|
|
|
|
## Status
|
|
|
|
Skript und Test-Compose sind als **Scaffold** abgelegt. Erstlauf steht noch aus und braucht Operator-Freigabe. Authelia ist Tier-1-kritisch, deshalb startet dieser Test bewusst konservativ: Smoke-Test prueft nur Config-Validate + HTTP-Health, kein vollstaendiger Auth-Flow.
|
|
|
|
## Vorbedingungen
|
|
|
|
- Borg-Quelle ist verfuegbar
|
|
- `borg-ui`-Container laeuft
|
|
- Borg-Passphrase-Datei vorhanden: `/mnt/user/appdata/secrets/borg_repo_passphrase.txt`
|
|
- `borg-ui` mountet die Passphrase im Container als `/local/secrets/borg_repo_passphrase.txt`
|
|
- aktuelles Borg-Archiv enthaelt `local/appdata/authelia/config`
|
|
- optional: `local/borg-dumps/latest/postgresql17-authelia.dump`
|
|
- Testpfade unter `/mnt/user/backups/restore-lab/` und `/mnt/user/backups/restore-reports/` sind freigegeben
|
|
- Port `127.0.0.1:19091` frei
|
|
- freier Speicher unter `/mnt/user/backups/restore-lab/authelia` (~200 MB reichen)
|
|
|
|
## Bestaetigter Host-Stand (Soll)
|
|
|
|
- produktiver Authelia-Container: `authelia` mit Image `authelia/authelia:4.39.20@sha256:1b363e9279e742397966333f364e0876ae02bf5c876de73e83af6d48c57ff51b`
|
|
- produktiver Config-Pfad: `/mnt/user/appdata/authelia/config`
|
|
- produktive Secrets: `/mnt/user/appdata/secrets/authelia_*.txt` (werden vom Test **nicht** gebraucht)
|
|
- produktive Storage: shared PostgreSQL 18 (wird vom Test **nicht** angesprochen)
|
|
|
|
## Erster Lauf - trockene Variante
|
|
|
|
```bash
|
|
bash /mnt/user/services/homelab-infra/ops/restore-tests/authelia-restore-test.sh --what-if
|
|
```
|
|
|
|
Erwartete Ausgabe: nur Plan-Output, kein Docker-Start, kein Borg-Extract.
|
|
|
|
## Erster Lauf - echter Test (Operator-freigegeben)
|
|
|
|
```bash
|
|
bash /mnt/user/services/homelab-infra/ops/restore-tests/authelia-restore-test.sh --keep-data
|
|
```
|
|
|
|
Bei Erfolg:
|
|
|
|
- Report unter `/mnt/user/backups/restore-reports/authelia-YYYY-MM-DD.md`
|
|
- Restore-Lab-Daten bleiben mit `--keep-data` erhalten
|
|
- ohne `--keep-data` wird das Restore-Lab geloescht; bei Fehler wird es nach `/mnt/user/backups/restore-lab/_failed/authelia-...` verschoben
|
|
|
|
## Smoke-Test-Pruefungen
|
|
|
|
Minimal erwartet im Report:
|
|
|
|
- Borg extract of config: `ok`
|
|
- Test-Postgres healthy
|
|
- `authelia config validate`: `ok`
|
|
- HTTP /api/health status: `200`
|
|
|
|
## Fehlerfaelle
|
|
|
|
| Symptom | Ursache | Massnahme |
|
|
|---|---|---|
|
|
| `config validate` failt mit `notifier` Block | Testkonfig enthaelt mehr als einen Notifier | `test-config/configuration.yml` pruefen; Minimal-Test-Block im Skript anpassen |
|
|
| `config validate` failt mit `session.domain` | aelteres/neueres Schema | Test-`session:`-Block an reales Authelia-Schema anpassen |
|
|
| `config validate` failt mit `access_control` default_policy | Authelia >=4.39 verlangt ohne Rules `two_factor`/`one_factor` | Test-Block ist bereits auf `two_factor` gesetzt; bei weiterer Schema-Aenderung anpassen |
|
|
| HTTP-Timeout 120 s | Authelia haengt in Postgres-Schema-Migration | `docker logs --tail 200 restoretest-authelia` lesen, ggf. Wartezeit erhoehen |
|
|
| `encryption key does not appear to be valid for this database` | jemand hat `pg_restore` des produktiven Dumps wieder eingebaut | `pg_restore` ist seit `2026-06-03` bewusst NICHT mehr Teil dieses Smokes - siehe Plan/Skript-Doku; nicht re-aktivieren ohne kontrollierte Encryption-Key-Choreographie |
|
|
| SMTP-Connect im Log | Testkonfig oder Env erzeugt unerwartet SMTP | `test-config/configuration.yml` und `AUTHELIA_*SMTP*` Env pruefen |
|
|
| `Could not determine the clock offset` | DNS-Lookup `time.cloudflare.com` failt im isolierten Test-Netz | `ntp.disable_startup_check: true` ist im Test-Config-Block bereits gesetzt; bei Aenderung beibehalten |
|
|
| `configuration environment variable not expected: AUTHELIA__SERVER__ADDRESS` | Doppel-Underscore ENV im Compose | seit `2026-06-03` entfernt; `server.address` kommt aus configuration.yml |
|
|
|
|
## Cleanup
|
|
|
|
- bei Erfolg ohne `--keep-data`: `rm -rf /mnt/user/backups/restore-lab/authelia` und Extract-Cache
|
|
- bei Fehler: Datenpfad wird via `preserve_on_failure` nach `/mnt/user/backups/restore-lab/_failed/authelia-...` umbenannt
|
|
|
|
Produktive Authelia-Container, produktive Secrets, produktive Postgres-DB und produktiver SMTP-Account werden niemals beruehrt.
|
|
|
|
## Schedule
|
|
|
|
Aktuell nicht im automatischen Schedule. Vorschlag nach erstem erfolgreichen Lauf: zweimonatlich (2. Samstag in geraden Monaten), damit nicht mit Paperless kollidierend.
|
|
|
|
## Festgelegte Entscheidungen
|
|
|
|
- Test-Compose nutzt denselben Image-Digest wie Produktion.
|
|
- Wegwerf-Secrets ausschliesslich im Test-Compose; niemals produktive Authelia-Secrets einsetzen.
|
|
- Test-Postgres ist isoliert; produktive shared PostgreSQL 18 wird nicht angesprochen.
|
|
- Notifier wird auf Filesystem umgebogen; KEIN echter SMTP-Versand.
|
|
- Test-Port nur auf `127.0.0.1:19091`, keine LAN-/Traefik-Anbindung.
|
|
- Borg-Passphrase wird aus Host-Secret-Datei gelesen und nirgendwo geloggt.
|