bf-infra/docs/handoff-20260826-agh-dns-cutover.md

Übergabe — nächste Session: AdGuard DNS-Cutover fortsetzen (TP23 Stufe 2 ∥ TP31 Schritt 4)

Entstanden am 2026-08-26. Die Handoff 20260825-agh-dns-cutover.md wurde begonnen und teilweise abgearbeitet. Diese Datei führt den neuen Stand fort. Keine Config-Transaktion offen.

Ausgangslage

✅ Erledigt in dieser Session (2026-08-26):

Was	Stand
opencode.jsonc	Permission "allow", MCPs: gitea-mcp, mikromcp, pve-mcp, home-assistant, cloudflare (OAuth)
docs/teilprojekte.md	Quick-Index-Tabelle eingebaut (1-Read-Statusbaum), hass-400-Fix vermerkt
CLAUDE.md	TP-Management-Regel: vorschlagen → abstimmen → anlegen
.opencode/commands/handoff.md	/handoff-Custom-Command (generate + resume)
LXC 110 agh-bf1	pve, Debian 13, 10.40.20.36, 4 GB / 512 MB / 2 Cores, onboot=1, startup order=10
LXC 111 agh-bf2	pve, Debian 13, 10.40.20.37, 4 GB / 512 MB / 2 Cores, onboot=1, startup order=10
Backup-Job	Beide VMIDs im Job backup-6dcf5c10-610f (pbs, sonntags 01:00)
AdGuard v0.107.79	Installiert auf 110 + 111 (offizieller Installer)
AGH-Konfig	docs/transaktionen/agh-bf1-AdGuardHome.yaml — 28 Rewrites (16 Caddy-Sites → .40, 8 Hosts → live-IPs), conditional upstream [/bf.emsenhuber.net/], Admin-PW wie altes adguard_bf1

Entscheidungen getroffen:

• (a) bf.lan → bf.emsenhuber.net heben (Domain-Wechsel im DHCP + conditional upstream)
• (b) FM beantwortet BF-Namen künftig nicht selbst, sondern fragt nach BF — Paar-Sync löst die toten VLAN1-Antworten
• tv = 10.40.40.11 (Reservierung bestätigt), appletv/vuplus → streichen (keine Reservierung/ARP)

IPs vergeben (alle .36/.37): ARP auf vlan20 geprüft — beide frei (keine Kollision).

🔴 AKTUELLER BLOCKER: AGH startet nicht

Symptom: --check-config meldet yaml: construct errors: line 33: cannot construct !!seq into string
Ursache: AdGuard Home v0.107.79 schreibt die AdGuardHome.yaml beim Start selbst neu (alphabetische Schlüsselreihenfolge) und verschachtelt dabei bootstrap_dns von flach auf - - 1.1.1.1 / - 1.0.0.1 — ein Format, das es selbst nicht mehr parsen kann. Zirkelschluss.
Versuchter Fix: Datei direkt schreiben → start → AGH korrumpiert sie erneut.

🔑 Empfohlener Weg für die nächste Session:
AGH nicht über YAML-Datei einrichten, sondern über die HTTP-API im First-Run-Wizard-Modus:

1. AGH stoppen (systemctl stop AdGuardHome), AdGuardHome.yaml löschen.
2. Starten → AGH läuft im Wizard-Modus auf Port 3000 (kein Admin-Login nötig).
3. POST /control/install/configure mit Admin-PW + DNS-Config (upstreams, filter, bootstrap).
4. POST /control/rewrite/add für jeden der 28 Rewrites (oder Bulk-POST).
5. POST /control/dns_config für cache_size, refuse_any, enable_dnssec etc.
6. Nach erfolgreichem Setup: die resultierende YAML von 110 → 111 kopieren, und auf 111 POST /control/install/configure mit denselben Werten.
7. Beide YAMLs ins Repo committen (unter adguard/AdGuardHome.yaml o.ä.).

Alternativer Weg (einfacher): Docker-Container auf pve (Muster wie LXC 400) mit adguard/adguardhome:latest — genau das Image, das produktiv auf adguard_bf1 läuft und dort klaglos startet. Die LXCs sind schon da, ein docker compose darin wäre minimaler Aufwand. Entscheidung gehört dem User.

Noch offene Schritte (aus dem ursprünglichen Auftrag)

Der Handoff 20260825-agh-dns-cutover.md (192 Zeilen) bleibt vollständig gültig — alle Punkte dort gelten weiter. Zusammenfassung der noch offenen Schritte:

1. AGH zum Laufen bringen (API- oder Docker-Weg, s.o.)
2. Rewrites auf beiden Instanzen identisch (Paar-Sync = eine Quelle)
3. Firewall zuerst (Fund 3 des Original-Handoffs):
   • TP5-E2: LAN->AGH dns (.16) → umziehen auf das Paar .36/.37
   • Über Golden Config (Core ist GC-only), nicht ad hoc
   • --refresh-compliance vor dem Cutover
4. Testen: dig @10.40.20.36 vw.emsenhuber.net (erwartet .40), dig @10.40.20.36 <lease> (erwartet Core-Antwort), aus anderem VLAN
5. VLAN für VLAN umstellen (20→10→Rest→30 IoT zuletzt):
   • Vor jedem Flip lease-time auf ~10 min senken
   • dns-server auf .36,.37 umstellen
   • Abnahme: frische DHCP-Lease, nicht ping
6. Domain-Wechsel bf.lan → bf.emsenhuber.net: /ip dhcp-server network set → domain=bf.emsenhuber.net (alle 7). Conditional upstream im AGH zeigt bereits auf [/bf.emsenhuber.net/].
7. Rollback: Core bleibt bis Session-Ende unangetastet als Rückfallebene (DNS und DoH laufen dort weiter).
8. Danach (TP31 Schritt 5–6): Tunnel bf-public + cloudflared auf ap1/ap2, CNAMEs umhängen, alte Tunnel + Container abbauen.

Einstieg für die nächste Session

1. Diese Datei lesen → docs/handoff-20260826-agh-dns-cutover.md
2. docs/teilprojekte.md → Quick-Index-Block (Zeilen ~174–200)
3. Original-Handoff: docs/handoff-20260825-agh-dns-cutover.md (192 Zeilen, alle Details)
4. AGH zum Laufen bringen (API- oder Docker-Weg, s.o.) — das ist der erste technische Schritt.
5. LXC-Zugang: ssh root@10.40.20.100 "pct exec 110 -- bash"
6. Referenz-Config: docs/transaktionen/agh-bf1-AdGuardHome.yaml (236 Zeilen, lokal)

Fallen, die schon bezahlt sind

• AGH-YAML-Datei-Kampf ist verloren — API-Weg oder Docker.
• pvesm free scheitert an geschützten PBS-Snapshots stillschweigend (Merkregel aus TP31).
• Ein Statuscode vom öffentlichen FQDN beweist nichts (Access-Login maskiert tote Dienste).
• pct push liest vom pve-Host, nicht lokal — Datei erst per scp auf pve, dann push.
• bf.lan-Suffix vs. bf.emsenhuber.net: der conditional upstream muss zum DHCP-domain-Wert passen. Beim Domain-Wechsel beides synchron ändern, sonst brechen Lease-Namen.