Files

T

Micha 52fc007123 fix(restore): authelia smoke without dump-restore, drop bogus env, disable ntp

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>

2026-06-03 08:27:40 +02:00

4.7 KiB

Raw Blame History

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 /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 /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.

4.7 KiB Raw Blame History