>Hi. I'm Hossein Amini
[■]V1.1
■AMINI.BAS
[▲][▼]
Back to all posts

dnsmasq & WireGuard

DNS Caching for a WireGuard Hub with dnsmasq

Hossein Amini•2021-08-04•4 min read•800 words
dnsmasq & WireGuard

The short version

Run dnsmasq on 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:

DNS query path from a WireGuard peer
VPN Peer
queries DNS
wg0
192.168.14.11
dnsmasq cache
10,000 records
Upstream DNS (cache miss)
192.168.15.1
Cache hit: dnsmasq answers without contacting the upstream resolver. The hub's own DNS follows a separate path.

dnsmasq Configuration

The config is intentionally minimal and scoped to wg0 only:

/etc/dnsmasq.conf
# /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-interfaces

Interface 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:

Stateresolv.conf nameserverHost DNS
Before dnsmasq starts127.0.0.53 (systemd-resolved stub)working
After dnsmasq starts127.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.

1
/etc/init.d/dnsmasq start runs start_resolvconf()
2
$DNSMASQ_EXCEPT is empty — the lo loop matches nothing
3
echo "nameserver 127.0.0.1" | resolvconf -a lo.dnsmasq
4
/etc/resolv.conf rewritten to nameserver 127.0.0.1
5
host lookups fail — dnsmasq never listens on 127.0.0.1

Looking at the dnsmasq init script at /etc/init.d/dnsmasq, there's a start_resolvconf() function that runs on every start:

/etc/init.d/dnsmasq
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
# /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=lo

Important:

The two variables guard opposite directions of the resolvconf integration. 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
# /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.sh

The startup script writes /etc/default/dnsmasq dynamically before launching dnsmasq (this replaces the whole file — anything the package ships is overwritten):

/etc/wireguard/scripts/wg0-postup.sh
#!/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
/etc/wireguard/scripts/wg0-predown.sh
#!/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 0

With this in place:

  • dnsmasq binds exclusively to wg0 and 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.conf is 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:

verify.sh
# 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 entry

Update — 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.

Immediate Window<F6=Window>

' Interactive Console v1.1 — Change display theme:

> SET THEME =