WireGuard Split DNS unter macOS: Suchdomains und Resolver

Warum dein Mac jeden Namen an den WireGuard-Tunnel schickt, wie sich Suchdomains von Resolvern pro Domain unterscheiden und wie du prüfst, was macOS nutzt.

Auf einem Mac schickt eine WireGuard-Konfiguration, deren DNS =-Zeile einen Server nennt, in der Regel jede Namensauflösung an diesen Server, solange der Tunnel aktiv ist: die Namen des entfernten Netzes und alles andere. Split DNS ist die Alternative. Für bestimmte Domains wird ein Resolver gewählt, und alle anderen Namen behalten das DNS, das du normalerweise nutzt. Suchdomains sind ein dritter, eigener Mechanismus: Sie ergänzen kurze Namen und wählen keinen Resolver. Wer die drei auseinanderhält, kann die meisten Symptome erklären, auf die man dabei stößt.

Diese Anleitung behandelt macOS und IPv4-Netze.

Stand der offiziellen App am 7. Oktober 2026: Die veröffentlichte WireGuard-App für macOS ist Version 1.0.16, und sie hat keine DNS-Einstellung pro Domain. Ein Patch für ein optionales Split DNS (Opt-in) wurde im Upstream-Projekt vorgeschlagen, aber unsere Prüfung fand weder einen Upstream-Merge noch eine veröffentlichte Version, die ihn enthält. Siehe den Quellcode der offiziellen App und ihren Eintrag im App Store für macOS.

Das Problem: ein Resolver für die ganze Maschine

Die Beispiele unten verwenden fiktive Namen und Adressen. Ein entferntes Netz betreibt einen DNS-Server unter 10.20.0.53, den einzigen Server, der server.corp.example.com kennt. Dein eigenes Netz, 192.168.50.0/24, hat Namen, die nur das DNS deines Routers kennt: einen Drucker, ein NAS.

Mit einem einzigen Resolver für alle Namen scheitert eine dieser beiden Gruppen. Richtest du alles auf 10.20.0.53 aus, werden deine lokalen Namen nicht mehr aufgelöst, während jede andere Anfrage einen Umweg über das entfernte Netz nimmt. Behältst du das DNS deines Routers, wird server.corp.example.com nie aufgelöst, obwohl 10.20.0.20, die Adresse dahinter, problemlos erreichbar ist.

In der offiziellen WireGuard-App

Eine Konfiguration wie diese ist verbreitet:

[Interface]
DNS = 10.20.0.53, corp.example.com

Die Netzwerkeinstellungen der App lesen sie so:

10.20.0.53, eine Adresse, wird zum DNS-Server des Tunnels.
corp.example.com oder jeder andere Eintrag, der keine Adresse ist, wird zu einer der Suchdomains des Tunnels.
Sobald mindestens ein Server angegeben ist, setzt die App die Liste der Match-Domains des Tunnels auf einen einzigen leeren Eintrag. Der Kommentar im Quellcode sagt es so: Alle DNS-Anfragen müssen zuerst über das DNS des Tunnels laufen.

Die veröffentlichte App hat keine Einstellung, um nur bestimmte Domains an das DNS des Tunnels zu schicken. Die Suchdomain schränkt nichts ein: Sie ergänzt Namen, während jede Anfrage weiterhin zuerst an 10.20.0.53 geht.

Mit wg-quick unter macOS

wg-quick aus wireguard-tools teilt dieselbe Zeile in Serveradressen und Suchdomains auf. Sein macOS-Skript arbeitet dann auf der ganzen Maschine, nicht auf einer Tunnel-Schnittstelle:

Ist mindestens eine Serveradresse angegeben, setzt es diese Server und Suchdomains auf jedem Netzwerkdienst, den networksetup auflistet, und ersetzt deren bisherige Werte. Hat die Zeile keine Suchdomain, löscht es die Suchdomains der Dienste.
Solange der Tunnel aktiv ist, setzt es diese Einstellungen erneut, wenn sich die Routing-Tabelle ändert.
Wenn der Tunnel beendet wird, stellt es die Werte wieder her, die es vor der Änderung festgehalten hat.
Eine DNS =-Zeile mit Suchdomains, aber ohne Serveradresse ändert überhaupt keine DNS-Einstellung.

Das ist eine DNS-Änderung für die ganze Maschine, kein Split DNS.

Suchdomains sind keine Resolver-Auswahl

Was eine Suchdomain macht

Mit einer Suchdomain lässt sich ein kurzer Name mit einem Suffix versuchen: server kann als server.corp.example.com nachgeschlagen werden. Sie hilft, Namen zu ergänzen und zu suchen. Sie entscheidet nicht, welcher DNS-Server für corp.example.com antwortet.

Das passt zu den Berichten über Suchdomains, die „nur autovervollständigen“: Den Namen zu ergänzen ist die ganze Aufgabe einer Suchdomain. Der Resolver, der den ergänzten Namen erhielt, musste ihn trotzdem kennen.

Was Split DNS macht

Split DNS wählt einen Resolver für eine Domain. Anfragen für Namen unter corp.example.com gehen an 10.20.0.53; alle anderen Namen bleiben beim Resolver, den du normalerweise nutzt. Die Domain, die den Resolver auswählt, wird oft Match-Domain genannt.

Ein Client kann seine Match-Domains und seine Suchdomains aus derselben Liste nehmen, aber es bleiben zwei Mechanismen. Der eine schreibt einen kurzen Namen um; der andere wählt den Server, der für eine Domain antwortet. Eine Konfiguration kann das eine ohne das andere haben.

Es ist nicht dasselbe wie Split Tunneling

Split Tunneling entscheidet, welche Adressen durch den Tunnel laufen: Das ist AllowedIPs. Split DNS entscheidet, welcher Resolver einen Namen beantwortet. Oft brauchst du beides, und beide hängen voneinander ab: Der entfernte DNS-Server selbst muss durch den Tunnel geroutet werden. Im Beispiel muss AllowedIPs sowohl 10.20.0.53 als auch 10.20.0.20 abdecken. Siehe DNS, Routing und Split Tunneling für die Routing-Hälfte.

Deine Optionen unter macOS

Ansatz	Was er ändert	Was er nicht tut
Das Verhalten der offiziellen App beibehalten	Während der Verbindung geht jede Anfrage zuerst an den DNS-Server des Tunnels	Namen, die nur das DNS deines eigenen Netzes kennt, werden womöglich nicht mehr aufgelöst
„Private IPs ausschließen“ in der offiziellen App aktivieren	Routing: Private IPv4-Bereiche verlassen einen Full Tunnel	Er wählt keinen Resolver pro Domain; die DNS-Einstellungen bleiben gleich
Eine Resolver-Datei in `/etc/resolver` anlegen	Eine Resolver-Konfiguration für eine Domain, die den Server deiner Wahl nennt	Sie ist nicht an den Tunnel gebunden, und ihr Zusammenspiel mit der offiziellen App während der Verbindung ist nicht geklärt
`wg-quick` verwenden	DNS für die ganze Maschine, solange der Tunnel aktiv ist, danach wiederhergestellt	Kein Resolver pro Domain; Skripte können einen hinzufügen, und um ihr Aufräumen musst du dich dann selbst kümmern
Einen Client verwenden, der Resolver pro Domain auswählt	Nur die angegebenen Domains nutzen den entfernten Resolver	Prüfe, wie er Suchdomains behandelt und was mit Namen geschieht, wenn der Tunnel stoppt

Resolver pro Domain mit /etc/resolver

Die Manpage auf deinem Mac, man 5 resolver, beschreibt Resolver-Konfigurationsdateien für einzelne Domains, die aus /etc/resolver gelesen werden. Bei einer Datei in diesem Verzeichnis dient der Dateiname als Domainname, und das Schlüsselwort nameserver gibt die Adresse eines Nameservers an, den der Resolver abfragen soll. Die Seite beschreibt, dass Anfragen an die Konfiguration geleitet werden, deren Domain am besten zum Namen passt. Für das Beispiel würde eine Datei namens /etc/resolver/corp.example.com Folgendes enthalten:

nameserver 10.20.0.53

Dieselbe Seite dokumentiert port und die anderen Schlüsselwörter. Sie sagt auch, dass Resolver-Konfigurationen aus anderen Quellen stammen können, etwa aus der System-Configuration-Datenbank, und dass Nutzer keine Annahmen darüber treffen sollten, woher die Konfiguration stammt.

Kenne ihre Grenzen, bevor du dich darauf verlässt:

Zum Anlegen der Datei brauchst du Administratorrechte.
Die Datei bleibt bestehen, ob der Tunnel aktiv ist oder nicht. Nichts entfernt sie, wenn der Tunnel stoppt: Sie nennt für diese Domain weiterhin 10.20.0.53, einen Server, der womöglich nur durch den Tunnel erreichbar ist.
Sie ist ein Mechanismus von macOS, keine WireGuard-Einstellung. Wie sie mit der offiziellen WireGuard-App zusammenwirkt, während diese verbunden ist, wurde hier nicht geklärt: Die App schickt jede Anfrage zuerst an das DNS des Tunnels. Nimm nicht an, dass das eine das andere übersteuert; prüfe das Ergebnis mit scutil --dns und einer echten Auflösung, wie unten beschrieben.

Was „Private IPs ausschließen“ ändert

In der offiziellen App für macOS erscheint dieses Kontrollkästchen („Exclude private IPs“ in der englischen App) im Tunnel-Editor, wenn die Konfiguration einen einzigen Peer hat, dessen AllowedIPs jede IPv4-Adresse abdeckt (0.0.0.0/0).

Wenn du es aktivierst, wird AllowedIPs umgeschrieben:

0.0.0.0/0 wird durch eine feste Liste ersetzt, die der Quellcode als alle nicht privaten IPv4-Adressen beschreibt. Sie lässt die privaten Bereiche 10.0.0.0/8, 172.16.0.0/12 und 192.168.0.0/16 aus.
Die DNS-Serveradressen der Konfiguration werden hinzugefügt, damit sie im Tunnel bleiben.
Jeder andere IPv4-Eintrag in diesem AllowedIPs wird ebenfalls ersetzt.

Private Adressen gehen dann über deine normale Verbindung. Dein lokales Netz wird außerhalb des Tunnels erreichbar. Auch entfernte private Netze verlassen den Tunnel: Abgesehen von den hinzugefügten DNS-Serveradressen werden sie nicht mehr über ihn erreicht.

Die Option ändert nur Routen. Die DNS-Einstellungen bleiben, wie sie waren, und Anfragen gehen weiterhin zuerst an den DNS-Server des Tunnels. Sie wählt keinen Resolver pro Domain.

Prüfen, was macOS wirklich nutzt

Drei Befehle beantworten drei verschiedene Fragen. Ersetze die fiktiven Namen und Adressen durch deine. Sie lesen die Konfiguration oder führen Auflösungen durch; sie ändern keine Einstellung.

Die Resolver-Konfiguration lesen

scutil --dns

Das beantwortet: Welche Resolver hat macOS bekommen, und für welche Domains? Achte auf den DNS-Server des Tunnels, die Domain, die zu jedem Resolver gehört, die Suchdomains und die Schnittstelle, an die jeder Resolver gebunden ist (scoped). Ein Resolver ohne Domain und ein Resolver für corp.example.com spielen verschiedene Rollen. Der zuerst aufgeführte Resolver ist nicht unbedingt derjenige, der für jede Anfrage verwendet wird.

scutil --dns zeigt die Konfiguration, nicht das Ergebnis einer Auflösung.

Über das System auflösen

dscacheutil -q host -a name server.corp.example.com

Das beantwortet: Was liefert macOS zurück, wenn es über seine Standardaufrufe nach diesem Namen gefragt wird? Seine Manpage, man dscacheutil, sagt, dass es eine Abfrage über die Standardaufrufe startet und dass das Ergebnis aus einem Cache stammen kann. Es zeigt die Adresse, die das System liefert, nicht, welcher DNS-Server sie geliefert hat. Verwende den vollqualifizierten Namen (FQDN) und vergleiche die zurückgegebene Adresse mit der erwarteten.

Einen Server direkt abfragen

dig @10.20.0.53 server.corp.example.com

Das beantwortet: Kennt dieser Server den Namen, und kannst du ihn erreichen? dig @server schickt die Anfrage direkt an den Server, den du nennst, und umgeht die Resolver-Auswahl des Systems. Eine korrekte Antwort beweist, dass der Server funktioniert und erreichbar ist. Sie beweist nicht, dass macOS diesen Server für den Namen wählen wird.

Mit der echten Anwendung testen

Öffne den Dienst über seinen vollständigen Namen, zum Beispiel https://server.corp.example.com/. Das prüft auch das HTTPS-Zertifikat, das nur auf dem echten Hostnamen gültig ist. Eine Anwendung mit eigenem DNS-Mechanismus kann sich anders verhalten als der System-Resolver. Antworten aus dem Cache können eine Änderung verdecken: Teste nach dem Ändern einer Einstellung erneut mit Namen, deren erwartete Antwort du kennst.

Häufige Fallen

Symptom	Was du prüfen solltest
Nur der kurze Name scheitert	Die Suchdomain: fehlt oder wird von deinem Client nicht angewendet. Teste den vollständigen Namen
Der vollständige Name scheitert, die Adresse antwortet	Die Resolver und ihre Domains in `scutil --dns`; was das System mit `dscacheutil` liefert
Jeder Name geht durch den Tunnel	Das Catch-all-DNS der offiziellen App oder die maschinenweiten Einstellungen von `wg-quick`
Lokale Namen werden nach dem Verbinden nicht mehr aufgelöst	Ein entfernter Resolver, der für alles antwortet; siehe die Optionen oben
`dig @10.20.0.53` antwortet, der Browser nicht	`dig` hat die Resolver-Auswahl des Systems umgangen; lies `scutil --dns` und vergleiche mit dem, was `dscacheutil` liefert
Überhaupt keine Antwort vom entfernten DNS-Server	Seine Adresse in `AllowedIPs`; siehe DNS, Routing und Split Tunneling
Namen scheitern, nachdem der Tunnel gestoppt wurde	Nicht wiederhergestellte Einstellungen oder eine in `/etc/resolver` zurückgebliebene Datei
Ein Name auf `.local` wird nicht über DNS aufgelöst	Das Multicast-DNS von Bonjour verwendet dieses Suffix, und Apple hat Auflösungsfehler bei Unicast-DNS-Namen dokumentiert, die auf `.local` enden

Wenn selbst über die Adresse nichts antwortet, liegt das Problem beim Tunnel selbst: siehe Wenn der Tunnel nicht zustande kommt.

Warum das zählt, sobald mehrere Netzwerke verbunden sind

Bei zwei entfernten Netzen mit jeweils eigenem DNS-Server liegt ein einziger Resolver für eines davon falsch: Keiner der beiden Server kennt die Namen des anderen Netzes. Mehrere VPN-Clients, die jeweils die DNS-Einstellungen der Maschine ändern, können sich außerdem gegenseitig stören, besonders wenn einer von ihnen stoppt. Für zwei WireGuard-Tunnel gleichzeitig, Routen und DNS zusammen, siehe Mehrere WireGuard-Tunnel unter macOS.

Paart für Split DNS verwenden

Paart Client ist einer der WireGuard-Clients, die einen Resolver pro Domain auswählen. Sein Split DNS arbeitet mit internen Namen, die du für jede Verbindung einträgst.

Was interne Namen machen

Nichts wird aufgeteilt, solange du nicht sagst, welche Namen zum entfernten Netz gehören. Öffne in den Details der Verbindung Names und wähle Add an internal name: zum Beispiel int.example.com. Diese Namen, und nur sie, werden durch den Tunnel aufgelöst. Alle anderen behalten das DNS dieses Geräts:

int.example.com geht durch den Tunnel zum entfernten Resolver, 10.0.99.10;
google.com geht an das DNS des WLANs, in dem du gerade bist.

Außer du wählst unter Settings › Resolvers einen Ersatz-Resolver: Dann beantwortet dieser Resolver stattdessen alle anderen Namen.

Die Zeile Look up with oben unter Names legt fest, wo die internen Namen nachgeschlagen werden. Bleibt sie leer, ist es das DNS der Konfiguration. Ohne internen Namen wird nichts aufgeteilt: Der unter DNS gewählte Resolver beantwortet jeden Namen. Unter macOS hängt Paart die internen Namen als Match-Domains an den gewählten Resolver.

Interne Namen wählen einen Resolver; sie sind keine Suchdomains. Paart wendet die Suchdomains aus der DNS =-Zeile einer Konfiguration nicht an: Sie werden beim Import verworfen, und der Import weist darauf hin. Verwende vollqualifizierte Namen wie server.int.example.com.

Interne Namen gibt es auf Mac, iPhone und iPad. Sie gehören zum erweiterten Networking: In der kostenlosen Stufe funktionieren sie auf deiner kostenlosen Verbindung, auf den anderen kommen sie mit Paart Pro.

Technische Quellen

Konfigurationsparser von wireguard-apple — wie der offizielle Client DNS = in Server und Suchdomains aufteilt.
Netzwerkeinstellungen von wireguard-apple — DNS-Server, Suchdomains und die Catch-all-Match-Domain im offiziellen Client.
Tunnel-Modell von wireguard-apple — was „Private IPs ausschließen“ mit AllowedIPs macht.
Referenz zu wg-quick und Darwin-Quellcode — wie wg-quick unter macOS DNS setzt und wiederherstellt. Der Darwin-Quellcode ist die plattformspezifische Referenz.
man 5 resolver und man dscacheutil, auf deinem Mac — Resolver-Dateien pro Domain in /etc/resolver und Auflösungen über die Standardaufrufe des Systems.
Apple Support: Domains, die auf .local enden — wie Bonjour das Suffix nutzt, und Unicast-DNS-Namen, die womöglich nicht aufgelöst werden. Apple hat diesen Artikel archiviert.
Verlauf von wireguard-apple und Patch-Vorschlag mit optionalem Split DNS — einen Vorschlag von einem Upstream-Merge und einer veröffentlichten App unterscheiden.

Quellenprüfung: 7. Oktober 2026. Die offizielle App und wg-quick sind nach ihrem Upstream-Quellcode beschrieben, nicht nach einem Test jeder macOS-Version.