Unbound on OPNsense — Why the Resolver Lives on the Router
AdGuard is already running. It's filtering queries, logging traffic, handing back clean responses. The question that comes up quickly is: where do the queries AdGuard can't answer locally actually go? And separately — where do internal hostnames resolve? These are two different problems, and collapsing them into one service creates a stack that's harder to debug and less resilient to change. Unbound on OPNsense is the answer to both, running on the one piece of infrastructure that's always up before anything else is.
Why Not Just Let AdGuard Handle Resolution
AdGuard can forward upstream. It can hold DNS rewrites for internal hostnames. For a simple setup it handles both filtering and resolution in one place, which is appealing. The problem shows up when the Docker host goes down.
If AdGuard is your only resolver — upstream forwarding, internal rewrites, all of it — then when the host running AdGuard goes offline, DNS is gone. Not degraded. Gone. Clients can't resolve anything, including the router, including services that have nothing to do with the Docker host. That's a harder failure than the host being unavailable warrants.
Moving resolution to the router changes the failure mode. The router is a separate physical device. It has a different availability profile. It runs before the Docker host boots and keeps running after the Docker host shuts down. Putting the resolver there means DNS survives independently of whether AdGuard is available. AdGuard becomes a filtering layer in front of a resolver that runs on more reliable infrastructure — and when AdGuard is down, clients fall back to the resolver directly and keep working, just without the filtering.
In an enterprise context this reasoning maps to dedicated DNS infrastructure — separate from the filtering layer, resilient, probably replicated. In a homelab, "dedicated DNS infrastructure" is the router. Same principle, different scale.
Forwarding Mode vs. Full Recursive Resolution
Unbound supports both. In recursive mode, it resolves from root hints — queries go to root servers, get delegated down through TLDs, reach authoritative nameservers, and come back. Nothing leaves the network until Unbound needs to resolve something it hasn't cached. In forwarding mode, unresolvable queries go upstream to a configured nameserver — Google, Cloudflare, NextDNS, whatever you set in System → Settings → General.
Forwarding mode is the right default for a homelab connected to reliable internet. Recursive resolution from root hints adds latency on cache misses, introduces more moving parts, and provides privacy benefits that matter more when you're trying to avoid your ISP's resolver than when you're already forwarding to Google anyway. If your threat model includes avoiding centralised DNS providers entirely, recursive mode is worth the tradeoff. For most homelab setups, it isn't — forwarding to a reliable upstream and spending the effort elsewhere is the better use of time.
One edge case worth naming: the OPNsense docs flag a specific problem with system nameservers in multi-WAN setups with separate gateways. Unbound uses locally created routes to reach them, which breaks when a gateway goes down. Single-WAN setups don't hit this. If you're running multi-WAN, use query forwarding with explicit entries rather than the system nameservers checkbox — it gives you more control over which resolver handles which domain.
Where Internal Hostnames Live
AdGuard has DNS rewrites. Unbound has host overrides. They do the same thing — map a hostname to an IP — but they live in different layers and have different failure modes.
AdGuard rewrites disappear when AdGuard goes down. If a client is in fallback mode, pointing directly at the router, those rewrites aren't reachable. Internal services stop resolving by hostname at exactly the moment you're already dealing with a degraded stack. That's a compounding failure.
Unbound host overrides live on the router. They're available whenever the router is available — which is always, or as close to always as anything in a homelab gets. When clients fall back to the router as their resolver, internal hostnames still resolve. Services are still reachable. The degraded state is genuinely degraded, not effectively broken.
Keeping overrides in Unbound also keeps the filtering layer and the resolution layer independent. AdGuard's job is to decide what to block and what to log. Unbound's job is to know where things are. Mixing those responsibilities into one service creates coupling that makes both harder to change. When you want to swap out AdGuard, you don't also have to migrate a hostname list. When you want to add an internal service, you add it in one place and every resolver on the network benefits immediately — including the fallback path.
The Upstream Choice
This setup forwards to Google's resolvers — 8.8.8.8 and 8.8.4.4. That's a reasonable default for a homelab: reliable, well-operated, fast. The privacy tradeoff is real — Google sees your DNS queries — but for a network that isn't trying to hide from its upstream provider, it's an acceptable operating cost.
If the upstream choice matters for your threat model, Cloudflare's 1.1.1.1 or Quad9's 9.9.9.9 are reasonable alternatives. NextDNS is worth evaluating if you want upstream policy enforcement in addition to AdGuard's local filtering — the two layers complement each other rather than duplicating work. The configuration change on the Unbound side is just the IP address in System → Settings → General. Everything else stays the same.
What doesn't change regardless of upstream choice: Unbound is the resolver, OPNsense is where it runs, and the DNS stack survives independently of the filtering layer. The upstream is a variable. The architecture isn't.
Unbound configuration and OPNsense UI paths described here reflect current behaviour as of early 2026. Verify against current OPNsense documentation before acting on specifics — the service menu structure in particular has shifted across major releases.
