WireGuard-Modul · Athena Deck 0.3

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

Auf dem Mac http://127.0.0.1:8108/#network öffnen.
Eigenes Deck-Passwort (mindestens 16 Zeichen) und separaten API-Token (mindestens 32 Zeichen) vergeben, Token sichern und Modul auf Athena installieren wählen. Installation läuft asynchron und meldet ihren Status.
Eigene IPv4-WireGuard-Conf importieren. Einen eigenen Peer verwenden, nicht die Konfiguration des produktiven Athena-Gateways wiederverwenden.
WireGuard aktivieren. Erst ein Handshake innerhalb der letzten 180 Sekunden führt zum Status „Verbunden“. Ein geladenes Interface alleine genügt nicht.
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. Kennwort-/Tokenwechsel und Rechte sind in Zugang und API beschrieben.

Im LAN-/Beides-Modus ist zusätzlich ein SSH-Tunnel zur Server-GUI möglich:

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:

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`, `api_token` für neue Server-Instanz, nur angemeldete 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):

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, Docker Runtime Capabilities.

9.1 KiB Raw Blame History