# 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:

```sh
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:

```sh
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

```sh
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.