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.