Mar 9, 2026 • Build • Firewall

OPNsense DHCP — Handing Out the Right DNS Servers

DHCP is the part of the DNS stack nobody thinks about until clients are resolving through the wrong server. The filtering is configured, the resolver is running, the host overrides are in place — and clients are still querying 8.8.8.8 because the DHCP server never got updated. This build covers configuring OPNsense's DHCP server to hand out AdGuard as primary DNS and Unbound as secondary, so every client on the network uses the right resolver without any manual configuration on the client side.

This assumes Unbound is already running on OPNsense and AdGuard is deployed on a host with a static LAN IP. Both are covered in the companion articles. Jump to Commands Reference →

Configure DNS Servers on the DHCP Interface

Navigate to Services → ISC DHCPv4 → [your LAN interface]. The interface-level settings include a DNS servers field that takes up to two entries. This is what gets sent to clients in DHCP option 6 — the DNS server list every client uses to configure its resolver.

Set the DNS servers in this order:

DNS Server 1 : the LAN IP of the host running AdGuard — the filtering layer
DNS Server 2 : the LAN IP of the OPNsense router — Unbound, the fallback

The order matters. Clients use the first server as primary and fall back to the second only when the primary is unreachable. AdGuard goes first because it's the intended resolver for all normal traffic. The router IP goes second as a genuine fallback — not a public resolver, not a gap in the filtering policy, but a local resolver that keeps the network functional when the primary host is unavailable.

If the DNS servers field is left blank, OPNsense hands out its own IP as the DNS server by default, pointing clients at Unbound directly. That works for resolution but bypasses AdGuard entirely. Leave it blank only if AdGuard is not in the picture.

Click Save , then click Apply Changes. The ISC DHCPv4 service restarts and begins handing out the updated DNS server list on new leases.

Verify Clients Are Picking Up the Change

Existing leases won't change until they renew. To verify the new settings immediately, release and renew the lease on a test client, then check which DNS server it's using:

# On a Windows client
ipconfig /release
ipconfig /renew
ipconfig /all

# On a Linux client
sudo dhclient -r
sudo dhclient
resolvectl status

The DNS server listed should match AdGuard's IP. If it doesn't, check that Apply Changes was clicked after saving — OPNsense stages changes and they don't take effect until applied.

To confirm DNS traffic is actually reaching AdGuard, open the AdGuard query log. After a client renews its lease and makes a few DNS queries, those queries should appear in the log. If the log stays empty, the client may be using a cached server address or the DHCP change didn't apply cleanly — a full DHCP service restart from System → Diagnostics → Services will force it.

Verify the Fallback Path

The secondary DNS is only tested when the primary is unreachable, which means it's easy to misconfigure and not notice for months. Worth verifying deliberately: temporarily stop AdGuard on the Docker host, then run a DNS query from a LAN client. The query should resolve — through Unbound on the router — without any client-side changes. Internal hostnames should still resolve correctly since the host overrides live in Unbound, not AdGuard.

When AdGuard comes back up, clients will start using it again on their next query. DNS client behaviour for failover is not deterministic across all operating systems, but in practice most clients switch back to the primary within a few queries once it's reachable again.

Commands Reference

# Set DHCP DNS servers
# Services → ISC DHCPv4 → [LAN interface]
# DNS Server 1: <adguard-host-ip>
# DNS Server 2: <opnsense-router-ip>
# Save → Apply Changes

# Force lease renewal on Windows client
ipconfig /release
ipconfig /renew
ipconfig /all

# Force lease renewal on Linux client
sudo dhclient -r
sudo dhclient
resolvectl status

# Restart DHCP service if changes don't apply
# System → Diagnostics → Services → ISC DHCPv4 → Restart

# Verify DNS query reaches AdGuard
# AdGuard admin → Query Log → watch for client queries after lease renewal

Author

Ryan Mckernan

IT service manager & infrastructure architect turning real-world IT messes into practical, documented fixes. I build systems, streamline ops, and share field notes at Painfully Useful—tested, refined, and repeatable.