Configuring a custom DNS server for WireGuard clients requires understanding that the standard
[Peer] configuration file does not natively push DNS settings to operating systems. While some Linux tools like
wg-quick support a
DNS key, this is not part of the core WireGuard protocol and may fail on Windows, macOS, or iOS. To ensure reliable DNS resolution across all platforms, you must configure the DNS settings within the client’s operating system network stack or use a local DNS resolver on the VPN server itself.
The Limitation of the Standard Peer Configuration
Many users attempt to add a
DNS = 10.0.0.5 line directly inside the
[Peer] block of their
server.conf file, expecting it to automatically update the client’s resolver. This approach is fundamentally flawed because the WireGuard protocol specification defines only three main sections:
[Interface],
[Peer], and optional comments. The
DNS keyword is not recognized by the kernel module or cross-platform clients. If you are using a Linux server with
systemd-resolved, the
wg-quick service handler might parse this key, but it will be ignored by other clients entirely. Therefore, relying on the config file for DNS distribution leads to inconsistent behavior where some devices resolve correctly while others fall back to public resolvers, potentially leaking traffic or breaking internal name resolution.
Method 1: Configuring Client-Side Network Settings
The most robust and universal method is to manually set the DNS servers on each client device after connecting to the VPN. This ensures that every operating system handles the resolution according to its own rules.
For Windows Clients:
1. Open the Network Connections panel (
ncpa.cpl).
2. Right-click the WireGuard adapter and select Properties.
3. Select Internet Protocol Version 4 (TCP/IPv4) and click Properties.
4. Choose "Use the following DNS server addresses" and enter your internal DNS IP (e.g.,
10.0.0.5) and a fallback public DNS.
5. Repeat for IPv6 if applicable.
For macOS Clients:
1. Go to System Preferences > Network.
2. Select the WireGuard interface.
3. Click Advanced, then the DNS tab.
4. Add your internal DNS server to the list.
For Linux Clients (non-systemd):
If you are not using
systemd-resolved, you may need to edit
/etc/resolv.conf directly or use NetworkManager profiles to assign static DNS to the tunnel interface. Always ensure that the DNS server is reachable through the VPN tunnel before configuring it as the primary resolver.
Method 2: Using a Local DNS Resolver on the Server
To automate this process and avoid manual configuration on every device, deploy a DNS resolver on your WireGuard server that has access to both internal and external zones. Tools like
dnsmasq or
unbound are ideal for this purpose.
First, install
dnsmasq on your server. Configure it to listen on the WireGuard interface IP (e.g.,
10.0.0.1) and forward unknown queries to upstream public DNS servers. You can also define static host entries in the
dnsmasq configuration file for internal resources. Once running, instruct all WireGuard clients to use the server’s WireGuard IP (
10.0.0.1) as their DNS server. This centralizes management; if an internal record changes, you only update the server’s DNS config, and all clients benefit immediately.
This approach integrates well with broader networking goals. For more details on managing traffic flow through your VPN, see our guide on
Wireguard with VPS for Mobile Clients: Routing All Traffic.
Method 3: Leveraging wg-quick on Linux Servers
If your WireGuard server runs Linux and uses
systemd-resolved, you can utilize the
DNS key within the
[Interface] section of the server’s configuration file. Note that this affects the server’s own DNS resolution, not the clients’. However, if you run a local DNS proxy on the server, this setup allows the server to resolve internal names correctly when acting as a relay or proxy.
Example
server.conf:
[Interface]
Address = 10.0.0.1/24
ListenPort = 51820
PrivateKey = SERVER_PRIVATE_KEY
DNS = 10.0.0.5
[Peer]
PublicKey = CLIENT_PUBLIC_KEY
AllowedIPs = 10.0.0.2/32
This configuration tells
systemd-resolved to use
10.0.0.5 for resolving domain names on the server side. It does not push this setting to the client. Ensure that
systemd-resolved is enabled and configured to handle the
wg0 interface properly by checking
/etc/systemd/resolved.conf.
Verifying DNS Resolution
After applying your chosen method, verify that DNS resolution works correctly through the tunnel. On the client machine, open a terminal or command prompt and ping an internal hostname that should only resolve via your custom DNS. Use commands like
nslookup internal.example.com or
dig @10.0.0.5 internal.example.com to confirm that queries are being sent to the correct server. If resolution fails, check the firewall rules on your DNS server to ensure UDP port 53 is open and accessible from the WireGuard subnet.
Troubleshooting connectivity issues often overlaps with DNS problems. If peers cannot communicate, refer to
Troubleshooting WireGuard Client-to-Client Communication Issues to rule out basic routing errors before diving deeper into DNS configurations.
Frequently Asked Questions
Why do my Windows clients ignore the DNS key in the config?
Windows WireGuard clients strictly follow the official WireGuard protocol specification, which does not include a DNS parameter in peer configurations. They rely entirely on the OS network stack for DNS settings. You must configure DNS manually in the Windows Network Adapter properties or use a third-party tool that modifies these settings programmatically.
Can I use the same DNS server for both internal and external queries?
Yes, if your DNS server (like dnsmasq) is configured to forward external queries to public resolvers. This simplifies client configuration by requiring only one DNS entry. However, ensure your internal zone data is accurate and that the DNS server has proper internet access to resolve non-internal domains.
What happens if my custom DNS server goes down?
If you only specify one DNS server and it becomes unreachable, all DNS resolution will fail, effectively breaking internet access for applications that rely on name resolution. Always configure a secondary/fallback DNS server in your client settings to maintain connectivity during outages.
Does enabling split DNS affect the WireGuard config file?
No, split DNS is an operating system feature that determines whether traffic for specific domains goes through the VPN or the local network interface. It does not require changes to the
server.conf or client config files. You manage split DNS through your OS network settings or router configurations.
How do I troubleshoot DNS leaks with WireGuard?
A DNS leak occurs when queries bypass the VPN tunnel. Verify that your client’s DNS server IP is within the WireGuard subnet (e.g.,
10.0.0.x). Use online DNS leak test sites to check if your public IP matches your VPN IP. If not, ensure your default route is correctly set to the VPN interface and that no other network adapters are prioritizing different DNS servers.