Mar 9, 2026 • Build • Firewall

Unbound DNS on OPNsense — Local Resolver and Host Overrides

OPNsense ships with Unbound DNS enabled but barely configured. Out of the box it forwards to whatever system DNS is set, registers no local hostnames, and returns public IPs for services you're running locally. If you're pointing AdGuard — or any other DNS filter — upstream at your router, what comes back for internal hostnames needs to be useful. This build covers enabling Unbound as your local resolver, wiring it to reliable upstream nameservers, and adding static host overrides so internal services resolve to their actual LAN addresses from anywhere on the network.

DHCP configuration — including handing out the correct DNS servers to clients — is covered in the companion article on OPNsense DHCP. Jump to Commands Reference →

Enable Unbound and Set System DNS

Navigate to Services → Unbound DNS → General. Enable the service if it isn't already running. The listening interfaces should include your LAN interface — the one clients are on. If you have multiple interfaces and only want Unbound answering on specific ones, select them explicitly here rather than leaving it on all interfaces.

Before Unbound can forward queries anywhere, the system needs upstream nameservers configured. Navigate to System → Settings → General and set your DNS servers. This build uses Google's resolvers:

DNS Server 1: 8.8.8.8
DNS Server 2: 8.8.4.4

Back in Services → Unbound DNS → General , check Use System Nameservers. This tells Unbound to forward unresolvable queries to the nameservers you just set rather than attempting full recursive resolution from root hints. For a homelab with reliable upstream internet, forwarding mode is the right call — it's faster and simpler than managing a full recursive resolver.

One thing to be aware of: if you have a multi-WAN setup with separate gateways assigned to different DNS servers in General, do not use the system nameservers option. Unbound uses locally created routes to reach them, which breaks when a gateway goes down. Single-WAN setups don't have this problem.

Click Apply to restart Unbound with the new settings. At this point it should be resolving public hostnames. Verify from a device on the LAN by pointing a DNS query directly at the router IP before changing any DHCP settings.

Add Static Host Overrides

Navigate to Services → Unbound DNS → Overrides. The Host Overrides section is where internal hostnames get mapped to LAN IPs. For each internal service, click the + button in the Host Overrides pane and fill in three fields:

Host — the hostname without the domain, e.g. portainer
Domain — your internal domain, e.g. yourdomain.com
IP address — the LAN IP the hostname should resolve to

For services sitting behind a reverse proxy, all hostnames point to the proxy's IP. The proxy already knows which hostname routes to which backend — Unbound just needs to get the query to the right address. Adding one override per service is the cleanest approach; it keeps the Overrides list readable and avoids wildcard entries that can mask resolution problems when a new hostname doesn't behave as expected.

Save each entry and click Apply after adding your overrides. Unbound does not require a full restart for override changes — applying is enough.

Verify Resolution

From a LAN device pointing at the router for DNS, query one of the hostnames you just added:

nslookup portainer.yourdomain.com <router-ip>

The response should return the LAN IP you configured, not a public address. If it returns the wrong IP or NXDOMAIN, the most common cause is a domain mismatch — the query domain and the override domain need to match exactly. Check that the domain field in the override matches what clients are actually querying.

If Unbound is answering but returning public IPs for overridden hostnames, check that Apply was clicked after saving the override. OPNsense's UI saves to a pending state — changes don't take effect until applied.

Commands Reference

# Enable Unbound
# Services → Unbound DNS → General → Enable: checked
# Listening interfaces: select LAN interface

# Set upstream nameservers
# System → Settings → General
# DNS Server 1: 8.8.8.8
# DNS Server 2: 8.8.4.4

# Enable system nameserver forwarding
# Services → Unbound DNS → General → Use System Nameservers: checked
# Click Apply

# Add host override
# Services → Unbound DNS → Overrides → Host Overrides → +
# Host: <hostname>
# Domain: <internal-domain>
# IP address: <lan-ip>
# Save → Apply

# Verify resolution from LAN device
nslookup <hostname>.<internal-domain> <router-ip>

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.