WireGuard unter macOS: die zwei Installationen und der Schnittstellenname, der Linux-Anleitungen scheitern lässt

WireGuard auf einem Mac zu installieren wirkt trivial, bis die Anleitung, der Sie folgen, für Linux geschrieben war. Zwei Dinge bringen Leute zu Fall: Es gibt zwei verschiedene WireGuard-Produkte für macOS, und der Schnittstellenname, den alle Beispiele verwenden, wg0, kann auf einem Mac nicht existieren.

Die zwei Installationen, laut offizieller Seite

Die WireGuard-Installationsseite nennt beide, und es ist tatsächlich unterschiedliche Software:

Die App aus dem Mac App Store. Ein grafischer Client mit Eintrag in der Menüleiste, Tunnelimport und Aktivierung bei Bedarf. Das wollen die meisten.

Die Kommandozeilenwerkzeuge.

brew install wireguard-tools
# oder, mit MacPorts
port install wireguard-tools

Sie erhalten wg und wg-quick, dieselben Befehle wie auf einem Server. Darunter läuft die Go-Implementierung im Userspace statt eines Kernelmoduls, denn macOS hat kein WireGuard im Kernel.

Beide teilen sich die Tunnelliste nicht. Ein in der App importierter Tunnel taucht nicht in wg show auf, und umgekehrt. Wählen Sie pro Maschine eines, sofern Sie keinen Grund für beides haben.

Was Linux-Anleitungen scheitern lässt: wg0 gibt es hier nicht

Das ist der häufigste Fehlschlag, und die Fehlermeldung erklärt ihn selten.

Unter Linux legen Sie wg0 an und machen weiter. Unter macOS laufen Tunnel über den utun-Treiber, und die plattformübergreifende WireGuard-Dokumentation formuliert die Einschränkung unmissverständlich: Der utun-Treiber kann keine beliebigen Schnittstellennamen haben. Man muss utun gefolgt von einer Zahl verwenden, etwa utun0, oder schlicht utun, damit der Kernel wählt.

# scheitert unter macOS
sudo wg-quick up wg0

# funktioniert
sudo wg-quick up utun

Wenn Sie eine Anleitung mit wg0 kopiert haben, benennen Sie die Konfigurationsdatei und jeden Befehl um, der sie referenziert. Schlüssel, AllowedIPs, Endpoint und DNS sind nicht betroffen: Nur der Schnittstellenname ist plattformabhängig.

Herausfinden, welches utun Sie bekommen haben. Wenn Sie den Kernel wählen lassen, brauchen Sie einen Weg, das Ergebnis zu erfahren. Setzen Sie WG_TUN_NAME_FILE, bevor Sie den Tunnel hochfahren, und der gewählte Name wird dort hineingeschrieben:

export WG_TUN_NAME_FILE=/tmp/wg-name
sudo -E wg-quick up utun
cat /tmp/wg-name    # zum Beispiel utun4

Sonst lesen Sie die Ausgabe von ifconfig und raten, welches utun Ihnen gehört: einmal in Ordnung, in einem Skript mühsam.

Eine vorhandene Konfiguration importieren

Haben Sie eine Client-Konfiguration auf dem Server erzeugt, lässt sie sich unverändert übernehmen. In der App nutzen Sie den Import und wählen die .conf-Datei; der Tunnel erscheint in der Liste und ist bereit. Auf der Kommandozeile legen Sie sie unter /opt/homebrew/etc/wireguard/utun.conf (Apple Silicon) oder /usr/local/etc/wireguard/utun.conf (Intel) ab, benennen die Datei nach der Schnittstelle und führen wg-quick up utun aus.

Eine für ein Telefon erzeugte Konfiguration funktioniert auch auf einem Mac. Sie ist eine Peer-Definition, kein gerätespezifisches Artefakt, vorausgesetzt jedes Gerät hat sein eigenes Schlüsselpaar statt eines geteilten.

Prüfen, ob es wirklich funktioniert

Fahren Sie den Tunnel hoch und bestätigen Sie zwei Dinge, statt sie anzunehmen.

sudo wg show

Ein gesunder Peer zeigt einen latest handshake innerhalb der letzten zwei Minuten und transfer-Zähler ungleich null in beide Richtungen. Gesendet, aber nichts empfangen ist die Signatur eines blockierten Rückwegs. Kommt der Handshake nie zustande, geht unser Leitfaden zur Handshake-Fehlerbehebung die Ursachen nach Wahrscheinlichkeit durch.

Bestätigen Sie dann, dass der Verkehr wirklich durch den Tunnel läuft und nicht bloß die Schnittstelle existiert: Prüfen Sie Ihre öffentliche IP im Browser, und wenn Sie DNS durch den Tunnel leiten, kontrollieren Sie, dass nichts ausleckt. Unsere Notiz zu DNS-Lecks bei WireGuard behandelt die relevanten Einstellungen.

Kurz gefasst

Zwei Produkte: die App aus dem App Store für einen grafischen Client, wireguard-tools über Homebrew oder MacPorts für dieselbe Kommandozeile wie auf dem Server. Sie teilen keine Tunnel. Und unter macOS muss die Schnittstelle utun oder utunN heißen, niemals wg0, weil der utun-Treiber keine beliebigen Namen akzeptiert. Diese eine Zeile erklärt die meisten gescheiterten Mac-Einrichtungen nach Linux-Anleitungen.