169 lines
9.3 KiB
Markdown
169 lines
9.3 KiB
Markdown
# 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](GNAI-006-SEC_VPN.md), [Profilverwaltung](GNAI-006-SEC_VPN_Client-Management.md)
|
||
|
||
## Ä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](https://www.wireguard.com/install/). 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:
|
||
|
||
```bash
|
||
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](https://git.zx2c4.com/wireguard-tools/tree/src/wg-quick/linux.bash)
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
sudo nmcli connection modify gnai-laptop connection.autoconnect no
|
||
sudo nmcli connection up gnai-laptop
|
||
nmcli connection show --active
|
||
ip -br addr
|
||
```
|
||
|
||
Zum Trennen:
|
||
|
||
```bash
|
||
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](https://networkmanager.dev/docs/api/latest/nmcli.html)
|
||
|
||
## 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
sudo wg-quick down gnai-laptop
|
||
```
|
||
|
||
Optionaler Autostart, erst nach erfolgreicher Prüfung und Absprache:
|
||
|
||
```bash
|
||
sudo systemctl enable wg-quick@gnai-laptop.service
|
||
```
|
||
|
||
Dies richtet den Bootstart ein. Für systemd-Verwaltung nach einem manuellen `wg-quick down`:
|
||
|
||
```bash
|
||
sudo systemctl start wg-quick@gnai-laptop.service
|
||
sudo systemctl status wg-quick@gnai-laptop.service
|
||
```
|
||
|
||
Autostart entfernen und systemd-verwaltete Verbindung stoppen:
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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.
|