Skip to content

Using Unbound as upstream DNS server

Jack'lul edited this page Mar 29, 2025 · 24 revisions

Install Unbound - opkg install unbound-daemon.

Create new /opt/etc/unbound/unbound.conf:

server:
    # Verbosity level
    # 0 - errors only
    # 1 - basic operational information (default)
    verbosity: 0

    # If no logfile is specified, syslog is used
    # The logfile must be within the chroot path
    # or chroot option must be disabled!
    #logfile: "/opt/var/log/unbound.log"

    # pidfile is written before chrooting, so it can be any path
    pidfile: "/opt/var/run/unbound.pid"

    # Run on localhost and accept queries only from localhost
    interface: 127.0.0.1
    port: 5335
    access-control: 127.0.0.1/32 allow
    do-ip4: yes
    do-udp: yes
    do-tcp: yes

    # Whether IPv6 queries are answered or issued
    # May be set to no if you don't have IPv6 connectivity
    do-ip6: yes

    # You want to leave this to no unless you have native IPv6 connectivity.
    prefer-ip6: no

    # To use external root hints file uncomment the following line and run:
    #  wget https://www.internic.net/domain/named.cache -O /opt/var/lib/unbound/root.hints
    #  chmod 644 /opt/var/lib/unbound/root.hints
    #  chown nobody:nobody /opt/var/lib/unbound/root.hints
    # It's a good idea to set up a cron to fetch it once every few months
    #root-hints: "/opt/var/lib/unbound/root.hints"

    # Trust glue only if it is within the servers authority
    harden-glue: yes

    # Require DNSSEC data for trust-anchored zones,
    # if such data is absent, the zone becomes bogus
    harden-dnssec-stripped: yes

    # To enable DNSSEC uncomment the following line and run:
    #  install -m 644 /opt/etc/unbound/root.key /opt/var/lib/unbound/root.key
    #  chown nobody:nobody/opt/var/lib/unbound/root.key
    #auto-trust-anchor-file: "/opt/var/lib/unbound/root.key"

    # Don't use Capitalization randomization as it known to cause DNSSEC issues sometimes
    # see https://discourse.pi-hole.net/t/unbound-stubby-or-dnscrypt-proxy/9378 for further details
    use-caps-for-id: no

    # Reduce EDNS reassembly buffer size
    edns-buffer-size: 1232

    # Perform prefetching of close to expired message cache entries
    # This only applies to domains that have been frequently queried
    prefetch: yes

    # One thread should be sufficient for most users
    num-threads: 1

    # Ensure kernel buffer is large enough to not lose messages in traffic spikes
    so-rcvbuf: 1m

    # Ensure privacy of local IP ranges
    private-address: 192.168.0.0/16
    private-address: 169.254.0.0/16
    private-address: 172.16.0.0/12
    private-address: 10.0.0.0/8
    private-address: fd00::/8
    private-address: fe80::/10

    # Security enhancements, make sure to run the following command:
    #  chown -R nobody:nobody /opt/var/lib/unbound && chmod 755 /opt/var/lib/unbound
    username: "nobody"
    directory: "/opt/var/lib/unbound"
    chroot: "/opt/var/lib/unbound"

    # Use somewhat higher port numbers versus possible NAT issue
    outgoing-port-permit: "10240-65335"

    # Print statistics to the log (for every thread) every N seconds
    # Set to 0 to disable, disabled by default
    #statistics-interval: 3600

    # Optimization for low memory systems
    # Uncomment only when necessary as it reduces the performance
    #outgoing-num-tcp: 1
    #incoming-num-tcp: 1
    #outgoing-range: 60
    #msg-buffer-size: 8192
    #msg-cache-size: 100k
    #msg-cache-slabs: 1
    #rrset-cache-size: 100k
    #rrset-cache-slabs: 1
    #infra-cache-numhosts: 200
    #infra-cache-slabs: 1
    #key-cache-size: 100k
    #key-cache-slabs: 1
    #neg-cache-size: 10k
    #num-queries-per-thread: 30
    #target-fetch-policy: "2 1 0 0 0 0"

# Speed up recursion speed by having the root zone cached
auth-zone:
    name: "."
    url: "https://www.internic.net/domain/root.zone"
    fallback-enabled: yes
    for-downstream: no
    for-upstream: yes
    zonefile: "/opt/var/lib/unbound/root.zone"

Based on docs.pi-hole.net/guides/dns/unbound/, also check the official documentation.

Create /opt/var/lib/unbound and set correct permissions:

mkdir -p /opt/var/lib/unbound
chown -R nobody :nobody /opt/var/lib/unbound
chmod 755 /opt/var/lib/unbound

If you wish to use external root hints file or enable DNSSEC then check the instructions within the config file.

Start Unbound service - /opt/etc/init.d/S61unbound start.

Modify /opt/etc/pihole/pihole.toml:

[dns]
  upstreams = [
    "127.0.0.1#5335"
  ]

Restart Pi-hole service - /opt/etc/init.d/S65pihole-FTL restart.

Clone this wiki locally