bf-infra/CLAUDE.md

BF-Netzwerk — Projekt-Kontext (auto-read)

Standort BF: VLAN-segmentiertes Heimnetz auf MikroTik/RouterOS. Ziel: CAKE/QoS gegen Bufferbloat, DNS/DHCP-Ablösung, WLAN via CAPsMAN, Firewall Least-Privilege, Multi-Site VPN.

Für jede TP-Session: zuerst docs/teilprojekte.md lesen — enthält kanonischen Stand, Scope, Abhängigkeiten und Reihenfolge aller Teilprojekte. Kein anderer Kontext nötig.

---

VLAN-Modell (kanonisch)

VLAN	Name	Subnetz	Zweck
10	MAIN	10.40.10.0/24	Trusted (Handy/Laptop)
20	INFRA	10.40.20.0/24	NAS/VMs/Docker/HA
30	IOT	10.40.30.0/24	Smart-Home
40	MEDIA	10.40.40.0/24	Sonos/AppleTV/TV/Cast
50	UNTRUSTED	10.40.50.0/24	Konsole/Low-Trust
90	GUEST	10.40.90.0/24	nur Internet
99	MGMT	10.40.99.0/24	Switch/AP/Hypervisor-Mgmt
100	WAN	(Arris-Transfer)	zum Arris-Kabelmodem (Liwest, Public-IP)

GW je VLAN = .1 · APs: ap1=.1, ap2=.2 · Switches: ALLNET=.11, Omada=.12

---

Hardware & Zugang

Gerät	IP	Zugang
ALLNET Core-Switch (sw1)	10.40.41.11 (interim, VLAN1)	telnet 10.40.41.11 · User: claudecode · PW: switch/.secrets
Omada Access-Switch (sw2)	10.40.41.12	Web-UI HTTPS · Creds omada/.secrets · Adoption pending
hAP ax² #1 (ap1)	10.40.41.1 (bridge/VLAN1 Mgmt)	MikroMCP (live) · TP4 ✅: L3-Router, GW je VLAN = .1
hAP ax² #2 (ap2)	10.40.41.2	MikroMCP (live) · Port 2 am Omada-Switch
NAS (nas-bf, DS923)	10.40.41.10	SSH · Docker (Portainer endpointId=14)
Omada-Controller	10.40.41.175	https://10.40.41.175:8043 (macvlan auf DS923)
omada-mcp	10.40.20.176	StreamableHTTP http://10.40.20.176:3000/mcp · MCP in Claude Code ✓ (pve-LXC) · TP14.2 2026-07-10: .41→.20, OMADA_BASE_URL→.20.175
pve-mcp	10.40.20.173	StreamableHTTP http://10.40.20.173:3000/ (Root-Pfad, NICHT /sse) · NAS-Stack ep14 (=nas-bf .20.10, NICHT LXC .126!) id 202 (vlan20-only, TP14.1 2026-07-10) · mcp-pve v0.6.1 (Upgrade 2026-07-10: Single-Session-Bug 0.4.8 „Server already initialized" gefixt, TP14.2a) · ~/.claude.json ✓
Proxmox (pve)	10.40.41.100	kein SSH-Key konfiguriert
Docker-LXC (auf pve)	10.40.20.126	Portainer CE 2.40.0 (https://10.40.20.126:9443) · TP14.2 2026-07-10: LXC 400 net0 tag=20/.20.126 (iface heißt jetzt veth20, NICHT eth0); Docker-Netz vlan20=ipvlan parent veth20; adguard_bf1 .20.16, adguard_fm2 .20.17
Mac mini	10.40.41.167	ssh macmini
Arris-Kabelmodem	(Bridge-Mode, keine Mgmt-IP im BF-LAN)	Liwest-Edge, physisch an sw1 gi16 · FritzBox 6660 seit 2026-07-01 komplett ausgebaut (Liwest-Tausch, kein Zurück); Telefonie war auf der FB und wird nicht weitergeführt

---

Tooling

• MikroTik (hAP ax²): MikroMCP-Server live verbunden → mcp__mikromcp__*-Tools verwenden. Reads immer safe; Writes mit dryRun:true previwen, dann apply_plan.
• ALLNET-Switch: kein MCP — nur Telnet-CLI (IOS-artig, FW 2.2.1). Runner: cd ~/dev/bf-network-r6/switch && . ./.secrets && expect cli/run-cli.exp cli/<datei>.cli Klickanleitungen in switch/ui-guides/ für manuelle Schritte.
• Omada-Switch: Controller https://10.40.20.175:8043 (TP2 ✅). Adoption ✅. Port-Config: manuell im Browser. omada-mcp live auf pve-LXC (.20.176, StreamableHTTP /mcp, MCP in Claude Code ✓).
• Docker-Management: Portainer API https://10.40.20.126:9443, Key in mcp/portainer/.env. Ablösung durch Komodo (native MCP) geplant.

---

Kritische Gotchas

• ALLNET: nur 1 Telnet-VTY — stale Sessions blockieren ~15 min. Sauber ausloggen (exit exit), nie hammern.
• save nicht vergessen nach ALLNET-Änderungen (sonst nach Reboot weg).
• hAP ax² hat 128 MB Flash, kein USB → Container NICHT auf dem Router; Container laufen auf NAS/pve.
• VLAN20-Docker-Hosts: Host-DNS nach dem Umzug prüfen (2026-07-10, TP14.2a): NAS + pve-LXC zeigten /etc/resolv.conf noch auf totes .41.254 → docker pull ghcr scheitert (EAI_AGAIN, aber Egress ok!). Fix = .20.1: LXC pct set 400 --nameserver 10.40.20.1; Synology-Falle: DSM-„Allgemein"-DNS ≠ was dockerd liest — Interface zieht DNS per DHCP → Fix an der Netzwerkschnittstelle „DNS manuell". Laufende Container frieren den 127.0.0.11-Upstream zum Erstellzeitpunkt ein (Recreate nötig). Merkregel: docker-pull-hängt + dns.lookup EAI_AGAIN aber TCP zu ghcr-IP:443 ok = toter Resolver, nicht Egress.
• ALLNET VLAN-DB final (TP1 ✅): 40=MEDIA, 50=UNTRUSTED; GE1/GE2/GE8 alle als Trunk mit 10/20/30/40/50/90/99/100.
• Omada-Switch Port 2 = ap2 (Trunk all VLANs), Uplink-Port → ALLNET GE8 (Trunk all), Restports = Access.
• Mesh = NEIN (beide APs haben wired Trunk-Uplink → Loop-Risiko).
• ap2 (CAP) braucht vlan-filtering=yes mit ether2-Trunk (TP3.1 ✅ 2026-07-01): local forwarding → datapath.vlan-id wird nur bei vlan-filtering auf die Leitung geschrieben. Ohne → ALLE ap2-WLAN-Clients ungetaggt in VLAN1 (defconf/10.40.41.x). Nur Master-Radios wifi1/wifi2 sind Bridge-Ports (Slave-VAPs forwarden darüber) → wifi1/wifi2 müssen manuell tagged-Member je Client-VLAN sein (CAPsMAN legt das auf dem CAP NICHT an). As-built routeros/tp3.1-ap2-vlan.rsc. VLAN1 MUSS untagged=bridge,ether2 bleiben (Mgmt/MCP-Pfad 10.40.41.2, kein Scheduler → Recovery = Power-Cycle OG). Widerlegt „ein CAP hält keine Config" (galt nur für Manager-Forwarding).
• mgmt-VLAN-Wechsel am Switch = Lockout-Risiko: VLAN muss existieren + Port muss es tragen, in einem Schritt.
• Omada ES208G = Easy Managed → Controller-adoptierbar (ab 6.1.x), nur Basis-VLAN/QoS im Controller (kein ACL/Policy-Routing).
• TP4 ✅: ap1 ist L3-Router. Bridge mit vlan-filtering=yes; VLAN1 untagged (Mgmt/Transition); vlan10-99 Subinterfaces mit DHCP+DNS. DNS: 13 statische A-Records bf.lan, Upstream seit 2026-06-16 = DoH Cloudflare Gateway (servers=1.1.1.1 Bootstrap). Omada-PVID-Fix (→ .10/.20-Subnetze) ist nächster Schritt.
• ✅✅ Edge-Cutover vollzogen (2026-07-01): FritzBox komplett ausgebaut, Arris-Kabelmodem im Bridge-Mode. Liwest hat die FB6660 dauerhaft gegen ein Arris-Kabelmodem getauscht (physisch weg, kein Zurück). WAN läuft über den Core-Switch (Arris→sw1 gi16 Access VLAN100→gi15 Trunk→ap1 ether2→vlan100 auf bridge), NICHT über ether1. ap1 zieht öffentliche Liwest-IP direkt → Double-NAT weg, ap1 = Public-Edge. Vorarbeit dazu: TP10 (beide VPN FM/DW von FB auf ap1-WG-Hub migriert, 2026-06-27) hat den Bridge-Mode entblockt. Telefonie war auf der FB und wird nicht weitergeführt (User-Bestätigung 2026-07-02). Details/Runbooks: routeros/wan-cutover-runbook.md.
• ap1 RouterOS-Scripting (device-mode=home): scheduler + fetch blockiert (not allowed by device-mode) → keine Scheduler in Scripts, Autonomie via Loop-Script. [/ping] gibt nil in 7.23, ICMP geblockt → Reachability via :resolve (server=1.1.1.1 = Routing-Test, ohne server = DoH). MikroMCP-Tools können droppen → Fallback REST http://10.40.41.1/rest (Creds = ROUTER_AP1 in ~/.claude.json).
• WLAN dozende Legacy-Clients nur auf ap1 erreichbar, NICHT via CAP ap2 (2026-07-02, P750W-Fall): L3-GW liegt auf ap1 → ARP-Broadcast an schlafenden Client wird nur am co-located AP zuverlässig zugestellt; Remote-CAP ap2 puffert Broadcast-ARP unzuverlässig. Fix = geordneter wifi-access-list-Pin auf ap1 (0 accept interface=w2-iot → 1 reject ohne Interface = überlebt ap2-Re-Provision). Merkregel: DHCP-geht-aber-Ping-nicht = ARP/Power-Save, NICHT Routing/L2/MTU/Switch. Coverage-Kanten/Terrasse grenzwertig (−76..−89 dBm, 4-Radio-Ping-Pong); TX schon am AT-Max (18/15 dBm, kein Hebel); Steering neighbor-group=bf-main gesetzt; echter Fix = Platzierung (offen, Tageslicht). SSoT docs/wifi-p750w-coverage-and-map.md.