dnsmasq & WireGuard
DNS Caching for a WireGuard Hub with dnsmasq

The short version
wg0 so peers share a DNS cache while the hub keeps its own resolver. On the Ubuntu 20.04 package setup described here, DNSMASQ_EXCEPT=lo stops the dnsmasq startup hook from registering an unused loopback address with resolvconf.Background
When building a WireGuard hub on Ubuntu 20.04, I wanted to improve DNS performance by adding a local caching resolver. The idea: instead of every peer's DNS query going straight to an upstream server, the hub itself runs dnsmasq to cache responses — speeding up repeat lookups across all connected clients.
There are two DNS paths: the hub uses its existing resolver, and VPN peers query dnsmasq. There's no need to disable systemd-resolved or replace /etc/resolv.conf to set up the peer cache. The failure below applies to the Ubuntu 20.04 package when its resolvconf integration is in use; check your installed service before applying the workaround on another release.
Architecture
The goal is to run dnsmasq exclusively on the WireGuard interface (wg0) — caching and forwarding DNS for VPN peers without touching the host's own resolution:
dnsmasq Configuration
The config is intentionally minimal and scoped to wg0 only:
# /etc/dnsmasq.conf
# Never read upstream servers from /etc/resolv.conf —
# they are declared explicitly below
no-resolv
# Never consult /etc/hosts for name resolution
no-hosts
# Cache up to 10,000 entries in memory.
cache-size=10000
# Use an upstream resolver reachable from the hub.
server=192.168.15.1
# Scope DNS to wg0. interface= also includes loopback by
# default, so exclude it explicitly.
interface=wg0
except-interface=lo
# Bind to the interface addresses, not a wildcard socket.
bind-interfacesInterface versus address
interface=wg0 selects the interface, including any IPv6 addresses on it. Don't add listen-address expecting it to narrow that selection: dnsmasq combines the two. See the dnsmasq manual. Peers must use 192.168.14.11 as their DNS server and route that address through the tunnel. If the hub filters incoming traffic, allow both UDP and TCP port 53 on wg0.The Problem: resolv.conf Gets Hijacked
After starting dnsmasq, a strange symptom appeared: local DNS resolution on the host broke entirely.
Inspecting /etc/resolv.conf revealed the cause:
| State | resolv.conf nameserver | Host DNS |
|---|---|---|
| Before dnsmasq starts | 127.0.0.53 (systemd-resolved stub) | working |
| After dnsmasq starts | 127.0.0.1 ← but dnsmasq isn't listening here! | broken |
Something was rewriting resolv.conf to point at 127.0.0.1 even though dnsmasq was only bound to 192.168.14.11 on wg0.
Tracing the Root Cause
The culprit is a resolvconf integration script at /etc/resolvconf/update.d/dnsmasq. It cannot be removed (system integrity), and it provides no configuration option to disable itself. The solution has to come from elsewhere.
/etc/init.d/dnsmasq start runs start_resolvconf()$DNSMASQ_EXCEPT is empty — the lo loop matches nothingecho "nameserver 127.0.0.1" | resolvconf -a lo.dnsmasq/etc/resolv.conf rewritten to nameserver 127.0.0.1127.0.0.1Looking at the dnsmasq init script at /etc/init.d/dnsmasq, there's a start_resolvconf() function that runs on every start:
start_resolvconf()
{
# If interface "lo" is explicitly disabled in /etc/default/dnsmasq
# Then dnsmasq won't be providing local DNS, so don't add it to
# the resolvconf server set.
for interface in $DNSMASQ_EXCEPT
do
[ $interface = lo ] && return
done
# Also skip this if DNS functionality is disabled in /etc/dnsmasq.conf
if grep -qs '^port=0' /etc/dnsmasq.conf; then
return
fi
if [ -x /sbin/resolvconf ] ; then
echo "nameserver 127.0.0.1" | /sbin/resolvconf -a lo.$NAME
fi
return 0
}There is exactly one early-exit path: if $DNSMASQ_EXCEPT contains lo, the function returns before touching resolvconf. The port=0 branch isn't usable — we need DNS enabled. That for loop is our only lever.
One gotcha worth calling out: the init script only ever looks at the $DNSMASQ_EXCEPT variable from /etc/default/dnsmasq — it never reads except-interface= out of /etc/dnsmasq.conf. The except-interface=lo line above controls dnsmasq's binding; it does nothing for the resolvconf rewrite.
The Fix
Set DNSMASQ_EXCEPT=lo in /etc/default/dnsmasq. This satisfies the early-return condition in start_resolvconf() and prevents any rewrite of /etc/resolv.conf.
# /etc/default/dnsmasq
# Read side: don't let the init script feed dnsmasq the
# resolvconf-generated file (/run/dnsmasq/resolv.conf) as
# its upstream list — ours come from server= lines.
IGNORE_RESOLVCONF=yes
# Write side: with "lo" listed here, start_resolvconf()
# returns before registering dnsmasq with resolvconf,
# so /etc/resolv.conf is never rewritten to 127.0.0.1.
DNSMASQ_EXCEPT=loImportant:
DNSMASQ_EXCEPT=lo is the one that stops the /etc/resolv.conf rewrite — it triggers the early return in start_resolvconf(). IGNORE_RESOLVCONF=yes covers the read direction: without it, the init script points dnsmasq at the resolvconf-managed /run/dnsmasq/resolv.conf for upstream servers. Set both — neither variable alone covers both halves.Since dnsmasq is started and stopped via WireGuard's PostUp/PreDown hooks, the tunnel owns dnsmasq's whole lifecycle:
# /etc/wireguard/wg0.conf (excerpt)
[Interface]
Address = 192.168.14.11/24
# ...keys, ListenPort, etc.
# dnsmasq lives and dies with the tunnel
PostUp = /etc/wireguard/scripts/wg0-postup.sh
PreDown = /etc/wireguard/scripts/wg0-predown.shThe startup script writes /etc/default/dnsmasq dynamically before launching dnsmasq (this replaces the whole file — anything the package ships is overwritten):
#!/bin/bash
# /etc/wireguard/scripts/wg0-postup.sh
# Write /etc/default/dnsmasq before starting.
# DNSMASQ_EXCEPT=lo triggers the early-exit in start_resolvconf(),
# preventing resolvconf from rewriting /etc/resolv.conf.
# IGNORE_RESOLVCONF=yes is the read-side guard; neither alone is enough.
cat > /etc/default/dnsmasq <<'EOF'
IGNORE_RESOLVCONF=yes
DNSMASQ_EXCEPT=lo
EOF
# Start dnsmasq — binds to wg0 (192.168.14.11) only
/etc/init.d/dnsmasq start
exit 0#!/bin/bash
# /etc/wireguard/scripts/wg0-predown.sh
# Stop dnsmasq when the tunnel goes down.
# stop_resolvconf()'s "resolvconf -d lo.dnsmasq" is a no-op here —
# no entry was ever registered.
/etc/init.d/dnsmasq stop
exit 0With this in place:
- dnsmasq binds exclusively to
wg0and caches up to 10,000 records - DNS queries from VPN peers are served from cache or forwarded to
192.168.15.1 - the host's
/etc/resolv.confis left completely untouched - dnsmasq starts and stops with the tunnel — no manual service management
Verifying the Fix
Four quick checks from the hub and a connected peer confirm the cache works and the host is untouched:
# 1. From a connected peer — resolve through the hub's cache.
# Run it twice: "Query time: 0 msec" on the second run
# means the answer came straight from cache.
dig @192.168.14.11 example.com
# 2. dnsmasq must listen on the wg0 address only —
# never 0.0.0.0 and never 127.0.0.1
sudo ss -lunp | grep ':53'
# 3. The host's resolver must be exactly what it was before
cat /etc/resolv.conf # still the 127.0.0.53 stub
# 4. The init script must have skipped resolvconf registration
journalctl -b -t resolvconf | tail -5 # no new dnsmasq entryUpdate — August 7, 2021
Jordan Whited published a post on WireGuard Endpoint Discovery and NAT Traversal using DNS-SD. In the Doubling Down on WireGuard section, he proposes using SRV records to expose WireGuard peer information via DNS Service Discovery.
The approach uses CoreDNS — a plugin-based DNS server written in Go — with a custom plugin (published as wgsd) that answers DNS-SD queries with WireGuard peer metadata. This is a compelling alternative architecture for dynamic peer discovery, eliminating the need for a central controller in mesh topologies where peers need to find each other's endpoints automatically.
Based on the original write-up at sskaje.me. Photo by Ferhat Deniz Fors on Unsplash.