If you have not heard of Pi Hole, then you are missing something really cool. But don’t worry, this Pi Hole tutorial will help you get rolling in minutes. Pi Hole is a network-wide ad blocker. In a typical home environment, this can cut out almost all ads to all devices in your home, without having to install an adblocker on every single device. Some devices do not even have a provision of installing adblocker.
In this Pi Hole setup guide, I will cover everything from PiHole introduction to installation and configuration. I will also share some basic maintenance steps and tips.
I debated a lot before writing this guide. Ad blockers are detrimental for content creators. By using an adblocker, you will essentially be wiping out any income that sites like this one can generate from your visit. Even the ads that you do not click on can generate income. But there are several malicious sites that PiHole can protect you from. Therefore, if you decide to install PiHole for Ad Blocking, I request you to whitelist the sites/domains you visit. PiHole is free and entirely dependent on donations. So if it helps you please consider donating.
Table of Contents
- What is PiHole
- Pi-Hole Installation
- Configuring Devices to Use PiHole
- Pi Hole Configuration and Customization
- PiHole Tweaks
- PiHole Tutorial – Closing Thoughts
What is PiHole
As said before, Pi-Hole is a network-wide ad blocking app. It setups a DNS Server and handles all DNS requests generated from your home network. In simple terms, a DNS server is an internet address registry that helps locate the server using the domain name. When you visit any site, a query is made to the DNS server to locate the IP Address (location) of the server to connect to. Pi-Hole puts itself between your device and the DNS Server and blocks out any requests to known ad servers.
Here are some of Pi Hole’s awesome features/advantages:
- Free!!! All you need is a device to run Pi-Hole on – Raspberry Pi, Linux Machine, or Docker.
- No client-side ad block software required.
- Over 100,000 ad-serving domains blocked. You can expand this using server freely available user-created lists. My setup blocks over 1,000,000 domains.
- Blocks ads on any device, including those Smart TVs and other devices that do not allow you to make any modifications.
- Reduces bandwidth and improves overall network performance. As you can see from the above picture. Over 50% of the ad requests were blocked before they are downloaded.
- Provides an awesome dashboard to monitor various stats on ad blocking. Pi-Hole has a built-in web server that provides an easy to use Web UI for administration.
Pi Hole can be installed on any Linux compatible system or Raspberry Pi. If you do not use Linux, don’t worry, Pi Hole setup on Raspberry Pi is quite easy and I will walk you through it step by step. Pi Hole can also be installed on Docker. In this guide, I am going to show you how to install Pi Hole on Raspberry Pi 3. These instructions should also work on any other model of Raspberry Pi, including the Zero. In the future, I will update this Pi Hole tutorial to include setup instructions for Linux.
Pi Hole Setup Guide – Raspberry Pi
Setting up Pi Hole on Raspberry Pi is one of the easiest ways to get started on whole home adblocking. On a Raspberry Pi, Pi Hole will function as a self-contained unit. Therefore, no messing with web servers etc. on a Linux system. PiHole needs ports 53, 80, among others. So if you have other services running on the same system, there could be conflicts. So having a separate Raspberry Pi for this purpose is more efficient and hassle-free. Plus, it is only going to cost you $2 to $5 in electricity cost for the whole year to keep the Pi running 24/7. So let’s get started with Pi Hole setup guide for Raspberry Pi.
Step 1: Requirements
Here is what you will need to follow this Pi Hole tutorial successfully:
- Raspberry Pi 3B+ – Although any version of Raspberry Pi should work quite well for Pi Hole purposes. I recommend this Raspberry Pi 3B+ kit which comes with power adapter, case, and heat sinks. A kit is cheaper than getting the items separately.
- SD Card – I use Sandisk Ultra 16GB Micro SDHC UHS-I Card 98 MB/s.
- Power Adapter – This is already included in the kit listed above.
- Ethernet Cable – Although you can use Wifi, I strongly recommend a wired connection for reliability since all your network DNS requests will depend on this.
In addition, you will access to a keyboard and monitor to connect your Raspberry Pi temporarily for setup (or your can use SSH for remote setup) and may be 1 to 2 hours to complete the setup depending on your proficiency. [Read: 15 most used SSH commands for Raspberry Pi – SSH for Raspberry Pi]
Step 2: Install Base OS – Raspbian Stretch Lite
Once you have Raspberry Pi and accessories, move on to setup the base operating system for Pi Hole. There are several that you can use but I recommend Raspbian Stretch Lite, which is headless and uses very little resource. Don’t worry, although the OS is headless (no GUI desktop environment) you can still manage Pi-Hole using its web interface.
Head over to Raspbian download page and download the latest version of Stretch Lite OS. Either method (ZIP or Torrent) will work.
Once downloaded, insert your SD card into the computer, write the downloaded Raspbian Stretch lite image to the SD card. Note that this is NOT as simple as copying the zip file. You will have to use a utility such as Etcher to write the downloaded ZIP file to the SD card, as shown below.
Note that Etcher will format your SD card while copying the Raspbian image.
Step 3: Configure Raspbian Lite OS
Enable SSH Access (optional but highly recommended)
I strongly suggest enabling SSH access on Raspbian Lite as this allow you to remotely manage your PiHole server. For this, insert the SD card with Raspbian Lite OS into your computer and create an empty file called ssh in the root/base folder of your SD card. [Read: Best SSH clients for Android: 10 free SSH Apps for remote admin]
On Windows, you can right-click and create a text file called ssh.txt (make sure Windows file extensions are turned on). Then, rename the file and delete the file extension.
On Linux and Mac, you can use touch ssh command to create the file.
Start Raspbian Lite OS
To start Raspbian Lite OS, insert the SD card into RPi, connect the ethernet cable, and power up it up.
If you did not enable SSH, then connect the Pi to a monitor and keyboard and continue with this PiHole tutorial. When the login prompt appears, use username pi and password raspberry to login. Once setup, you will rarely have to mess with your Pi Hole setup again.
If you do not have a monitor or keyboard attached to Raspberry Pi, you can connect to your Pi Hole through SSH. But for this, you will need your Raspberry Pi’s network IP address.
Raspberry Pi’s Network IP
Login to your Wifi router administration page, look through your list of connected clients and note down the IP address of your Raspberry Pi. In my case, it is 192.168.1.26. While you are there, setup a static IP for your Pi Hole Raspberry Pi (this is required). Most modern routers rarely change the IP addresses of connected clients. However, when it does happen your Pi Hole instance will not be available and there is a good chance you may not have internet access as well.
The procedure to set static / fixed IP for clients vary by router. Check this page for some examples of how to do this. The screenshot below shows how to do this on UniFi controller.
Connect to PiHole Through SSH
Once you have the PiHole’s IP address, use a SSH Client such as MobaXterm and connect to your Raspberry Pi through SSH using:
- IP Address / Host, which in this PiHole guide is 192.168.1.26
- Port 22
Use username pi and password raspberry to login.
Change Default Password
Raspbian Lite’s default password, as stated above, is raspberry. For security, you must change this. One your logged into your Raspberry Pi command prompt (either through SSH or locally using monitor and keyboard), use the following command to set a new password:
That is it. You have now prepped your base OS for setting up Pi Hole.
Step 4: Pi Hole Installation
To setup Pi Hole, from the command prompt (locally or remotely through SSH) use the following commands in sequence:
wget -O basic-install.sh https://install.pi-hole.net sudo bash basic-install.sh
There is also one line installation code. Although PiHole is trustworthy, piping in bash is risky. So I recommend the above method. Then, follow the PiHole installer prompts as shown below. Read through the introduction and press Enter to continue.
Next, you will see a donation screen. If PiHole ends up saving you bandwidth and improving network performance then I strongly recommend donating.
As stated before, a static IP is needed for Pi Hole to function properly. We already took care of this before. PiHole has DHCP capabilities, which means it can act as your DHCP server and assign IP addresses to your clients. However, most routers can do this well as well. Therefore, we are going to let your router handle that and not use PiHole’s DHCP server. Only a static/fixed IP is needed to proceed further.
Next, you will have to choose which Raspberry Pi network interface to use. Recent models of Raspberry Pi have both wired (ethernet) and Wifi interfaces. As stated before, for reliability, we are going to use ethernet (eth0).
PiHole puts itself between your DNS server and clients. A DNS server is usually your ISP (many of them are notorius for hijacking searches etc.) although you may use other custom DNS servers such as Google’s public DNS. Recently, Cloudflare introduced their own privacy focussed DNS server. Unlike other DNS services that usually sell your DNS lookups data to ad companies, Cloudflare maintains no logs beyond 24h and does not sell your data. Therefore, we are going to use that one for our upstream DNS server. We will choose Cloudflare as shown below.
You may refer to this discussion and choose any other DNS provider you please.
PiHole blocks ads using blocklists which contain known ad serving domain names. PiHole has no domains listed in blocklists, to begin with. So you won’t be blocking ads until you enable a few third-party blocklists. The installer offers you a list of suggested third-party blocklists. I suggest leaving the defaults enabled as shown below and continuing with PiHole installation. This will get you started with blocking over 100,000 ad/tracking domains.
For protocol, select IPV4 (will work for most people). But you can leave the defaults as is in the unused protocol (IPV6) will be disabled automatically.
Finally, confirm the network and static IP details. Gateway IP shown here is the router’s IP address, which PiHole installer should pull automatically.
Next, you will see a warning on IP conflict in case Pi Hole receives the same IP address as another device on your network. With modern routers, this should be a rare occurrence.
Then, you will an option to enable PiHole web interface, which I strongly recommend.
PiHole web interface needs a web server to be available over the browser. PiHole comes with a lightweight web server option using Lighttpd. For Pi Hole on Raspberry Pi, I suggest turning on the Lighttpd web server option, as shown below. If you are installing PiHole on other platforms (eg. Linux home server, docker, etc.) and have separate web servers running, then you may want to consider disabling Lighttpd and making PiHole available through existing web server. Showing how to do this is beyond the scope of this PiHole tutorial. So we will keep moving with the Lighttpd option.
Next, you will see an option to enable or disable query logging. Querry logging gives you all the cool statistics about how many requests were blocked, etc. This is also important to troubleshoot if a legitimate website that you visit is not working properly. I have had troubles while signing up credit cards, online shopping through affiliate links, etc. But leaving query logging on will increase writes to your SD card and reduce its life. I have already burned two SD cards in less than a year. So after using PiHole for a few weeks and making sure everything is working fine, you may want to consider disabling query logging through the admin web interface. Alternatively, you may consider moving your logs to RAM as described later in this guide. For now, choose On and proceed.
The final installer screen should show your password to use for the web interface. Note it down. If you forgot to note this down or would like to change the password, see the commands listed later in this guide.
All steps to install PiHole are now done. You should see a Pi Hole installation confirmation message as shown below.
Next, I will walk you through configuring Pi Hole server.
Configuring Devices to Use PiHole
There is not a lot of configuring to do on Pi-Hole. You can actually start using it right away. But some basic PiHole configuration can make it even better. So let’s get on with it. In short, you will have to provide your Pi-Hole server’s IP address in place of DNS server IPs in your router/devices.
Note: Most devices provide options two list at least two DNS name servers. Unless you have two PiHole instances running at home, you will provide one DNS IP address and leave the other (rest) blank as shown below. If you specify a second DNS IP that is not a PiHole server, then ad block won’t work on some devices. Having two PiHole instances is recommended if you are worried about one device failing and cutting of your internet temporarily.
Configuring Your Router – Whole Home Ad Blocking
To block ads on a network level, meaning all devices connected to your home network won’t see ads, you will have to manually change your DNS server IPs on your router. While many routers allow manually setting DNS servers, some do not make this advanced option available. Custom router firmware such as DD-WRT, OpenWRT, and Tomato, make open up this option among several others. So if you do not see an option to change DNS name servers, consider switching to one of the supported free alternate router firmware.
The advantage here is that there is only one place you will need to update your DNS server IP instead of each and every device. However, there are some disadvantages:
- Per-host tracking will be unavailable all requests to PiHole will appear as if they are coming from your router. My personal opinion is that this is not a big deal for a typical home user. I do not use it. But if you absolutely need this
- You will not be able to connect to devices with their hostnames as PiHole cannot resolve hostnames. Again, not a big deal for a typical home user in my opinion.
If the above two disavantages are deal breakers for you, then you partially overcome those by using PiHole Hosts file or fully by advertising PiHole’s IP address via dnsmasq in a router (if supported).
Note that if you chose this method, you will have to renew the DHCP leases provided by the router. The easiest way to do this is to restart the router.
Configuring Your Devices
The procedure to manually set DNS servers will depend on the device and the operating system. In general, you will have to open the network connection and find the place to put in DNS server IP manually. Covering this beyond the scope of this guide. But here are some external references:
In the above references, in place of public DNS IPs, use your PiHole IP address.
Pi Hole Configuration and Customization
To configure PiHole, access the web interface by visiting Pi Hole admin page through: http://IP-ADDRESS/admin/. Login using the password provided by the PiHole installer and you should be ready to go. There is not much you need to configure on PiHole.
Expand Pi-Hole Block Lists
PiHole with third-party blocklists block over 100,000 domains. That is a great start. But most PiHole users may want to expand that. The PiHole community is excellent and several users have created and continue to maintain custom expanded blocklists. Wally’s list is a notable one.
Pick one of the 3 available lists. This is a great start. Some users have concatenated many lists to create their own (like this one). I caution you to not add every blocklist you can find. This can break your internet experience and cause troubles. The basic / default lists are a great starting point and block over 100,000 domains.
Once you have the list finalized add it to PiHole blocklist by going to Settings->Blocklists, as shown below.
Click Save and Update.
Pi Hole YouTube Ad Blocking
PiHole Youtube Ad blocking is a hit or a miss as the ad servers can change constantly. But this has not stopped some users from creating and maintaining Youtube ad blocklist for PiHole. I have had good success with the following list:
However, PiHole YouTube ad blocking is not robust and I do get ads sometimes.
Expand PiHole Whitelist
If you went with one of the expanded blocklists, then many useful domains can be blocked, which can lead to either the webpage or app not functioning properly. CNN app, GitHub webpage, etc. are some examples that did not function properly for me. In addition, referral or affiliate links (eg. SlickDeals) may not work correctly. In such cases, it is a good idea to whitelist certain known good domains. Whitelisted domains take priority and will be whitelisted even if they appear in blocklists.
Ideally, you should manually whitelist each domain you really trust yourself. But this can take a long time to build. But available this whitelist worked well for me (for including referral sites). To whitelist domains from this GitHub project, you will need access to commandline on your PiHole raspberry pi either locally or remotely through SSH. Run the following commands in sequence:
sudo apt-get install git-core cd ~ git clone https://github.com/anudeepND/whitelist.git cd whitelist/scripts sudo chmod +x whitelist.sh sudo bash whitelist.sh
You should see an output similar to the one below on successful whitelisting.
If you would also like to whitelist referral site domains then run the following command as well:
sudo bash referral.sh
That is all there is to configuring and customizing Pi Hole.
Note that whitelisting referral sites will allow some ads to be displayed. But, for most users whitelisting these referral sites should be fine.
Basic Pi Hole Commands
Almost all admin work to keep your Pi Hole setup running can be done through the web interface. But with commandline, you can do those and more (eg. changing web UI password). I am providing some useful examples below. A lot more are documented here and here.
Change PiHole Web Interface Password
- pihole -a -p – Change WebUI password
Status, Realtime log and Statistics
- pihole status – Pihole Status
- pihole -t tail log – realtime log
- pihole -c – pihole statistics
Whitelist and Blacklist
- pihole -w -l – List Whitelisted domains
- pihole -w example.com – Add example.com to whitelist
- pihole -w -d example.com – Remove example.com from whitelist
- pihole -b -l – List blacklisted domains
- pihole -b example.com – Add example.com to blacklist
- pihole -b -d example.com – Remove example.com from blacklist
- pihole -up – Udpate PiHole
- pihole -l off – Query logging off
- pihole -l on – Query logging on
Enable Disable PiHole
- pihole enable – Enable PiHole
- pihole disable – Disable PiHole permanently
- pihole disable 10m – Disable PiHole for 10 minutes
- pihole disable 60s – Disable PiHole for 1 min
- pihole uninstall – Uninstall PiHole
Enable or Disable Query Logging
As I mentioned before, query logging provides a lot of useful information as shown below. In addition, you get a lot of statistics.
However, this is quite taxing on the SD card as a lot of information gets written to them, which will burn them in months. Whether this is acceptable or not is your decision. Note that this only affects the PiHole log and not the database that long-term database.
Automatic List Updates
PiHole blocklists and whitelists are constantly updated and maintained by the maintainers. PiHole automatically updates your lists on a weekly basis (Sunday). Updating the lists sooner is typically unnecessary and increases server load.
Move Query Logging to RAM – Protects SD Card
Extensive writing can damage SD card. For this reason, I suggested turning off query logging. But what if you want to leave it on? A good option, in this case, is to move your logs to RAM instead of SD card. So all your logs on Raspbian Lite will be written to RAM instead of SD card, thereby prolonging the life of SD card.
For this, I use and recommend Log2ram. The GitHub page has all the information for you to get started and customize, which only takes about 5 min or less total. So I am not going to go into the details of setting it up in this PiHole guide.
If you see ads on some devices and not on some then try rebooting your router first to renew DHCP leases. If you still continue to see ads, then the DNS server IP may be hardcoded on the device (eg. Chromecast). Some allow you to change it and some do not. Look through your device’s network settings to check if your change your DNS IP to your PiHole’s IP or even better your internet gateway’s (since you have already configured this to run through PiHole).
This happened when my SD cards failed. If you no internet, make sure PiHole is up and running buy trying to SSH into it or opening the web UI. If not try restarting Raspberry Pi by pulling the power. Another option is to restore your DNS server IPs on router/device back to upstream DNS IP (126.96.36.199 and 188.8.131.52 for Cloudflare). If the internet works, then the problem is with PiHole setup. You may try to reconfigure using pihole -r command.
PiHole Tutorial – Closing Thoughts
I tried to cover almost all the instructions for a basic Pi Hole setup in this guide. There are several other advanced tweaks such as PiHole host file, dnsmasq in the router, etc. that were left out of this guide. But the information in this PiHole tutorial is more than enough to get you rolling with whole home Ad blocking. If you want to this setup another level, you can consider setting up DNS over HTTPS that Cloudflare supports. All your DNS lookups will be encrypted and will offer you additional security and privacy.
Once again, I want to reiterate that by blocking ads, you are essentially hindering content creativity. So if you visit legitimate sites that depend on ad revenue, then please consider whitelisting those. In addition, please consider donating to PiHole development.
I hope you enjoyed this PiHole installation and configuration guide.