Unbound DNS Resolver

Synopsis #

unbound(8) is a validating, recursive, caching DNS resolver included in the OpenBSD base system. It is distinct from unwind(8) , which integrates local resolution with changing network proposals, and nsd(8) , which serves authoritative zones.

This chapter configures Unbound as a LAN resolver on 10.10.10.1. It leaves the router’s own /etc/resolv.conf under resolvd(8) control. This separation allows the router to keep using its normal local resolver path while Unbound listens only on the LAN address.

Unbound is included in base but is not the automatically integrated default resolver. Enabling the daemon does not by itself make either the local host or LAN clients use it.

Choose the Resolver Role #

Use Unbound to provide recursive DNS service to a defined set of clients, such as a LAN. Use unwind for an automatically integrated resolver on a workstation or mobile host. Use nsd for authoritative DNS data.

Do not expose recursive service to the Internet. An open resolver can be abused for reflection attacks and consumes resources on behalf of untrusted clients.

A LAN client queries Unbound, which answers locally or performs recursionA client on 10.10.10.0/24 sends DNS queries to the Unbound resolver at 10.10.10.1 using UDP or TCP port 53. Unbound can use configured local data or a valid cached answer. When needed it queries authoritative servers, following the DNS hierarchy from root through TLD to the relevant zone, reusing cached information when available. Answers return through Unbound to the client. resolvd manages resolver configuration; it does not answer DNS queries.Who answers a DNS query?Clients on 10.10.10.0/24Configured DNS server: 10.10.10.1DNS query and answerUDP or TCP port 53Unbound: 10.10.10.1Uses local data or a valid cached answerPerforms recursion when neededValidates DNSSEC-signed answersQueries and replies as neededCached referrals can skip stepsAuthoritative DNS serversRoot, TLD, and the relevant zoneUnbound follows their referralsresolvd manages /etc/resolv.conf.It configures DNS; it does not answer queries.
LAN clients query Unbound. It uses local data or its cache when possible and queries authoritative DNS servers when needed.

Create the Configuration #

The default configuration path is /var/unbound/etc/unbound.conf. Preserve any existing local policy and create a protected backup before replacing it.

For a resolver at 10.10.10.1 serving 10.10.10.0/24, use:

server:
    interface: 10.10.10.1

    access-control: 0.0.0.0/0 refuse
    access-control: 10.10.10.0/24 allow

    hide-identity: yes
    hide-version: yes
    harden-glue: yes
    harden-dnssec-stripped: yes

    auto-trust-anchor-file: "/var/unbound/db/root.key"

The refusal rule denies queries from clients outside the allowed network. Add IPv6 interfaces and access-control entries only for prefixes that are actually routed and protected.

Initialize or update the DNSSEC root trust anchor with unbound-anchor(8) :

doas unbound-anchor -a /var/unbound/db/root.key
doas chown _unbound:_unbound /var/unbound/db /var/unbound/db/root.key

The command can use built-in trust material when the network is unavailable. The Unbound account must be able to update the anchor and its directory when RFC 5011 tracking is enabled.

Validate the configuration with unbound-checkconf(8) :

doas unbound-checkconf /var/unbound/etc/unbound.conf

Add Local Names #

Small static overrides can use local-zone and local-data in the server section:

    local-zone: "internal.example." static
    local-data: "router.internal.example. IN A 10.10.10.1"
    local-data: "files.internal.example. IN A 10.10.10.20"

Use a trailing dot for complete DNS names. A static local zone answers only data configured for that zone and returns negative answers for other names below it. Larger or dynamically maintained authoritative zones belong on an authoritative server.

Add PF Rules #

Permit DNS from the controlled LAN to the resolver address over both UDP and TCP:

lan = "vlan10"
lan_net = "10.10.10.0/24"

pass in on $lan proto { udp, tcp } from $lan_net to 10.10.10.1 port domain

TCP is required for responses that do not fit in UDP, zone-related operations where allowed, and normal fallback behavior. Do not add a general Internet-facing port 53 rule.

Parse the complete policy before loading it:

doas pfctl -nf /etc/pf.conf
  # Check syntax without changing the active ruleset
doas pfctl -f /etc/pf.conf
  # Load the verified policy

Enable and Test Unbound #

Enable and start the daemon with rcctl(8) :

doas rcctl enable unbound
  # Start Unbound during boot
doas rcctl start unbound
  # Start recursive service now
doas rcctl check unbound
  # Confirm the daemon remains running

Confirm that only the intended address and port are listening:

netstat -na -f inet | grep '\.53 '

From a LAN client, query the resolver directly with host(1) :

host openbsd.org 10.10.10.1
  # Test public recursive resolution
host router.internal.example 10.10.10.1
  # Test the local override

Repeat a public query and inspect service logs when resolution is slow or fails. Use tcpdump(8) to separate client reachability from upstream recursion:

doas tcpdump -ni vlan10 port 53
  # Observe client queries and replies
doas tcpdump -ni egress port 53
  # Observe recursive queries to authoritative servers

Direct Clients to the Resolver #

Static clients can place nameserver 10.10.10.1 in their resolver configuration. DHCP service should advertise 10.10.10.1 as the domain-name server for the corresponding subnet.

Do not make /etc/resolv.conf immutable. On OpenBSD clients, resolvd merges proposals from DHCP, SLAAC, VPNs, and supported network devices. Check which resolver is selected when a client moves between networks.

Make the Router Use Unbound #

The LAN-only design does not change the router’s local resolver. If the router must also query Unbound, add a loopback listener to unbound.conf, permit loopback clients, and configure local DNS resolution to use it.

One possible stable-server design is:

server:
    interface: 127.0.0.1
    interface: 10.10.10.1
    access-control: 127.0.0.0/8 allow
    access-control: 10.10.10.0/24 allow

Before changing the router’s resolver, check how resolvd, unwind, and DHCP or SLAAC proposals update /etc/resolv.conf. Leave resolvd enabled if Unbound serves only LAN clients.

Optional Remote Control #

unbound-control(8) requires a configured control channel. Do not assume that it works merely because the resolver daemon is running.

To use unbound-control, configure a local Unix control socket or use unbound-control-setup as described in the manual. Keep the control endpoint local and restrict filesystem access. Then validate commands such as status, statistics, reload, and cache flush in a maintenance window.

Troubleshooting #

  • A startup failure should be investigated with unbound-checkconf, service logs, address ownership, and existing port 53 listeners.
  • Client timeouts with no packets on the LAN interface indicate client configuration, routing, VLAN, or PF problems.
  • Client packets with no upstream queries indicate Unbound access control, configuration, or DNSSEC state.
  • Upstream queries with no replies indicate routing, provider filtering, or upstream reachability.
  • SERVFAIL can be a correct DNSSEC-validation result. Check time synchronization and validation logs before weakening DNSSEC.
  • Local names that return NXDOMAIN should be checked for trailing dots, zone type, and exact owner names.

See Configure Name Services for authoritative and recursive DNS roles and Build a Simple Router and Firewall for a LAN service example.

Report a bug