Athena-Deck/network/NATIVE.md

Nativer WireGuard-Dienst

WireGuard wird auf dem Debian-Host als wgdeck0 verwaltet. Der systemd-Dienst athena-deck-network.service läuft außerhalb von Docker. Die Deck-Webanwendung kommuniziert als unprivilegierter Benutzer über einen Unix-Socket mit dem Helfer; sie bekommt weder NET_ADMIN noch allgemeinen Root-Zugriff.

Einrichtung

Auf einem frischen Debian zuerst wireguard-tools und iproute2 installieren; setup_network_helper.py --install-tools kann genau diese Pakete nachziehen. Es installiert keinen Kernel, keinen NVIDIA-Treiber und verlangt keinen Reboot.

Für die derzeitige isolierte Deck-Docker-Installation:

sudo python3 deploy/install.py --network-helper \
  --directory /opt/athena-deck-dev/runtime --lan-address 172.21.117.202

Standardmäßig werden nur GUI-Port und der konfigurierte API-Portbereich freigegeben. Zusätzliche Web-Tools müssen explizit mit --network-ports registriert werden, beispielsweise 8108,8120,8121,8122,8123,8124,8118,8127,8128. Der Installer bindet den Dienst-Socket und Proxy-Prüfwert schreibgeschützt ein. Die einmalige App-Aktualisierung startet nur Deck neu; der Tunnel bleibt bis zum Conf-Import und Aktivieren deaktiviert. Keine zweite Deck-Instanz entsteht.

Für eine spätere native Deck-Installation kann derselbe Helfer mit der unprivilegierten Deck-UID/GID bereitgestellt werden:

sudo python3 deploy/setup_network_helper.py --client-uid UID --client-gid GID \
  --lan-address HOST_LAN_IP --gui-port 8108 --ports 8108,8120

Deck benötigt DECK_NETWORK_MODE=native und DECK_PROXY_TOKEN_FILE=/run/athena-deck-network/proxy-token. Die konkrete Portdefinition liegt rootgeschützt in /var/lib/athena-deck-network/policy.json. Sie wird beim erneuten Setup nicht still verändert. Bestehende WireGuard-Interfaces und Gateways bleiben erhalten.

Konfiguration und Zugriff

Einstellungen → Netzwerkzugang: Conf importieren, aktivieren, Handshake prüfen, Zugriff wählen. Unterstützt werden ein Peer, eine IPv4-Adresse und optional eine IPv6-Adresse. Wiederholte DNS-Zeilen sind importierbar, verändern aber nicht den Host-DNS. Shell-Hooks, Table und SaveConfig werden abgelehnt.

LAN/Tunnel/beides gilt ausschließlich für die registrierten Deck-Ports. Listener binden an konkrete Adressen und Interfaces; keine Wildcard-Freigabe, keine Änderungen an Firewall-Default-Policies oder Docker-Regeln. Die vorhandenen Loopback-Ports bleiben für SSH-Verwaltung erreichbar. SSH-Port 22 wird nicht vom Zugriffsmodus gesperrt. Separate öffentliche Freigaben außerhalb des Helfers werden nicht automatisch kontrolliert.

GUI-Anfragen erhalten einen geheimen Proxy-Prüfwert und den tatsächlichen Zugangsweg. Bestätigung aus der GUI benötigt Anmeldung und den richtigen Zugangsweg. Ein Zugriffswechsel läuft 120 Sekunden auf Probe; ohne Bestätigung wird der vorherige Modus wieder wirksam. API/WebSocket-Verbindungen werden ohne Parameterübersetzung weitergeleitet. Zusatzoberflächen behalten ihre eigenen Anmelde- und Hostprüfungen; deren URL-Freigaben sind separat zu prüfen.

Der Dienst übernimmt absichtlich nicht die globale Standardroute. AllowedIPs-Routen liegen ausschließlich in Tabelle 51826 und werden nur für Pakete mit der eigenen Tunnel-Quelladresse ausgewählt. Full-tunnel-AllowedIPs machen somit nicht den gesamten Debian-Host zum VPN-Client. Eine spätere systemweite Egress-Policy wäre ein eigener Auftrag. Prioritäten 12126/12127 und Tabelle 51826 werden vor Aktivierung auf Kollisionen geprüft.

Sicherung und Migration

Die originale Conf liegt rootgeschützt im Dienst-Zustandsverzeichnis. Status enthält keine Schlüssel. Decks verschlüsseltes Backup exportiert/importiert Conf, Aktivierungszustand und bestätigten Modus. Der Helfer und seine feste Portdefinition müssen auf einem neuen Host vor dem Netzwerk-Restore eingerichtet sein. Wiederherstellung fremder Ports oder des alten Docker-Gateway-Routings ist kein Bestandteil dieses Modul-Backups.

Denselben Peer niemals gleichzeitig im alten Gateway und auf dem Host aktivieren. Vor einer Übernahme unabhängigen SSH-Zugang prüfen, alte Abhängigkeiten stoppen, Rückfall vorbereiten, dann alten Gateway stoppen und neuen Tunnel aktivieren. Zuerst beide Zugänge prüfen; erst anschließend "nur WireGuard" bestätigen.

Betrieb

sudo systemctl status athena-deck-network.service
sudo systemctl stop athena-deck-network.service
sudo systemctl start athena-deck-network.service

Stop entfernt nur die vom Dienst angelegte Schnittstelle und deren eigene Regeln. Ein explizit aktivierter Tunnel wird beim nächsten Dienststart wieder aktiviert; eine Deaktivierung über Deck bleibt dagegen gespeichert.

Tests: python3 -m unittest network.test_native test_network und auf einem Linux-Testhost als root python3 network/test_native_integration.py. Letzterer nutzt zwei Wegwerf-Netzwerk-Namensräume und synthetische Schlüssel, keine Container, produktiven Peer-Konfigurationen oder Host-Routen.