Pi-hole is a do-it-yourself home adblocker that can run on basic hardware, such as a Raspberry Pi. This article will discuss the install process as well as some of its key features.
Things you’ll need:
Raspberry Pi/micro-USB charger
Micro-SD card: 32GB will be plenty
Monitor, USB keyboard and mouse, HDMI cable (or appropriate adapter for another display cable)
Some application that will allow you to turn a SD card into a bootable drive from a raw disk image. Popular choices are Win32 Disk Imager and Etcher.
SD Formatter. This also requires that your computer has a way to mount SD cards, either with an SD port or an adapter of some type
SSH utility if you’ll be managing the Raspberry Pi from a Windows machine
First things first, go ahead and download your desirable version of Raspbian, SD Formatter and your image burner. Mount your SD card and format it really quick:
Using the burner then, we basically select Raspbian as our source file and the SD as our destination drive. Raspberry Pis don’t come with any installed firmware, so we essentially have to feed it everything it needs to live.
Once everything is done, attach your monitor, mouse and keyboard to the Raspberry Pi. You should see the RPi splash screen almost right away but experiences may vary at this point. You can refer to this guide if your device isn’t booting properly. This is also a good read for ensuring you aren’t doing something really stupid. Raspberry Pis are tested prior to shipping so you can be reasonably sure you aren’t dealing with a DOA. It’s also worth simply power cycling it without any devices plugged into it.
If everything works as it should, you should see the bootup screen:
Once it finishes, log in with the default credentials pi and raspberry. Now that we’re in, let’s change the default password by utilizing the passwd command. You’ll first be prompted for the current password, followed by the new one. Next we’ll type raspi-config to enter the configuration tool so that we may enable ssh. This allows us to remotely manage the device from any other machine on the network. Navigate to Interfacing Options > SSH and enable the SSH server.
Go ahead and plug it into your network and run an ifconfig to pull its IP on eth0. Now we should be able to SSH into it:
A lot of the unofficial documentation for Pi-hole recommends manually setting all of the devices on your network to use the RPi as their DNS server when, really, all we have to do is make this change on our gateway. So first off let’s give our Raspberry Pi a static IP. Here are instructions from man dhcpcd.conf:
So let’s change directory to /etc/dhcpcd.conf and add set our static address. I advise setting the IP of the RPi outside of your DHCP pool:
sudo nano dhcpcd.conf
Following the instructions from the man pages, I placed my static IP entry just below the sample included in dhcpcd.conf. I left out anything related to IPv6. I also specified the DNS server I wanted to use, in this case OpenDNS:
After the reboot you should lose connection over SSH. Go ahead and get back in once the RPi boots.
With all the prep work out of the way, we’re ready to get Pi-hole installed. On the project’s github page the authors briefly discuss the dangers of piping to bash. We are going to heed their warning and run the installer locally:
sudo wget -O basic-install.sh https://install.Pi-hole.net
sudo bash basic-install.sh
This will begin the install process:
It will walk you through the process of configuring your static IP and DNS servers, but you can inherit your current settings if you did this previously:
Leave the protocols setting defaulted:
We set our IP and gateway address earlier so we can leave the next step alone:
If you want to have access to the web console, select Yes at the next screen:
Select Yes to allow logging:
The installation will now complete. This will take several minutes:
Once installation is complete you will be given a screen with the URL address and default credentials for the admin console. In case you lose or forget your password, you may reset it using pihole -a -p
Take some time now to physically install your new ad-blocker, and then we’ll jump into the admin console! Don’t forget to force your gateway to utilize the RPi as its DNS server.
* You can now use the command pihole -r at any time to reconfigure any settings.
The Admin Console
Open up a browser and log into the Pi-hole console:
Along the top we’ll see some analytics regarding how many domains have been queried versus how many have been blocked. Under the Query Log tab we see more granular information related to when a domain was requested, the client who requested it and the action taken by Pi-hole:
If there are specific domains you would like to either whitelist or blacklist, Pi-hole offers functionality for doing so. Under Settings we are given a GUI interface for a lot of the tasks we can perform from the command line, including restarting various services, flushing our query logs, modifying our DNS settings, enabling a DHCP server, etc. If you have had issues up to this point, you can spin up a debug log under Tools which can assist you in your troubleshooting efforts.