WireGuard Peer hinzufügen: im laufenden Betrieb, ohne den Tunnel neu zu starten

Die meisten Anleitungen beantworten „wie füge ich einen WireGuard-Peer hinzu?" mit wg-quick down wg0 && wg-quick up wg0. Das funktioniert — und trennt zugleich alle, die den Tunnel gerade benutzen, um eine einzige Zeile in eine Datei zu schreiben. Auf einem Server mit einer Handvoll Clients ist das ein kurzes Ärgernis. Auf einem Server, auf den Sie sich wirklich verlassen, ist es der Grund, warum Leute das Hinzufügen von Peers ganz vermeiden.

Es gibt einen Befehl, der es im laufenden Betrieb erledigt.

Wie fügt man einen Peer zu WireGuard hinzu?

Eine Zeile, auf der laufenden Schnittstelle:

wg set wg0 peer <CLIENT_PUBLIC_KEY> allowed-ips 10.0.0.5/32

Der Peer existiert ab diesem Moment. Kein Neustart, keine abgebrochenen Handshakes, keine Unterbrechung für irgendjemanden, der bereits verbunden ist. wg set spricht direkt mit dem Kernel-Modul und bearbeitet die Live-Konfiguration der Schnittstelle.

Prüfen, ob es angekommen ist:

wg show wg0

Der neue öffentliche Schlüssel taucht in der Liste auf, noch ohne Handshake — das ist erwartbar, der Handshake passiert, wenn der Client zum ersten Mal Verkehr sendet.

Wie sieht der vollständige Ablauf auf der Kommandozeile aus?

Auf der Client-Maschine das Schlüsselpaar erzeugen:

wg genkey | tee client.key | wg pubkey > client.pub

client.key ist der private Schlüssel und verlässt diese Maschine nie. client.pub ist das, was der Server braucht.

Auf dem Server:

wg set wg0 peer "$(cat client.pub)" allowed-ips 10.0.0.5/32

Zurück auf dem Client braucht die Konfigurationsdatei den öffentlichen Schlüssel des Servers, dessen Endpunkt und die gerade vergebene Adresse:

[Interface]
PrivateKey = <Inhalt von client.key>
Address = 10.0.0.5/32

[Peer]
PublicKey = <SERVER_PUBLIC_KEY>
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

Die beiden Schlüssel sind der Schritt, den man falsch macht: Jede Seite hält den öffentlichen Schlüssel der anderen Seite, nie den eigenen.

Was gehört in AllowedIPs, wenn man einen Peer hinzufügt?

Es hängt davon ab, auf welcher Seite Sie stehen, und diese Asymmetrie ist die Quelle der meisten Verwirrung.

Die Regel gegen Überschneidungen ist strukturell, nicht kosmetisch. AllowedIPs sagt WireGuard, welchem Peer ein bestimmtes Ziel gehört — eine auf zwei Peers aufgeführte Adresse macht diese Entscheidung mehrdeutig, und das praktische Symptom ist, dass das Hinzufügen eines Clients den vorherigen stillschweigend offline nimmt. Wenn Sie über die eine /32 hinausgehen wollen, ist AllowedIPs im Detail erklärt der Ort, an dem die Routing-Seite auseinandergenommen wird.

Wie übersteht der neue Peer einen Neustart?

wg set ändert die laufende Schnittstelle. Es fasst /etc/wireguard/wg0.conf nicht an, ein Neustart vergisst es also. Zwei Wege, es dauerhaft zu machen:

Den Block von Hand in die Datei eintragen:

[Peer]
PublicKey = <CLIENT_PUBLIC_KEY>
AllowedIPs = 10.0.0.5/32

Oder den Live-Zustand zurück auf die Platte schreiben:

wg showconf wg0 > /etc/wireguard/wg0.conf
chmod 600 /etc/wireguard/wg0.conf

wg showconf gibt neben allem anderen den privaten Schlüssel der Schnittstelle aus, die Zieldatei darf also nicht für alle lesbar sein. Wenn Sie den zweiten Weg gegangen sind, prüfen Sie die Berechtigungen, bevor Sie weitermachen.

Um eine bearbeitete Datei neu zu laden, ohne Sitzungen abzuwerfen:

wg syncconf wg0 <(wg-quick strip wg0)

syncconf wendet die Unterschiede an. wg-quick down/up tut das nicht — es baut die Schnittstelle von Grund auf neu, also genau das, was Sie vermeiden wollten.

Wie skriptet man das Hinzufügen von Peers unter Linux?

Die Abfolge hat keinen interaktiven Schritt und lässt sich deshalb direkt skripten:

#!/usr/bin/env bash
set -euo pipefail
NAME="$1"; IP="$2"          # ./addpeer.sh laptop 10.0.0.7
umask 077
wg genkey | tee "$NAME.key" | wg pubkey > "$NAME.pub"
wg set wg0 peer "$(cat "$NAME.pub")" allowed-ips "$IP/32"
wg showconf wg0 > /etc/wireguard/wg0.conf
echo "added $NAME at $IP"

umask 077 ist wichtig: Ohne die Zeile ist der frisch geschriebene private Schlüssel für jedes Konto auf der Maschine lesbar. set -euo pipefail ebenso — ohne sie hinterlässt ein fehlgeschlagenes wg set trotzdem Schlüsseldateien und eine fröhliche Erfolgsmeldung.

Eine Hand ruht auf der Tastatur, während der Monitor schwarz bleibt — einen Peer mit wg set hinzuzufügen erzeugt überhaupt keine sichtbare Bestätigung, weshalb wg show das Einzige ist, was Ihnen sagt, dass es funktioniert hat.

Warum verbindet sich der neue Peer nicht?

Der Befehl lief durch und nichts passiert. In der Praxis ist es fast immer eines von drei Dingen, und alle drei lassen sich prüfen statt raten.

1. Die Schlüssel sind vertauscht. Der Server hält den öffentlichen Schlüssel des Clients, der Client den des Servers. Einen privaten Schlüssel dorthin zu schreiben, wo ein öffentlicher hingehört, scheitert lautlos.
2. Der Client sitzt hinter NAT ohne PersistentKeepalive. Der Server hat keinen Rückweg, bis der Client zuerst spricht, und die NAT-Zuordnung läuft in der Zwischenzeit ab. PersistentKeepalive = 25 auf der Client-Seite hält sie offen — warum 25 Sekunden und was der Wert kostet ist eine eigene Frage.
3. Die Adresse ist bereits vergeben. Zwei Peers mit denselben AllowedIPs sind der Fall, der am rätselhaftesten aussieht, weil ausgerechnet der ältere Peer kaputtgeht.

Für diesen dritten Fehler existiert wg-clients-audit. Es liest einen Ordner mit Client-Konfigurationen und meldet doppelte Adressen, wiederverwendete private Schlüssel und AllowedIPs-Bereiche, die breit genug sind, um das lokale Netz zu verschlucken — die drei Fehler, die einen Tunnel erzeugen, der verbindet und sich dann seltsam verhält. Es laufen zu lassen, bevor Sie jemandem eine Konfiguration geben, ist schneller, als es hinterher zu diagnostizieren.

Beginnen Sie mit wg show wg0. Ein Peer ohne latest handshake hat nie einen abgeschlossen, was auf Schlüssel oder Erreichbarkeit deutet. Ein Peer, der einen Handshake hat, aber keine Daten trägt, deutet auf AllowedIPs. Wenn der Handshake selbst der Punkt ist, an dem es hängt, arbeitet die Handshake-Fehlerbehebung die Ursachen der Reihe nach ab.

Was man behalten sollte

wg set fügt einen Peer live hinzu; wg-quick down/up trennt alle, um dieselbe Aufgabe zu erledigen. Was Sie live hinzufügen, ist nach einem Neustart weg, sofern Sie es nicht auch in die Konfiguration schreiben, und wg showconf schreibt Ihren privaten Schlüssel bereitwillig in eine für alle lesbare Datei, wenn Sie es zulassen. Ein /32 pro Client, niemals überschneidend. Und wenn ein neuer Peer sich seltsam verhält, sehen Sie in wg show nach, bevor Sie irgendetwas ändern — der Unterschied zwischen „kein Handshake" und „Handshake, aber kein Verkehr" sagt Ihnen, welche Hälfte des Aufbaus Sie sich ansehen müssen.