# WireGuard-Modul · Athena Deck 0.2 ## Was eingebaut ist Einstellungen → Netzwerk bietet Installation, Conf-Import, Aktivieren/Deaktivieren, Handshake-Status und die Modi **LAN**, **Tunnel**, **beides**. Diese Modi gelten für die Server-Instanz von Athena Deck und alle ihre `/api/v1/*`-Endpunkte. Produktive Router-, Modell-, Audio- und Bild-Endpunkte werden nicht übernommen. Die lokale Mac-Instanz bleibt ein separater SSH-Verwaltungskanal. Die Implementierung benutzt einen eigenen Container `athena-deck-network` mit eigenem Netzwerk-Namespace. Im Container laufen ein eingeschränkter Root-Helper und die Webanwendung unter UID/GID 65534. Der Webprozess erhält keinen Docker-Socket und keinen Root-Zugriff. Der Helper erlaubt über seinen Unix-Socket nur fest implementierte Netzwerkaktionen. Er nimmt keine Shell-Befehle entgegen. WireGuard-Pakete werden automatisch im Container-Image installiert. Docker und WireGuard-Kernelunterstützung müssen auf dem Host vorhanden sein; Athena hat beides. Kein `apt` auf dem Host, kein Kernel-Update, kein Reboot, kein Host-Netzwerkmodus, keine Änderungen am bestehenden Gateway oder dessen Konfiguration. Docker erstellt seine üblichen Regeln für den **neuen** Container und seine Port-Veröffentlichung; eine Aussage „keinerlei Netzwerkänderung“ wäre dafür falsch. ## Einrichtung in der Oberfläche 1. Auf dem Mac http://127.0.0.1:8108/#network öffnen. 2. Eigenes Deck-Passwort (mindestens 16 Zeichen) vergeben und **Modul auf Athena installieren** wählen. Installation läuft asynchron und meldet ihren Status. 3. Eigene IPv4-WireGuard-Conf importieren. **Einen eigenen Peer verwenden**, nicht die Konfiguration des produktiven Athena-Gateways wiederverwenden. 4. WireGuard aktivieren. Erst ein Handshake innerhalb der letzten 180 Sekunden führt zum Status „Verbunden“. Ein geladenes Interface alleine genügt nicht. 5. Gewünschten Zugriffsmodus testen, die Zieladresse öffnen, dort anmelden und innerhalb von 120 Sekunden bestätigen. Tunnel/beides muss über den Tunnel, LAN über den LAN-Zugang bestätigt werden. Der Mac-Verwaltungskanal kann diese Bestätigung nicht ersetzen. Ohne Bestätigung wird der vorige Modus wiederhergestellt. Gespeichert wird nur der bestätigte Modus; ein Container-Neustart während der Testphase verwirft den Versuch. Bei Tunnelausfall im bestätigten Tunnel-Modus bleibt der LAN-Zugang geschlossen. Deaktivieren entfernt nur das Deck-WireGuard-Interface; der Zugriffsmodus bleibt. Die Zugriffspolitik steuert **eingehende Verbindungen**, nicht sämtlichen ausgehenden Verkehr des Servers. Die Host-/Container-Standardroute bleibt bestehen. ## Zugang, Installation und Wiederherstellung Fester Zielhost für den aktuellen Prototyp: SSH `root@192.168.1.212`, vorhandener Schlüssel `~/.ssh/athena_key`, strikte Hostschlüsselprüfung. Keine Passwörter oder Schlüssel in Kommandozeilenargumenten, API-Antworten oder Logs. Installation unter `/opt/athena-deck/source` und `/opt/athena-deck/state`. Der Installer prüft Port 8110 und bindet ihn an `127.0.0.1` und die ermittelte private LAN-Adresse; er veröffentlicht nicht auf `0.0.0.0`. Auf Athena war die LAN-Adresse beim Test `172.21.117.202`, während `192.168.1.212` zum vorhandenen VPN-Zugang gehört. Die tatsächliche ermittelte LAN-URL erscheint in der GUI. Eine DHCP-Adressänderung erfordert eine gezielte Neuerstellung der Portbindung. Ein vorhandener Container oder vorhandene Zugangsdaten werden nicht überschrieben. Bei einem fehlgeschlagenen Erststart bleibt der geschützte Installationsstand zur gezielten Wiederherstellung liegen. Automatische Updates/Reparatur bestehender Installationen sind noch nicht implementiert. Der neue Server verwendet aktuell HTTP. WireGuard schützt den Tunneltransport. Für Einrichtung und Secrets aus entfernten Netzen den lokalen Mac-Verwaltungskanal (SSH) verwenden. LAN-HTTP nur in einem vertrauenswürdigen Netz verwenden; HTTPS/Reverse-Proxy-Zertifikate sind noch nicht enthalten. Passwort wird mit PBKDF2-SHA256 (600.000 Iterationen, individuellem Salt) gespeichert. Sitzungen sind HttpOnly/SameSite=Strict, acht Stunden gültig und werden nach Neustart ungültig. Ein Anmeldelimit begrenzt Versuche auf zehn pro Minute. Kein Standardpasswort. Im LAN-/Beides-Modus ist zusätzlich ein SSH-Tunnel zur Server-GUI möglich: ```sh ssh -i /Users/mike_i386/.ssh/athena_key -o BatchMode=yes \ -N -L 8110:127.0.0.1:8110 root@192.168.1.212 ``` Dann http://127.0.0.1:8110 öffnen. Dieser Zugriff zählt als LAN, nicht als WireGuard-Bestätigung. Im Tunnel-only-Modus wird auch er gesperrt. Die Mac-Oberfläche auf Port 8108 kann weiterhin per SSH den Helper verwalten. Zur Wiederherstellung dort Modus LAN testen, SSH-Tunnel öffnen und dort bestätigen. Nur den neuen Container stoppen/starten: ```sh ssh -i ~/.ssh/athena_key -o BatchMode=yes root@192.168.1.212 \ docker stop athena-deck-network ssh -i ~/.ssh/athena_key -o BatchMode=yes root@192.168.1.212 \ docker start athena-deck-network ``` Beim regulären Stoppen wird auch der Demo-Kindprozess beendet. Der neue Container benötigt NET_ADMIN/NET_RAW in seinem eigenen Namespace sowie SETUID/SETGID/CHOWN zum Absenken der Webprozess-Rechte und Einrichten des privaten Sockets. Keine privileged-Option, kein SYS_ADMIN, keine Host-Geräte. NVIDIA ist ausschließlich mit Treiber-Capability `utility` für Hardware-Telemetrie eingebunden. ## Importgrenzen und Secrets - Maximal 16 KiB, genau `[Interface]` und ein `[Peer]`. - Eine IPv4-Interface-Adresse, IPv4-AllowedIPs, Peer-Endpoint erforderlich. - PrivateKey/PublicKey und optional PresharedKey als gültige 32-Byte-Base64-Werte. - MTU, ListenPort und PersistentKeepalive werden geprüft; Keepalive standardmäßig 25. - DNS wird ausdrücklich nicht übernommen; GUI meldet dies. - PostUp/PostDown/PreUp/PreDown, SaveConfig, Table, doppelte und unbekannte Direktiven werden abgelehnt. Kein Ausführen von `wg-quick` oder importiertem Shelltext. - Konfiguration und Passwort-Hash unter `/data` mit 0600, Verzeichnis 0700. Secret für `wg setconf` liegt nur kurz im Container-tmpfs und wird danach entfernt. - Import/Entfernung nur im bestätigten LAN-Modus bei deaktiviertem Tunnel. - Keine Anzeige oder Export privater/öffentlicher Peer-Schlüssel durch die API. IPv6, mehrere Peers, Konfiguration ohne Endpoint (passiver VPN-Server), DNS-Umschaltung und das Verwalten anderer produktiver Endpunkte sind noch nicht implementiert. Diese Einschränkungen werden beim Import ausdrücklich gemeldet. ## API Alle POSTs: JSON, `Content-Type: application/json`, `X-Athena-Deck: 1`, passender Origin. Im Serverbetrieb zusätzlich gültige Sitzung. Host-Allowlist und serverseitige Prüfung des tatsächlichen Zugangs gelten vor dem API-Aufruf. | Methode/Pfad unter `/api/v1` | JSON-Inhalt | |---|---| | POST `/login` | `password` | | GET `/network` | Status ohne Secrets | | POST `/network/install` | `password` für neue Server-Instanz, nur Mac-Verwaltung | | POST `/network/import` | `config` als Dateiinhalt | | POST `/network/connect` | `{}` | | POST `/network/disconnect` | `{}` | | POST `/network/delete` | `{}` | | POST `/network/mode` | `mode`: `lan`, `tunnel`, `both` | | POST `/network/confirm` | `trial_id` aus Status | | POST `/network/cancel` | `{}` | `/network` liefert `installed`, `configured`, `enabled`, `connected`, `latest_handshake`, `state`, `mode`, `pending`, `ingress`, URLs und ggf. Fehler. Bei Nicht-Erreichbarkeit meldet die Mac-Ansicht ausdrücklich „noch nicht installiert oder nicht erreichbar“; sie behauptet nicht, den Unterschied sicher zu kennen. Anwendungsfehler geben HTTP 400, fehlende Sitzung 401, unerlaubter Host/Origin oder Zugangsweg 403. Installation läuft als Hintergrundauftrag mit `job.state`. ## Tests am 28.09.2026 Lokale Unit-/API-Tests: `python3 -m unittest discover -s . -v`. Parser, fehlender Handshake, falscher Bestätigungsweg, Timeout, Neustart-Policy, Login, gefälschter Ingress-Header und bestehende Demo-Prozesssteuerung sind abgedeckt. Zusätzlich auf Athena zwei kurzlebige Testcontainer **ohne veröffentlichte Host-Ports**: frische Wegwerfschlüssel, echter WireGuard-Handshake, HTTP über beide Interfaces, LAN-/Tunnel-Sperren, richtige/falsche Bestätigung, geschlossenes LAN nach Disconnect, Neustart während unbestätigter Änderung. Testcontainer und Test-Secrets entfernt. Startzeiten sämtlicher vorher vorhandenen Container vor/nach dem Test unverändert. Reproduzierbarer Integrationstest (nur bewusst auf einem Linux-Docker-Testhost): ```sh docker build -t athena-deck-network-test:20260928 -f network/Dockerfile . python3 network/test_integration.py ``` Der echte Peer des Benutzers, seine Router-Freigaben und die persistente Installation über die GUI sind damit noch nicht live abgenommen. Der Test ersetzt keine eigene WireGuard-Konfiguration. Auf Athena wurde bisher nur der isolierte Test ausgeführt. Technische Referenzen: [WireGuard Quick Start](https://www.wireguard.com/quickstart/), [Docker Runtime Capabilities](https://docs.docker.com/engine/containers/run/).