How to Set Up Pi-hole and Unbound

  • Post author:WunderTech
  • Post published:April 15, 2021
  • Post last modified:November 14, 2023
  • Post category:Raspberry Pi
  • Reading time:12 mins read

Today we are going to take a look at the Unbound Pi-hole setup process on a Raspberry Pi, so that it can be used with Pi-hole to increase your privacy.

The first question that needs to be answered is why you might want to set up Pi-hole and Unbound. Ultimately, the answer is somewhat simple, and it’s mostly privacy related. When you use Pi-hole, you generally configure an upstream DNS provider.

The first thing you need to realize is that all traffic is being sent from your external IP address, so depending on who you’re sending the data to, you’re trusting them with your internet traffic. 

The other issue is that periodically, these services will go down. In that case, it might appear as if your internet “stopped” working, when the reality is that it simply cannot resolve DNS names. While this is infrequent, it does happen.

When you set up Pi-hole and Unbound, you become your DNS provider. This ensures that your privacy is maintained, and you will no longer be impacted by potential service outages.

Unbound Pi-hole Setup Process

We will look at how to set up Pi-hole and Unbound below.

1. Setting up Pi-hole

Before we look at how to install Pi-hole on a Raspberry Pi, ensure that you can SSH into your Raspberry Pi with a valid Raspberry Pi operating system.

If you aren’t sure how, please follow these instructions to install Raspbian (Raspberry Pi OS)

pi-hole raspberry pi main ssh screen

1. Run the command below to install Pi-hole. Please review the script to ensure you’re comfortable running it before proceeding (I am not the creator of this script).

curl -sSL | bash
installing Pi-hole. How to Install Pi-hole on a Raspberry Pi.

2. Press Enter until you get to the Static IP address setup. It is extremely important for Pi-hole to have a static IP address. It’s recommended to set up a static IP on your router, but you can do it inside of the Pi-hole setup process as well at a later step.

pi-hole static ip address.

3. Select the correct interface for Pi-hole to use.

pi-hole interface selection.

4. If you didn’t set a static IP address above, you can either use the existing settings, set your own, or skip this step.

pi-hole static ip address setup.

5. Select an Upstream DNS Provider. The Upstream DNS Provider is where DNS requests (which are not found locally) will be forwarded.

pi-hole upstream dns servers.

6. Select Yes to use the default block list. Please keep in mind that this can be configured later, and you do not have to use this list if you don’t want to.

pi-hole blocklists.

7. Select Yes to install the admin interface. This is how you’ll manage Pi-hole.

pi-hole admin interface.

8. Select Yes to install the Admin Web Interface.

pi-hole web server.

9. Query logging is a personal preference (this is what will determine if DNS requests are logged), so select Yes or No based on your preference.

query logging in pi-hole

10. If you selected yes above, you’ll be asked to determine the privacy of DNS requests. Select the option you’d like, then press Continue.

pi-hole privacy mode.

11. Pi-hole will now install! Give it a few minutes to ensure that it’s fully configured. When it’s complete, you’ll receive a confirmation page where you can select OK to proceed. Please note the password given so that you can log in to the web interface!

pi-hole confirmation.

2. Setting up Unbound

The instructions that we will be following were taken straight from the Pi-hole website that shows how to configure Unbound. The goal of these instructions is to strip out some of the explanation (though I highly suggest that you read the official documentation if you can) and simply enter the instructions that need to be followed below.

1. Ensure that Pi-hole is installed on your Raspberry Pi. I have a tutorial here that you can quickly follow to get it up and running.

2. Connect to your Raspberry Pi, either via SSH or by plugging it into a monitor with a keyboard and mouse.

3. Run the commands below to install Unbound and attain the root.hints file needed.

sudo apt install unbound
wget -qO- | sudo tee /var/lib/unbound/root.hints

4. Create a file that will force Unbound to only listen for queries from Pi-hole. There are a few other benefits that can be found on the official Unbound page.

sudo nano /etc/unbound/unbound.conf.d/pi-hole.conf

5. Paste the contents below into the file we just created and save.

    # 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

6. Restart the Unbound server and run the dig command to test DNS resolution. You should see the status as “NOERROR” with an IP address for the server.

sudo service unbound restart 
dig @ -p 5335
unbound pi-hole setup showing what happens when you dig the local address

7. The final test is to ensure that DNSSEC is working properly. First, if you’re interested in learning what DNSSEC is, this is a great explanation. There are two commands that you can run to ensure that DNSSEC is working properly.

dig @ -p 5335

This command should return SERVFAIL with NO IP address.

dig @ -p 5335

This command should return NOERROR WITH an IP address. If both are returned properly, DNSSEC is properly working. 

8. The final step is to configure Pi-hole to use our recursive DNS server. Open the Pi-hole admin page, select Settings then DNS. Uncheck all Upstream DNS Servers, check off Custom 1, and add in the textbox. Save the settings.

pi-hole unbound raspberry pi - configuring pi-hole to use unbound

9. Test to ensure that everything is working as expected and you are fully set up!

Conclusion & Final Thoughts

This tutorial looked at the Unbound Pi-hole setup process. Privacy is something that everyone takes differently. Some people don’t care about it at all, and some want to ensure that their data is protected and not being sent to larger corporations.

If you don’t care about privacy, you probably don’t have a benefit in implementing this Unbound Pi-hole setup process. However, if you do, this is a very easy way to ensure you manage your own recursive DNS server!

Thanks for checking out the tutorial on an Unbound Pi-hole setup. If you have any questions on the Unbound Pi-hole setup process, please leave them in the comments!


Frank is an IT professional with 13+ years experience and the creator of WunderTech. He focuses on sharing his experience with others on computer hardware, servers, software, networking, and self-hosted apps. He has a BS in Computer Information Systems and an MBA. Learn more about Frank in his bio.

This Post Has 13 Comments

  1. Johnnie


  2. Domenick

    This went through without a hitch for me (thus far…) which for some reason was not the case when I initially attempted to set up Unbound a couple months back from the Pi-Hole website instructions… Question I have: I’m running Pi-Hole and Unbound on an RPi4 but I also have a PiZero running AdGuard. Do I need to install Unbound on that Pi as well and change some AdGuard settings for the same time of functionality or does Unbound only play nice with Pi-Hole? Would you be willing to do a video on that as well?

    1. WunderTech

      Yes, you will, unfortunately. The setup might be slightly different, but any device that’s serving DNS will need to implement Unbound (or an alternative).

  3. lichti

    Thank you! Very good tutorial.
    Do you know, how i can make a SSL Certificate for pihole? I wanna access it in my local Network, not over the Internet.

    1. WunderTech

      When you say an SSL certificate for pi-hole, do you mean the admin interface? If so, it’s pretty confusing (and for something that you won’t have that huge of a benefit from if you’re only running it locally), but if you google “https pi-hole web interface” you should find a bunch of tutorials!

  4. Rich

    I followed your directions and every thing seems to work perfectly with one exception. In the PiHole admin GUI under TOOLS > Update Gravity, is an option to update the block list. In the initial configuration of PiHole, using OPENDNS or GOOGLE it worked within a few seconds of clicking update. In the Unbound Configuration it runs for about 40 seconds and comes back with

    [✗] DNS resolution is currently unavailable
    [✗] DNS resolution is not available

    if I go back and turn on google or openDNS, leaving the custom link to the unbound server enable it functions normally again. I went digging in the logs to see if I could find anything but nothing that pointed to a configuration issue, and everything else on my network seems to resolve without a problem. I’m going to increase the logging level of unbound to see if I can at least see what its looking for. Anyone else see this?

    1. WunderTech

      Can you generate a debug log and see if there’s anything out of the ordinary there?

    1. WunderTech

      The very first sentence under “1. Instructions” has the link and source. I simply tried to rip out some of the explanation that might confuse people, with a suggestion to read the official documentation.

  5. Cold Ass Honkey

    Thank you for posting this. These instructions made it SO EASY to install Pi-hole and Unbound on my first Raspberry Pi. It was even easier than when I set them up in Unraid’s Docker.

    1. WunderTech

      Glad that it helped, thank you for the kind words!

  6. Dave

    What settings if any would you need to change on your router? I typically have my DNS servers listed in my router (I use Cloudflare).

    Should I just change the Cloudflare IPs to my PiHole IP?

    1. WunderTech

      That is correct! Just keep in mind that if you only set one and that Raspberry Pi goes down, you will lose domain name resolution. Therefore, it’s best to have a backup (either a second Pi-hole instance or a public DNS server). Just keep in mind that if you use a public DNS server, you might lose some of the ad-blocking capabilities of Pi-hole if the request is sent through that DNS server.

Comments are closed.