Pi-Hole with Unbound - Full Setup Guide by ᏤⵁŁTRⵁИł€
This guide will walk you through setting up a Pi-hole with Unbound, gaining you network-wide ad and malware domain filtering, as well as your own local recursive DNS server.
These instructions assume you have a functional LAN setup, access to a desktop or laptop with internet access, as well as basic networking and command-line experience.
- steps under each category ( notes ) $ commands to enter (copy-paste into your console)
- ASSEMBLE PARTS
-
A Pi with proper accoutrements. The Pi 4 will be the simplest, as it does not require any adapters.
== OPTION 1 ==
Pi 4: https://www.adafruit.com/product/4295 (1 GB RAM model is more than enough) Case: https://www.adafruit.com/product/4301 Power supply: https://www.adafruit.com/product/4298
== OPTION 2 ==
Pi Zero W: https://www.adafruit.com/product/3400 Power supply: https://www.adafruit.com/product/1995 (or anything with similar specs) Case: https://www.adafruit.com/product/3446 OTG adapter: https://www.adafruit.com/product/2910 Ethernet Adapter Dongle: https://www.amazon.com/gp/product/B00FFJ0RKE (We will disable WiFi later, and a hardwired connection is far more reliable.)
== OPTION 3 ==
Pi Zero W kit: https://www.amazon.com/Vilros-Raspberry-Starter-Official-Case-Power/dp/B0787BXR3P/ Ethernet Adapter Dongle: https://www.amazon.com/gp/product/B00FFJ0RKE
-
MicroSD Card (32 GB or larger to be safe) - this "high endurance" model is a good choice: https://www.amazon.com/dp/B07P3D6Y5B/ (NOTE: DO NOT use any old microSD card you might have lying around. You need something reliable.)
-
MicroSD card to USB adapter (to be used for imaging and config editing) https://www.adafruit.com/product/939
- CAT 5e or CAT 6 cable (to connect pi-hole to switch or router) https://www.amazon.com/Monoprice-Cat6-Ethernet-Patch-Cable/dp/B003L1AET2/
- DOWNLOAD RASPBERRY PI OS "LITE" IMAGE
- WRITE IMAGE TO MICROSD CARD
-
Insert microSD card into USB adapter, and use Etcher to write image: https://www.balena.io/etcher/
- After imaging is complete, eject and then re-plug SD card to mount the filesystem.
- ENABLE SSH
- Create an empty file named ssh (no extension) and place it in the /boot directory on the card.
- DISABLE BLUETOOTH AND WIFI
-
In the /boot directory, open config.txt with a text editor.
-
Add the following two lines to config.txt:
dtoverlay=disable-bt dtoverlay=disable-wifi
- Save and exit
- CONNECT AND BOOT THE PI
-
Eject microSD card from computer and install into the pi.
-
Connect the pi to an open port on your router or switch. Use the USB OTG adapter and ethernet dongle if using a pi Zero.
- Connect pi to power supply. The pi will boot (it will take several minutes).
- FIND THE IP ADDRESS OF YOUR PI AND RESERVE IT
-
Log into your router (or whatever box is your DHCP server), and look under the DHCP Client List.
-
Find the new device on your LAN. Record its IP address and MAC address.
- Reserve the IP address in your DHCP server so it has a permanent lease.
- SSH INTO PI-HOLE
-
You can do this through the terminal, or with a program like PuTTY on Windows. Host Name is the IP address you recorded Port is 22 Connection Type is SSH
- Login with default credentials: Username: pi Password: raspberry
-
CHANGE HOST NAME
$ sudo nano /etc/hostname
- Change the name to something else, such as pi-hole
- Write out and exit
$ sudo nano /etc/hosts
- Change the last entry after 127.0.1.1 to the same thing you entered into /etc/hostname
-
Write out and exit
(Keep in mind that this will only change the hostname; not the username you log in with (pi).)
-
CHANGE PASSWORD
$ passwd
- Follow prompts
- The next time you SSH to your pi, you will use this password. This does NOT change the password for the web admin console which we will use later.
- INSTALL PI-HOLE
-
SSH to your pi
$ curl -sSL https://install.pi-hole.net | bash
- This will take a while to download and install. Eventually you will be in the config screens.
-
Upstream DNS resolver doesn't matter; you will replace it later. Just choose Google for now.
-
For Protocols, de-select IPv6 unless you know that you need it.
-
When asked about a static address, make sure it matches the IP you found and reserved in your DHCP server.
-
You can use the default block lists. These are easily changed later in the web admin console.
-
Web Interface: select ON.
-
VERY IMPORTANT: When you see the "Installation Complete" screen, make sure to copy down the Admin Webpage login password (which we will now change in the next step).
If you ever need to run this setup routine again, use: $ pihole -r (don't do this now).
-
CHANGE WEB ADMIN PASSWORD
$ pihole -a -p
- Follow prompts
(This will only change the password for the web admin console; not the password to login via the terminal.)
- INSTALL UNBOUND:
-
In your web browser, go to https://docs.pi-hole.net/guides/unbound/ (You will need this handy to copy a block of text.)
-
Back in your SSH session, enter the following:
$ sudo apt install unbound
$ wget -O root.hints https://www.internic.net/domain/named.root
$ sudo mv root.hints /var/lib/unbound/
$ sudo nano /etc/unbound/unbound.conf.d/pi-hole.conf
- Copy config text from pi-hole Unbound website listed above.
- Paste the copied text into this file. Write and exit.
$ sudo service unbound start
-
TEST UNBOUND DNS RESOLUTION
$ dig pi-hole.net @127.0.0.1 -p 5335
- We are asking dig to use the localhost for DNS lookup
$ dig sigfail.verteiltesysteme.net @127.0.0.1 -p 5335
- This should return a SIGFAIL error
$ dig sigok.verteiltesysteme.net @127.0.0.1 -p 5335
- SET PI-HOLE TO USE UNBOUND AS DNS RESOLVER
-
Log into web admin console using the pi IP address followed by /admin.
For example: http://192.168.1.100/admin or whatever your IP is Use the new password for the admin console you just set. - Go to Settings > DNS On the left side, un-check any selected Upstream DNS servers (chosen during initial setup) On the right side, check Custom 1 (IPv4) and enter 127.0.0.1#5335 (Only enter IPv6 address if needed) Scroll down and click Save.
- SET PI-HOLE AS YOUR LOCAL DNS SERVER
-
Log into your router / DHCP server
-
Under Internet / WAN settings, DNS Address should be set to obtain a dynamic address from your ISP. (For most home users, this is the case. If you have a fixed IP, you would know.)
-
Under DCHP settings, enter the pi-hole IP address for BOTH the Primary and Secondary DNS servers. Or, make sure secondary DNS servers are entered as 0.0.0.0 (This is to make sure your network only uses the pi-hole for DNS requests.)
- Log in to any additional access points on your network, and change the DNS servers accordingly. We want to make sure the entire network is sending all DNS requests to our local DNS resolver.
- TESTING
-
Browse the internet on various devices connected to your network. If it does not work, review the steps.
-
Test for ad blocking. Disable any browser-based ad blocking, and then try these sites: https://canyoublockit.com/ https://ads-blocker.com/testing/
-
Use the sites listed at https://www.routersecurity.org/testdns.php to view your DNS servers. Keep in mind that some warnings are just because you are not using that provider's specific product. Only one result should be returned for these tests, which is your local DNS server. If you get multiple DNS server results, go back and review the steps.
(These tests will show an IP provided by your ISP. Don't worry - that is your Public IP and not your ISP's DNS server. This is as it should be, since YOU are hosting your own DNS resolver. Also, don't worry about DNS "leaks" reported on these tests, which only matter if you are testing a VPN.)
- Check for DNSSEC signature validation: https://dnssec.vs.uni-due.de/ http://www.dnssec-or-not.com/ https://www.cloudflare.com/ssl/encrypted-sni/
- ADD ADDITIONAL BLOCKLISTS AND WHITELISTS (optional)
-
You can add additional blocklists to filter out more things. Keep in mind that some legitimate things you use may break with increased blocking, so you might need to whitelist certain domains. Also realize that the same domains will likely appear on multiple blocklists coming from different sources.
-
Modify blocklists in the Admin Console under Group Management > Adlists
This is a good general blocklist: https://dbl.oisd.nl/
A few specific blocklists for problematic devices or services: https://github.com/kboghdady/youTube_ads_4_pi-hole/blob/master/youtubelist.txt https://raw.githubusercontent.com/Perflyst/PiHoleBlocklist/master/android-tracking.txt
https://raw.githubusercontent.com/Perflyst/PiHoleBlocklist/master/SmartTV.txt
https://raw.githubusercontent.com/Perflyst/PiHoleBlocklist/master/AmazonFireTV.txt -
Modify whitelists under Whitelist
This is where you can add specific domains that you need access to, but which pi-hole is currently blocking.
Recommended General Whitelist: https://raw.githubusercontent.com/raghavdua1995/DNSlock-PiHole-whitelist/master/whitelist.list
- VIEW STATS
- View the Query Log and Long Term Data to see what clients are making frequent requests. You may find some clients or services are more active than you might expect! It may take some time for stats to populate after initial setup.
- UPDATE
-
At some point, you will log into the web admin console and see "Update Available" at the bottom of the screen specified for one or more pi-hole components. Updates are also announced at https://pi-hole.net/blog/. To update, SSH to your pi-hole:
$ pihole -up