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