Initial import from bf-network-r6.opencode — opencode migration

docs/wifi-access-list-erklaert.md

@@ -0,0 +1,92 @@
+# Die WLAN-`access-list` — von Grund auf erklärt
+
+> **Warum es dieses Dokument gibt:** die `access-list` taucht in diesem Projekt an drei Stellen auf
+> (TP25 Fund E, der Mess-Pin `tp25-pin-s22.sh`, der gescheiterte DTU-Versuch vom 2026-08-23) — und sie
+> ist genau das Werkzeug, mit dem man sich still ins Knie schießt, wenn man ihr Wesen nicht kennt.
+> Stand 2026-08-23.
+
+## In einem Satz
+
+Die `access-list` ist eine **Türsteher-Liste am WLAN**: für jeden Client, der sich anmelden will, geht
+sie von oben nach unten durch und entscheidet **ja oder nein** — pro AP, pro Funkschnittstelle, pro
+Gerät.
+
+## Wo sie lebt
+
+`/interface wifi access-list` — und bei uns **auf dem Manager `crs326-core`**, nicht auf den APs.
+Unter CAPsMAN besitzen ap1/ap2 ihre Radios nicht; sie fragen den Manager. *(Dieselbe Regel wie bei der
+Registration-Table: der Manager führt die Tabellen.)*
+
+## Der eine Satz, den man wirklich verstehen muss
+
+> 🔴 **Eine `access-list`-Regel kann einem Gerät nur „nein" sagen. Sie kann es nicht irgendwo
+> hinschicken.**
+
+Das klingt trivial und ist die Quelle fast aller Überraschungen. Wer einen Client „auf ap2 umziehen"
+will, verbietet ihm in Wahrheit **ap1** — und hofft, dass er von selbst zu ap2 geht. Ob er das tut,
+entscheidet **das Gerät**, nicht der Router:
+
+| Gerätetyp | Reaktion auf ein `reject` |
+|---|---|
+| Telefon, Laptop | sucht sofort einen anderen AP → der Umzug klappt |
+| einfaches IoT-Gerät | hängt am gespeicherten AP fest, versucht es weiter — **oder gibt ganz auf** |
+
+**Am 2026-08-23 live erlebt:** der PV-Wechselrichter wurde auf ap1 abgewiesen, ging **nicht** zu ap2,
+und kam auch nach dem Entfernen der Sperre nicht zurück. Er musste über die Hersteller-App neu
+provisioniert werden. Zehn Minuten Ausfall der PV-Telemetrie. **Ein „nein" an ein Gerät ohne
+Suchlogik ist ein Abschalten.**
+
+## Wann sie greift
+
+**Nur im Moment der Anmeldung** (Association) — nicht laufend. Zwei Folgen:
+- Eine neue Regel wirft bestehende Verbindungen **nicht automatisch** raus … *außer* RouterOS wertet
+  sie neu aus, was es bei Änderungen an der Liste tut: im Log steht dann
+  `disconnected, access-list changed`.
+- Wer eine Regel testet, muss den Client **einmal trennen**, sonst misst er den alten Zustand.
+
+## Was eine Regel matchen kann
+
+| Feld | Bedeutung |
+|---|---|
+| `mac-address` | genau ein Gerät |
+| `interface` | ein bestimmtes Radio bzw. eine bestimmte SSID (bei uns `cap-wifiN` / `cap-wifiN-virtualM`) |
+| `signal-range` | **nur Clients innerhalb dieses dBm-Fensters** — das Werkzeug gegen klebende Clients |
+| `time` | Uhrzeit/Wochentag |
+
+Und als Aktion im Kern: **`accept`** oder **`reject`**. Dazu kommt eine Besonderheit, die
+kein Verbot ist, sondern eine Ausnahme: eine Regel kann einem einzelnen Gerät ein **eigenes
+WLAN-Passwort** zuweisen (`passphrase`) — der Trick, mit dem sich ein PSK-Wechsel ohne Stichtag machen
+lässt (neues Passwort aufs Profil, Altgeräte übergangsweise per MAC mit dem alten weiter).
+
+## Die drei Dinge, für die wir sie brauchen
+
+1. **Signal-Boden gegen klebende Clients** (TP25 „Fund E"). Ein Client, der bei −85 dBm an einem
+   fernen AP klebt, obwohl zwei Meter weiter ein besserer steht, wird mit einem `signal-range`-Fenster
+   frühzeitig abgewiesen — er sucht sich dann den stärkeren. ⚠️ **Wirkt nur, wenn es einen besseren AP
+   gibt.** Auf der Terrasse gab es keinen; dort hätte ein Boden die Lage *verschlechtert*.
+2. **Messen** (`tp25-pin-s22.sh`): ein Testgerät gezielt auf **einen** AP zwingen, um den Gegen-AP zu
+   vermessen. Genau hierfür ist sie gebaut — Testgeräte haben Suchlogik.
+3. **PSK-Wechsel ohne Flag-Day** (s. `passphrase` oben) — vorgemerkt für die Rotation.
+
+## Governance in diesem Projekt
+
+Seit **2026-08-23** steht `/interface wifi access-list` unter der ComplianceRule `wifi-access-list`.
+Das heißt: **jeder Eintrag erzeugt Drift** und gehört als Transaktion geführt
+(`nautobot/gc-transaktion.py begin …`), sonst sieht ein Versuch aus wie ein Versehen.
+Der Soll-Zustand ist **leer**.
+
+## Merkregeln, jede aus einem echten Fehlgriff
+
+- 🔴 **`reject` ist kein Umzug, sondern ein Rausschmiss.** Vorher fragen: *kann und will dieses Gerät
+  woanders hin?*
+- 🔴 **Signalstärke ist kein Nachweis für Assoziationsfähigkeit.** „Der andere AP hört ihn mit −59 dBm"
+  belegt einen Funkpfad — nicht, dass das Gerät dort hingeht.
+- 🔴 **Ein abgewiesener Verbindungsversuch ist in Ping-Daten nicht von einem Funkloch zu
+  unterscheiden**, und der Manager protokolliert ihn auf `info`-Ebene **gar nicht**. Wer mit einem Pin
+  misst, braucht eine eigene Alarmierung für „Gerät hängt nirgends".
+- 🔴 **Die `cap-wifiN`-Nummern sind nicht stabil** — sie werden in der Reihenfolge vergeben, in der
+  sich die CAPs anmelden. Eine Regel, die auf `cap-wifi4` zeigt, kann nach einem AP-Neustart ein
+  anderes Radio meinen. **Vor jedem Eingriff die Zuordnung über `radio-mac` neu bestimmen.**
+  ⚠️ Besonders relevant, sobald die zwei neuen APs dazukommen: dann wird neu durchnummeriert.
+- ⚠️ **Für den PV-Wechselrichter ist die Liste gesperrtes Gebiet** — nicht wegen des Kanals, sondern
+  weil er nach einem `reject` aufgibt und einen Vor-Ort-Einsatz braucht.