Setup Pi-Hole as a Recursive DNS Server with Unbound 🌱

Installing and Configuring Unbound

  1. Run the following commands in a terminal window:
    # install unbound
    sudo apt install unbound
    # update root hints file
    wget -qO- | sudo tee /var/lib/unbound/root.hints
    # edit unbound configuration
    sudo nano /etc/unbound/unbound.conf.d/pi-hole.conf
  2. Paste the following configuration into pi-hole.conf

        # If no logfile is specified, syslog is used
        # logfile: "/var/log/unbound/unbound.log"
        verbosity: 0

        port: 5335
        do-ip4: yes
        do-udp: yes
        do-tcp: yes

        # May be set to yes if you have IPv6 connectivity
        do-ip6: no

        # You want to leave this to no unless you have *native* IPv6. With 6to4 and
        # Terredo tunnels your web browser should favor IPv4 for the same reasons
        prefer-ip6: no

        # Use this only when you downloaded the list of primary root servers!
        # If you use the default dns-root-data package, unbound will find it automatically
        #root-hints: "/var/lib/unbound/root.hints"

        # Trust glue only if it is within the server's authority
        harden-glue: yes

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

        # Don't use Capitalization randomization as it known to cause DNSSEC issues sometimes
        # see for further details
        use-caps-for-id: no

        # Reduce EDNS reassembly buffer size.
        # Suggested by the unbound man page to reduce fragmentation reassembly problems
        edns-buffer-size: 1472

        # 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, can be increased on beefy machines. In reality for most users running on small networks or on a single machine, it should be unnecessary to seek performance enhancement by increasing num-threads above 1.
        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: fd00::/8
        private-address: fe80::/10

  3. Press CTRL+O, Enter, CTRL+X to write the changes to pi-hole.conf
  4. Continue with the following commands in terminal
    # restart the unbound service
    sudo service unbound restart
    # test a DNS lookup via unbound
    dig @ -p 5335
  5. Back in the web browser, navigate back to the Pi-Hole web interface
  6. Log in if you are not already
  7. Select Settings > DNS
  8. Uncheck any of the previously selected upstream DNS servers
  9. Check the box next to Custom 1 (IPv4)
  10. Enter as the address
  11. Scroll down and click the Save button

Testing the Changes

  1. Open a new tab in the web browser and navigate to
  2. Go back into Pi-Hole and select Query Log from the left navigation
  3. Filter the results on
  4. You should see entries showing the DNS requests forwarding to localhost#5335