Quick Start: Get Unbound Running in 5 Minutes
Ever wonder why internal DNS queries hit Cloudflare or Google before resolving? Or why a single upstream outage tanks your entire network? Unbound fixes both problems. It runs as a recursive resolver on your own hardware — walking the DNS tree from root servers down to the authoritative nameserver for every query. No third-party resolver. No logs shipped elsewhere.
Fastest path to a working install on Ubuntu/Debian:
# Install Unbound
sudo apt update && sudo apt install -y unbound
# Enable and start the service
sudo systemctl enable --now unbound
# Quick sanity check
dig @127.0.0.1 google.comIf dig returns an A record, Unbound is up and resolving. That’s your baseline. Everything below makes it production-ready.
Deep Dive: How Unbound Actually Works
Recursive vs. Forwarding vs. Caching — What’s the Difference?
Most home routers use a forwarding resolver — they pass your query to 8.8.8.8 and cache the result. Unbound can do that too, but its real strength is full recursion: it starts at the root DNS servers, follows referrals down the hierarchy, and reaches the authoritative nameserver directly. Three concrete benefits fall out of this:
- No single upstream can log or manipulate your queries
- DNSSEC validation happens locally, not delegated to a third party
- You control cache TTLs and negative caching behavior
Core Configuration File
Unbound’s main config lives at /etc/unbound/unbound.conf. The default is minimal. Here’s a solid starting point for a homelab or small office — covers access control, DNSSEC, performance tuning, and basic privacy:
sudo nano /etc/unbound/unbound.confserver:
# Network interface to listen on
interface: 0.0.0.0
port: 53
# Allow queries from your local network
access-control: 127.0.0.1/32 allow
access-control: 192.168.0.0/16 allow
access-control: 10.0.0.0/8 allow
access-control: 0.0.0.0/0 refuse
# DNSSEC validation
auto-trust-anchor-file: "/var/lib/unbound/root.key"
# Root hints file (updated periodically)
root-hints: "/var/lib/unbound/root.hints"
# Performance tuning
num-threads: 2
cache-max-ttl: 86400
cache-min-ttl: 300
neg-cache-size: 4m
prefetch: yes
prefetch-key: yes
# Privacy
hide-identity: yes
hide-version: yes
qname-minimisation: yes
# Logging (adjust verbosity: 0=minimal, 2=debug)
verbosity: 1
log-queries: no
logfile: "/var/log/unbound/unbound.log"Fetch the Root Hints File
The root hints file tells Unbound where to find the 13 root nameserver clusters. It changes rarely, but stale hints can cause subtle resolution failures during infrastructure transitions:
sudo mkdir -p /var/lib/unbound
sudo curl -o /var/lib/unbound/root.hints https://www.internic.net/domain/named.root
sudo chown unbound:unbound /var/lib/unbound/root.hintsEnable DNSSEC Validation
DNSSEC is probably the single biggest reason to run your own resolver. With it enabled, Unbound verifies cryptographic signatures on every DNS response. A compromised upstream can’t inject fake A records — the classic DNS cache poisoning attack. Without DNSSEC, you’d never know it happened.
Initialize the trust anchor (the root zone’s public key):
sudo unbound-anchor -a /var/lib/unbound/root.key
sudo chown unbound:unbound /var/lib/unbound/root.keyVerify it works with two tests:
# Should return AD (Authenticated Data) flag
dig @127.0.0.1 dnssec-failed.org +dnssec
# This domain intentionally has broken DNSSEC — should return SERVFAIL
dig @127.0.0.1 www.dnssec-failed.orgGetting SERVFAIL on www.dnssec-failed.org is the correct result. Unbound refused to hand back a bogus answer. That’s exactly what you want.
Restart and Verify
sudo systemctl restart unbound
sudo systemctl status unbound
# Check config syntax before restarting in production
sudo unbound-checkconfAdvanced Usage
Split-Horizon DNS for Internal Domains
Running internal hostnames like nas.home.lab or vpn.internal? You want Unbound to resolve those locally without touching the public internet. Drop local-zone and local-data directives into your config:
server:
# Define your internal zone
local-zone: "home.lab." static
# Add A records for internal hosts
local-data: "nas.home.lab. IN A 192.168.1.10"
local-data: "router.home.lab. IN A 192.168.1.1"
local-data: "vpn.home.lab. IN A 192.168.1.20"
# Reverse lookup (PTR records)
local-data-ptr: "192.168.1.10 nas.home.lab"Forward Specific Zones to Another Resolver
Active Directory environments and split-DNS VPN setups often need one zone handled by an internal nameserver while everything else resolves recursively. One forward-zone block does it:
forward-zone:
name: "corp.internal."
forward-addr: 10.0.0.53 # Your internal AD DNS serverRate Limiting to Prevent Abuse
Exposing your resolver beyond your LAN — say, on a VPS — makes rate limiting non-optional. Without it, you’re running an open DNS amplifier:
server:
ratelimit: 1000 # Max queries per second per IP
ratelimit-size: 4m
ip-ratelimit: 2000 # Per-IP limitDNS-over-TLS (DoT) Upstream for Forwarding Mode
Prefer forwarding to an upstream but want the traffic encrypted? Unbound supports DNS-over-TLS on the client side. This is a different angle from the DoH/DoT server guide on this blog — here Unbound is the client sending encrypted queries upstream, not the endpoint serving them:
forward-zone:
name: "."
forward-tls-upstream: yes
forward-addr: 1.1.1.1@853#cloudflare-dns.com
forward-addr: 9.9.9.9@853#dns.quad9.netMonitoring with unbound-control
Unbound ships with a stats interface that’s genuinely useful for diagnosing slow resolution or poor cache hit rates. First, enable it:
# Enable remote control in config
# remote-control:
# control-enable: yes
# Setup TLS keys for unbound-control
sudo unbound-control-setup
# Check live stats
sudo unbound-control stats_noreset | grep -E 'total|cache|num'
# Flush a specific cached record (useful during debugging)
sudo unbound-control flush www.example.com
# Dump the entire cache
sudo unbound-control dump_cachePractical Tips from the Field
Automate Root Hints Updates
Root hints rarely change, but keeping them fresh is good hygiene. A monthly cron job handles it without any manual work:
sudo crontab -e
# Add this line:
0 3 1 * * curl -s -o /var/lib/unbound/root.hints https://www.internic.net/domain/named.root && systemctl reload unboundPoint Your Clients at Unbound
On the server itself:
# Edit /etc/resolv.conf or use systemd-resolved stub
nameserver 127.0.0.1For network-wide coverage, configure your DHCP server (router or dnsmasq) to hand out the Unbound host’s IP as the DNS server. Every device on the network picks it up automatically — no per-client config needed.
Check DNSSEC Status for Any Domain
# Look for "ad" (authenticated data) in the flags
dig @127.0.0.1 github.com +dnssec | grep flags
# Detailed DNSSEC chain trace
dig @127.0.0.1 github.com +sigchase +trusted-key=/var/lib/unbound/root.keyLog Format for Debugging
Something not resolving? Bump verbosity temporarily rather than digging through static logs:
sudo unbound-control verbosity 2
# Watch live
sudo tail -f /var/log/unbound/unbound.log
# Reset when done
sudo unbound-control verbosity 1My Experience Running This in Production
I’ve had Unbound running on a 15-device homelab for over a year. It handles roughly 8,000–12,000 DNS queries per day with cache hit rates consistently above 70%. Resolution latency tells the real story: ~30ms forwarded to an upstream dropped to under 5ms for cached hits, and cold recursive lookups to root servers land under 150ms. That’s a 6x improvement on the common path.
More telling: DNSSEC validation caught two actual spoofed responses during a period when I was testing with a misconfigured upstream. Plain forwarding would have silently accepted both. You’d never know.
One gotcha on modern Ubuntu: systemd-resolved already binds port 53, so Unbound won’t start. Two ways around it:
# Option 1: Disable systemd-resolved stub listener
sudo sed -i 's/#DNSStubListener=yes/DNSStubListener=no/' /etc/systemd/resolved.conf
sudo systemctl restart systemd-resolved
# Option 2: Run Unbound on port 5335 and point systemd-resolved at it
# In unbound.conf: port: 5335
# In /etc/systemd/resolved.conf: DNS=127.0.0.1:5335Security Hardening Checklist
- Set
access-control: 0.0.0.0/0 refuseas the catch-all — only whitelist your specific subnets - Enable
hide-identity: yesandhide-version: yesto block version fingerprinting - Use
qname-minimisation: yes— Unbound sends only the minimum necessary labels to each nameserver, cutting data leakage significantly - On a public VPS, firewall port 53 from the internet entirely with ufw or iptables
- Keep Unbound updated —
sudo apt update && sudo apt upgrade unbound
The setup is less involved than it looks. Twenty minutes of config gets you full recursive resolution, DNSSEC validation, no third-party logging, and cached lookups that feel instant. Hard to argue with that tradeoff for any homelab or small production environment.
