167 lines
8.9 KiB
Markdown
167 lines
8.9 KiB
Markdown
# 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/).
|