DNS Stack — AdGuard + Unbound + dnsmasq

This guide covers setting up a layered DNS stack on OPNsense. Each service has a distinct role and they chain together so that all client DNS traffic is filtered, recursively resolved, and locally registered.

I am only using IPv4 for this guide. Not familiar enough with IPv6, and I don't feel like dealing with for now. I'll come around to it (maybe).

This is made for DNSMasq and Unbound DNS specifically, but same ideas apply if using something else. Same for omada controller (for the most part)

References

• OPNsense Dnsmasq Documentation
• OPNsense Unbound Documentation
• How to Migrate from ISC DHCP to dnsmasq or Kea DHCP in OPNsense

Architecture

Client
  └─► AdGuard Home :53        — ad/tracker filtering, client-facing DNS
        └─► Unbound :5335     — recursive resolver, DNSSEC, caching
              └─► dnsmasq :53053   — local hostname resolution (.internal)
              └─► Root DNS servers — all other queries

Purpose of each service:

• AdGuard — filtering layer. Sits in front so every query is inspected before resolution. Cannot do recursive resolution itself.
• Unbound — recursive resolver. Resolves public DNS from root servers directly (no third-party upstream needed). Forwards internal domain queries to dnsmasq.
• dnsmasq — DHCP server and local DNS registry. Registers DHCP hostnames automatically so hostname.internal resolves without manual DNS entries. Cannot resolve public DNS itself — it needs Unbound as its upstream.

None of these roles overlap. Each is doing something the others cannot.

Step 1 — dnsmasq

Services → Dnsmasq DNS & DHCP → General

Static Host Reservations

Services → Dnsmasq DNS & DHCP → Hosts

Add one entry per static host. A single entry handles both DHCP reservation and DNS registration.

This gives you three things from one entry:

1. DHCP always assigns this IP to this MAC
2. server01 resolves to the IP
3. server01.internal resolves to the IP

DHCP Ranges

Services → Dnsmasq DNS & DHCP → DHCP ranges

Add one range per VLAN. Static reservations defined in Hosts sit outside the pool by MAC binding — they do not need to be excluded from the range manually.

DHCP Options — Push DNS to Clients

Services → Dnsmasq DNS & DHCP → DHCP options

Clients need to receive AdGuard's IP as their DNS server via DHCP. Add one entry per VLAN:

DHCP Options — Omada Controller Discovery

If you are running Omada managed switches or APs on a dedicated MANAGEMENT VLAN, add an additional DHCP option on the MANAGEMENT interface so devices can locate the Omada controller after a reboot.

This is required because broadcast-based controller discovery does not work across VLANs. Without Option 138, Omada devices survive a single session but become orphaned after rebooting because they cannot find the controller on a different subnet.

Step 2 — Unbound

Services → Unbound DNS → General

Query Forwarding

Services → Unbound DNS → Query Forwarding

Unbound forwards .internal queries to dnsmasq instead of trying to resolve them recursively (which would fail — .internal is not a real TLD).

These Query Forwarding entries must exist and must point to the correct port. If dnsmasq DNS is running on port 53053 but the Query Forwarding entries are missing or point to a different port, .internal resolution will fail silently — DHCP will still work, but hostnames will not resolve.

Host Overrides

Services → Unbound DNS → Overrides

Use sparingly. Unbound Overrides are for:

• Devices with static IPs set on the device itself (not via DHCP) — dnsmasq never sees them
• Custom DNS aliases or CNAMEs (e.g. omada.internal → prod-deb-01.internal)
• Any record that needs to exist regardless of DHCP lease state

Do not duplicate entries that already exist as dnsmasq Hosts — they will conflict.

Step 3 — AdGuard Home

Services → Adguardhome

AdGuard sits in front of everything. Clients query it on port 53 (DNS port). It filters, then forwards upstream to Unbound on 5335.

Settings → DNS settings → Upstream DNS servers:

127.0.0.1:5335

This points AdGuard at Unbound. All queries — local and public — go through Unbound. Unbound then decides whether to forward to dnsmasq (.internal) or resolve recursively (everything else).

Settings → DNS settings → Bootstrap DNS:

1.1.1.1
9.9.9.9

Used only to resolve the upstream DNS server address itself at startup. Not used for client queries.

Settings → DNS settings → Clear cache — use this when stale records persist after configuration changes.

Step 4 — Force DNS via NAT

Prevents clients from bypassing AdGuard by pointing at a public resolver directly (e.g. 8.8.8.8).

Firewall → NAT → Port Forward — add one rule per VLAN:

Inverting the destination means: redirect any DNS query NOT already going to AdGuard. Queries going to AdGuard pass through normally. Rogue queries get silently redirected.

Verification

After configuring all three services, verify each layer independently.

Test dnsmasq directly:

dig hostname.internal @<opnsense-ip> -p 53053

Test Unbound directly (bypasses AdGuard):

dig hostname.internal @<opnsense-ip> -p 5335

Test full chain through AdGuard:

dig hostname.internal @<opnsense-ip>

Test public resolution:

dig example.com @<opnsense-ip>

All four should return correct answers. If dnsmasq works but Unbound doesn't, the Query Forwarding entries are missing or wrong. If Unbound works but AdGuard doesn't, the upstream DNS setting in AdGuard is incorrect.

Troubleshooting AKA "It'll be better a different way and I break my fucking internet (again)"

NXDOMAIN for local hostnames

Check in order:

1. Does the dnsmasq Host entry exist with correct MAC and IP?
2. Is dnsmasq DNS listen port set to 53053 (not 0)?
3. Do the Unbound Query Forwarding entries point to 127.0.0.1:53053?
4. Is AdGuard upstream set to 127.0.0.1:5335?

DNS broke after editing dnsmasq settings

Check the DNS listen port field immediately. It is easy to accidentally set this to 0 while editing other settings. Port 0 disables dnsmasq DNS entirely, breaking the Unbound → dnsmasq chain and causing all .internal resolution to fail. Set it back to 53053 and restart dnsmasq.

Stale DNS record after IP change

Clear cache at every layer in order:

1. AdGuard → Settings → DNS settings → Clear cache
2. Restart Unbound (flushes cache on reload if enabled)
3. Client: sudo systemctl restart systemd-resolved (Linux) or ipconfig /flushdns (Windows)

Client not receiving correct DNS via DHCP

Check Services → Dnsmasq DNS & DHCP → DHCP options — confirm option 6 is set for the client's VLAN interface with the correct AdGuard IP.

Verify what DNS the client actually received:

resolvectl status          # Linux
ipconfig /all              # Windows

Docker containers cannot resolve .internal hostnames

Docker containers use their own DNS configuration and do not automatically use the host's DNS settings. Add the VLAN gateway as an explicit DNS server in the container's compose file:

services:
  myservice:
    dns:
      - 10.10.30.1   # VLAN gateway IP — replace with your LAB/SERVERS gateway

Without this, containers query Docker's internal DNS (127.0.0.11) which cannot resolve .internal hostnames.

Rogue DNS bypass not being caught

Verify NAT port forward rules exist for each VLAN under Firewall → NAT → Port Forward and that the destination invert is checked.