infrastructure/docs/GNAI-006-SEC_VPN_Clients_Linux.md

SOP – WireGuard unter Linux einrichten und verwenden

Dokumenten-ID: GNAI-006-SEC-SOP-03
Plattformen: Debian, Arch/CachyOS und Fedora; Fedora Kinoite gesondert berücksichtigt
Status: Anleitung bereinigt; bisheriger CachyOS-CLI-Test teilweise bestanden, übrige Varianten nicht abgenommen
Referenzen: Gateway, Profilverwaltung

Änderungsverlauf

Datum	Version	Autor	Änderung
2026-09-09	1.0	spektr	Erste Clientanleitung für Linux mit KDE Plasma erstellt.
2026-09-15	2.0	spektr	Debian, Arch/CachyOS, Fedora und Kinoite getrennt beschrieben; NetworkManager und wg-quick, Geheimnisschutz, Fehlersuche und belegten Teiltest überarbeitet.

1. Voraussetzungen und Begriffe

Du benötigst ein eigenes .conf-Profil vom Administrator, sudo-Berechtigung für die Einrichtung und Internetzugang. Der Administrator nennt deine Rolle und ein erreichbares Testziel. Du benötigst keine wg-easy-Anmeldung.

Das Profil enthält geheime Schlüssel: PrivateKey und PresharedKey dürfen nicht geteilt werden. PublicKeys sind öffentlich, die vollständige Datei ist dennoch geheim. Jeder Rechner verwendet einen eigenen Peer. Serverdienste verlangen weiterhin ihre eigene Anmeldung.

Bei Split-Tunneling gehen nur freigegebene Ziele durch WireGuard, normale Internetverbindungen bleiben direkt. Wähle eine der Methoden: NetworkManager oder wg-quick. Beide dürfen dasselbe Profil nicht gleichzeitig aktivieren.

2. Software bereitstellen

Distribution	Installation der WireGuard-Werkzeuge
Debian	sudo apt update, anschließend sudo apt install wireguard-tools
Arch / CachyOS	sudo pacman -S wireguard-tools
Fedora, klassisch	sudo dnf install wireguard-tools
Fedora Kinoite	falls Werkzeuge fehlen: sudo rpm-ostree install wireguard-tools, anschließend in die neue Deployment-Version neu starten

Die offiziellen Distributionsbefehle stehen auf der WireGuard-Installationsseite. Aktuelle Standardkernel dieser Distributionen unterstützen WireGuard; bei angepassten Kerneln muss der Administrator dies prüfen. DKMS nicht pauschal installieren.

Für NetworkManager muss dessen Dienst vorhanden und aktiv sein; auf KDE wird die Netzwerkoberfläche durch plasma-nm bereitgestellt, nicht durch ein automatisch von wireguard-tools erzeugtes Tray-Icon. Desktop-Installationen bringen das häufig bereits mit:

nmcli --version
systemctl is-active NetworkManager

Wenn NetworkManager fehlt, klärt der Administrator zunächst, welcher Dienst dein Netzwerk verwaltet. Auf einem Debian-Server nicht parallel zur vorhandenen ifupdown-Konfiguration blind einen weiteren Netzwerkmanager einschalten.

3. Profilname und Aufbewahrung

Für diese Anleitung heißt die lokale Datei gnai-laptop.conf. Vom Administrator anders benannte Dateien gegebenenfalls im Dateimanager umbenennen. Der tatsächliche Name muss bei folgenden Befehlen passen. Linux-wg-quick verwendet den Dateinamen ohne .conf als Interface-Namen, ohne wg--Präfix, maximal 15 Zeichen. wg-quick-Implementierung

chmod 600 "$HOME/Downloads/gnai-laptop.conf"

4. Methode A: NetworkManager und Desktop

Für Desktop-Nutzer eignet sich die bestehende NetworkManager-Verwaltung. Unter KDE Systemeinstellungen → Verbindungen öffnen und die Funktion zum Importieren einer Verbindung verwenden, sofern deine Version WireGuard-Dateiimport anbietet. Wenn die Oberfläche diese Funktion nicht anbietet, ist der folgende Import eindeutig; danach erscheint die Verbindung in der Desktop-Netzwerkverwaltung:

sudo nmcli connection import type wireguard file "$HOME/Downloads/gnai-laptop.conf"
nmcli connection show

Den beim Import gemeldeten Verbindungsnamen verwenden. Bei abweichendem Namen in folgenden Befehlen gnai-laptop ersetzen:

sudo nmcli connection modify gnai-laptop connection.autoconnect no
sudo nmcli connection up gnai-laptop
nmcli connection show --active
ip -br addr

Zum Trennen:

sudo nmcli connection down gnai-laptop

Alternativ über die Desktop-Netzwerkverwaltung verbinden/trennen. Verbindung erst nach Absprache automatisch starten lassen; Autoconnect-Verhalten wird beim Import nicht vorausgesetzt. NetworkManager speichert das Profil in seiner eigenen Verwaltung; die Downloaddatei ist danach nur eine zusätzliche Geheimniskopie. NetworkManager-CLI

5. Methode B: wg-quick, Terminal und systemd

Diese Methode verwendet die Datei /etc/wireguard/gnai-laptop.conf. Nur verwenden, wenn Methode A für dieses Profil nicht aktiv ist:

sudo install -d -m 700 /etc/wireguard
sudo install -m 600 "$HOME/Downloads/gnai-laptop.conf" /etc/wireguard/gnai-laptop.conf
sudo wg-quick up gnai-laptop
sudo wg show gnai-laptop
ip -br addr show gnai-laptop

Erwartet: Interface gnai-laptop, eigene Adresse 10.8.0.x, ein Handshake nach Verkehr zu einem freigegebenen Ziel. Nicht pauschal wg0 abfragen; das ist der Interface-Name auf dem Server.

DNS-Abhängigkeit: Wenn das Profil DNS = ... enthält, ruft Linux-wg-quick resolvconf auf. Vorher prüfen:

command -v resolvconf

Bei fehlendem Befehl nicht die DNS-Zeile ungeprüft entfernen. Der Administrator installiert eine zum vorhandenen Resolver passende resolvconf-Implementierung oder nutzt NetworkManager. Debian/Arch/Fedora verwenden nicht in jeder Installation denselben Resolver; deshalb wird kein pauschaler Paketwechsel vorgeschrieben. Profile mit leerem DNS-Feld verwenden System-DNS.

Zum Trennen:

sudo wg-quick down gnai-laptop

Optionaler Autostart, erst nach erfolgreicher Prüfung und Absprache:

sudo systemctl enable wg-quick@gnai-laptop.service

Dies richtet den Bootstart ein. Für systemd-Verwaltung nach einem manuellen wg-quick down:

sudo systemctl start wg-quick@gnai-laptop.service
sudo systemctl status wg-quick@gnai-laptop.service

Autostart entfernen und systemd-verwaltete Verbindung stoppen:

sudo systemctl disable --now wg-quick@gnai-laptop.service

6. Verbindung prüfen

Die erste Abnahme von einem fremden Netz ausführen, beispielsweise Smartphone-Hotspot. Zuerst einen tatsächlich freigegebenen Dienst aufrufen:

Rolle	Testziel
Familie	Proxmox https://10.0.0.2:8006 und ein bekannter Heimnetz-PC
Server Admin	Proxmox oder bekannter freigegebener LXC-Dienst
LLM Admin	bekannter Dienst auf 10.0.0.90, gegebenenfalls SSH mit eigenem SSH-Key

Ein Ping ist ergänzend möglich, aber Host-Firewalls können ihn sperren. Ein ausgeschalteter KI-Server ist kein geeignetes Testziel. 10.8.0.1 ist nur dann ein Testziel, wenn der Administrator Zugriff darauf ausdrücklich freigegeben hat.

ip -4 route get 10.0.0.90
sudo wg show

Der Routenbefehl ist für Rollen geeignet, denen .90 freigegeben wurde. Für Rollenprüfungen am Server reicht fehlendes Client-Routing nicht als Sperrnachweis.

Öffentliche IPv4-Adresse vor und nach der Aktivierung im selben fremden Netz vergleichen:

curl -4 https://ifconfig.co/ip

Erwartet: Außenadresse des verwendeten Netzes bleibt gleich, normale Internetnutzung bleibt direkt. -4 erzwingt einen IPv4-Test. Ein direkter IPv6-Internetpfad ist im vorgesehenen IPv4-Split-Tunnel keine zusätzliche VPN-Route. Bei Internetproblemen auch DNS prüfen: DNS kann über das VPN laufen, obwohl der übrige Internetverkehr direkt bleibt.

7. Fehlersuche

Symptom	nächster Schritt
Datei nicht gefunden / ungültiger Interface-Name	Pfad, .conf-Endung und maximal 15 Zeichen im Basisnamen prüfen
kein Handshake	Internet prüfen, erlaubtes Ziel aufrufen; Administrator kontrolliert tatsächlichen Endpoint-DNS und UDP-Weiterleitung
Handshake, aber Dienst unerreichbar	Zielstatus, Rolle, Routen, Server-Firewall und NAT vom Administrator prüfen lassen
resolvconf: command not found	bei wg-quick DNS-Abhängigkeit aus Abschnitt 5 klären
Operation not permitted	sudo bzw. Systemrechte prüfen; Datei-ACLs oder Gruppenzugehörigkeit ersetzen keine benötigten Netzwerkprivilegien
Interface bereits vorhanden	andere Verwaltung oder zweite Aktivierung desselben Profils prüfen; Methoden nicht mischen
KDE-Verbindung fehlt	NetworkManager und plasma-nm sowie Import prüfen; kein pauschaler Plasma-Neustart erforderlich
fremdes Netz verwendet ebenfalls 10.0.0.0/24	Adressüberschneidung melden und über anderes Netz gegenprüfen

Bei neuem Profil erst die alte Verbindung trennen. Bei NetworkManager nach Absprache den alten Eintrag entfernen und neu importieren; bei wg-quick Datei geschützt ersetzen und wieder starten. Exporte nicht unter offen lesbaren Pfaden belassen. Geräteverlust oder Offenlegung sofort melden, damit der Administrator den Peer serverseitig widerruft.

8. Abnahmestand

Am 12.09.2026 wurde ein CachyOS-Laptop mit wg-quick von außerhalb des Heimnetzes getestet: Handshake, Ping auf das VPN-Gateway und Proxmox sowie direkter IPv4-Internetpfad bestanden. KI-Server war ausgeschaltet. Dieser historische Test bestätigt weder NetworkManager-/Fedora-/Debian-Verfahren noch die neue Rollen-Firewall; diese Abnahmen stehen aus.