Unbound in resolver mode versus forwarder mode

OPNsense ships with Unbound, a validating, recursive, caching DNS resolver. The question every operator has to answer first is: do we want Unbound to walk the DNS hierarchy from the root down, or do we want it to forward every query to an upstream resolver (a service like Cloudflare 1.1.1.1, Google 8.8.8.8, Quad9, or an internal resolver)? The OPNsense GUI calls these two modes recursive resolver and forwarder. They look superficially similar — both answer DNS queries on port 53 — but the operational implications are different in every dimension that matters.

This lesson covers the two modes at the level the firewall operator needs, when to choose which, and what changes in the system when the choice is made.

What the two modes actually do

In resolver mode (the OPNsense default on a fresh install), Unbound accepts a query from a client, looks up the answer itself by walking the delegation chain from the root, validates the chain with DNSSEC if enabled, caches the result, and returns it. The walk is the same walk the foundational DNS lesson covered: root, TLD, authoritative. Unbound does this on the firewall itself; no upstream recursive service is consulted for the answer.

In forwarder mode, Unbound accepts a query from a client and sends that query to a configured upstream resolver (or list of resolvers). The upstream does the walk; Unbound waits for the answer, caches it, and returns it. The firewall does not perform recursion itself; it delegates recursion to whoever it forwards to.

The two modes produce the same answer for a client query when both work. The differences are in who does the work, who sees the query, and what happens when a piece of the chain is broken.

What changes for the operator

Five things differ between the two modes in production:

Who sees the queries. In resolver mode, the queries the firewall makes to root, TLD, and authoritative servers come from the firewall itself, with the firewall source IP, going to many different destinations. In forwarder mode, every client query (and every cached miss) goes to the upstream resolver you configured. The upstream sees the client source IP if it is on a different subnet, and the upstream sees the full pattern of what every client on the network is doing. This is a privacy difference that matters in environments with a privacy policy.

Where latency comes from. In resolver mode, the first query for an uncached name pays the cost of the full delegation walk — tens to hundreds of milliseconds across multiple round-trips. Subsequent queries within the TTL are served from the cache. In forwarder mode, every uncached query pays one round-trip to the upstream plus however long the upstream takes to walk the chain itself; the cache on the upstream usually shields the firewall from the walk cost after the first hit.

Who you trust to validate. In resolver mode, Unbound validates DNSSEC itself; the trust chain ends on the firewall. In forwarder mode, the upstream does the validation, and the firewall has to trust that the upstream did it correctly. A DNSSEC-validating forwarder (a public validating resolver, an internal BIND or Unbound configured to validate) gives you the same chain; a forwarder that does not validate silently breaks the DNSSEC guarantee.

What happens when upstream is broken. In resolver mode, the firewall still works if every external recursive resolver is unreachable: Unbound walks the chain itself. The failure mode is the firewall’s own connectivity. In forwarder mode, when every configured upstream is unreachable, Unbound cannot answer; the firewall returns SERVFAIL for every query. This is the operational reason resilient forwarders point at two or more upstreams (or use a gateway group).

What the firewall log shows. Resolver mode produces very little outbound traffic on port 53 — only the queries the chain itself requires. Forwarder mode produces outbound traffic on port 53 proportional to client query volume. Both are normal; the difference shows up in capacity planning for an upstream link that cannot carry the volume.

When to choose forwarder mode

Three production patterns justify forwarder mode:

Internal recursive resolver exists. The estate has its own recursive resolver (often Active Directory-integrated, often a BIND or Unbound on a Linux host) that is the system of record for internal zones and forwards external queries to the public DNS. Pointing OPNsense Unbound at this resolver centralises validation, internal-zone authority, and logging in one place. This is the standard enterprise pattern.

Privacy contract requires it. Some compliance regimes require that no external DNS service see client query patterns. Forwarding to a corporate resolver that drops external queries at the edge satisfies the contract; resolving from the firewall does not, because root and TLD servers see the firewall’s queries. The choice is rarely “no upstream” — it is “this specific upstream with this specific contract”.

Upstream is more reachable than root. Some network designs (captive portals, isolated lab networks, satellite links with captive resolvers) cannot reach the root servers directly. In those environments forwarding to the captive resolver is the only way to make DNS work at all. The trade-off is that the captive resolver is now a hard dependency.

When to choose resolver mode

Three production patterns justify the default:

The estate is self-contained. The firewall is the only resolver and the only egress path. Forwarding to a public recursive resolver adds a dependency and a privacy exposure that the deployment does not need. Resolver mode keeps everything on the firewall.

DNSSEC validation is required and you do not trust upstream to do it. A bank, a healthcare network, a government estate that handles signed-zone data cannot delegate DNSSEC validation to a third-party resolver; the validation has to terminate on the asset that does the lookup. Resolver mode gives that.

Outbound port 53 must reach the Internet. If outbound port 53 to the public recursive resolvers is blocked or metered, forwarding breaks. Resolver mode works because the walk uses the standard DNS hierarchy on port 53 to authoritative servers, which most networks allow.

Verifying the mode the firewall is actually running

The operator’s first diagnostic is to ask the running Unbound what it is doing.

$ unbound-control -c /var/unbound/unbound.conf stats | head -20

server.current.time: 2026-08-14 12:34:56
server.start.time: 2026-08-12 03:14:15
server.uptime: 2 days 09:20:41
total.num.queries: 4823917
total.num.cachehits: 4612183
total.num.cachemiss: 211734
total.num.prefetch: 18294
total.num.recursivereplies: 211734
total.requestlist.avg: 1.732
total.requestlist.max: 24
total.requestlist.overwritten: 0
total.requestlist.exceeded: 0
total.recursion.time.avg: 0.043824
total.recursion.time.median: 0.027113
msg.cache.count: 4821
rrset.cache.count: 9843

If total.num.recursivereplies is approximately equal to total.num.cachemiss and total.recursion.time.avg is non-trivial, the firewall is doing the recursion itself. If total.num.recursivereplies is near zero and total.recursion.time.avg is tiny, the firewall is forwarding.

The check is read-only and safe; the daemon does not need to be reloaded.

When the mode choice and the network do not agree

The most common production incident for a firewall that was put in forwarder mode without realising it: the operator changes the upstream list (adds a second provider, removes a deprecated one), the change applies, but the change is invisible until the upstream the firewall was relying on stops answering. The mode choice was made once, the upstreams changed, and the trust model drifted.

The fix is a change-control discipline that re-asserts the mode on every Unbound-relevant change. The OPNsense backup captures the Unbound configuration; the operator reviewing the backup should be able to answer which mode is this firewall running and why from the configuration alone. If the answer is not in the configuration comments, the change record has lost information.

Summary

• Unbound runs in one of two modes: resolver mode (Unbound walks the chain itself) or forwarder mode (Unbound forwards to a configured upstream).
• The choice is a trust, privacy, and operational dependency decision, not a preference.
• Resolver mode is the default and the right choice for self-contained estates that need DNSSEC validation to terminate on the firewall.
• Forwarder mode is the right choice when the trust model puts an upstream resolver in the path: an internal recursive resolver, a contracted DNS service, or a captive resolver on an isolated network.
• A single upstream in forwarder mode is a single point of failure; always configure a second upstream or a gateway group.
• Verify the running mode with unbound-control stats and a comparison of total.num.recursivereplies to total.num.cachemiss.