Pi Hole on Ubuntu Server 18.04 Setup
This is reference for precise and complete steps for cofiguring a Pi Hole device on a network. I figured this would be a great way to kick off using the updates to this website to demo the markdown blog piece, and elaborate on another project I've worked on.
This entry goes over what a Pi Hole is, and what it intends to accomplish. It then covers specifics on everything necessary to get a Pi Hole up and running on your home network. This runs the gambit from formatting an SD Card with an operating system, configuring the Raspberry Pi device itself, setting up Ubuntu Server, and installing the Pi Hole application. It also briefly covers some LAN setup required.
There already exists some great documentation on the Pi Hole Homepage and included / linked with the Pi Hole application's source code GitHub. This Ubuntu Pi Wiki is helpful for finding valid operating systems. I would highly recommend those if you get stuck, want to configure differenty, or are just interested.
What is Pi Hole
Pi Hole is a
DNS sinkhole for unwanted network requests. Okay, what does that mean? When an
HTTP request attempts to reach, lets say
google.com, it has to find an
IP Address associated with the
google.com. This requires a
Domain Name System which is part of the normal flow of traffic some describe it as the phonebook of the internet... meh. When this happens, a
nameserver takes your
domain as input, and returns an
IP Address to send the query to. The
sinkhole is the exciting part. For queries with domains that we do not approve of, known addresses of trackers, spammers, scammers, advertisements, etc., we can just fail that name lookup, effectively failing that request.
How Effective Is It
Once you have it setup, you can see for yourself on the dashboard. In my experience, it's far too good not to have. Mine regularly blocks roughly 65% of all requests!
I think this screenshot sums it up quite nicely:
Do The Thing
There is absolutely nothing preventing this project from working on an old laptop or some other hardware that you can setup a server and run the Pi Hole application on. Your steps may change drastically, but the concept remains the same. It may even be better and / or faster.
- Configurable network router, switch, gateway, etc.
- Raspberry Pi 3B+ (or similar) I didn't want to trust wireless for this component
- Pi Power Adapter
- LAN Cable
- USB Keyboard & maybe Mouse
- HDMI Cable & Display
Flashing the SD Card
Ubuntu server image made for a raspberry pi (or something like it): Ubuntu Server Pi 2/3
Format the Image onto MicroSD OSX Commands Displayed
diskutil list to get
Use caution with the following commands. If you choose the wrong
<disk/name> you can rewrite your own hard disk!
diskutil unmountDisk <disk/name> sudo sh -c 'xzcat ubuntu-18.04.2-preinstalled-server-arm64+raspi3.img.xz | sudo dd of=<disk/name> bs=32m' diskutil eject <disk/name>
Setup Raspberry Pi
With the power cord disconnected from the device, install the SDCard, and plug in all the peripherals. You will use a normal LAN slot to plug the device into the network. WiFi can work as well.
Plug in the power cable to boot the device and login. The default username and password are both
Initial Pi Setup
First, get the pi up to date by downloading and installing patches.
sudo apt update sudo apt upgrade sudo apt-get update sudo apt-get upgrade
The device is now technically ready for installation of the Pi Hole application. While you're here, you might as well change the default login
password, and setup
ssh so you can remotely configure and debug the device.
Change the password with
passwd and follow the prompts.
Install ssh server for remote access, and check the status.
sudo apt install openssh-server sudo systemctl status ssh
Reboot the device with
At this point you can continue locally, or
ssh into the device. Get the IP and MAC address on the pihole using commands:
ip a or
ifconfig -a. Connect using
Install Pi-hole Application
There are a couple methods of installing it, using
clone the project and executing the
basic-install.sh seemed like the most pain-free and trustworthy way.
git clone --depth 1 https://github.com/pi-hole/pi-hole.git Pi-hole cd "Pi-hole/automated install/" sudo bash basic-install.sh
During the setup, I chose the following options:
- This is more imporant than you may think. The SD Card has both a
write limit. No card lasts forever.
- This is more imporant than you may think. The SD Card has both a
- enable FTL
- Choose to enable static IP
There is a key displayed at the end of setup, this is the default admin console login key. You can accidentally ignore it and change the password later with:
sudo pihole -a -p
Configure Network (LAN)
Note: These settings will vary by manufacturer and consider updating your BIOS first.
Get the IP and MAC addresses again they might have changed after installing Pi Hole.
Reserve / assign a static DHCP address in the Router / Switch / Gateway that your end-user devices connect to, and for which the DNS sinkhole to be used for.
Configure your network device to point to the Pi Hole for DNS queries.
I only configured my router (gateway) to direct DNS queries to the Pi Hole within the
DHCP group. That means any devices assigned outside that group will NOT automatically be configured. They can still use the Pi Hole as their DNS server, but they must be configured manually to point to it.
If everything worked, you should now be able to view the Pi-hole Admin Console. If your network isn't allowing local DNS names, try connecting directly to the IP of your Pi Hole such as
Test the Setup
Make sure everything starts up on reboot.
sudo reboot pihole status
I also made sure my entire network came back in a bad scenario like an outage. I achieved this simulated power outage for all network connected devices conveniently by just yanking the plugs. This may not always be smart or completely safe, but it's my real world test.
These are the domains that will fail the name lookup, and therefore the request entirely.
Use the admin console to update the default
gravity. I found many quality blacklists by googling and searching around on
At some point, someone on the network will probably want to load a site that is being blacklisted. An
HTTP 404 error will probably occur in this case. This is what whitelisting domains is for.
This can be achieved by adding the domain to the
whitelists in the
admin console. This is a good resource if you are unsure which domains to add for which service.
I found this cool github project to make maintaining your whitelists easier.
If there is anything incomplete or innacurate, please don't hesitate to reach out to me and I will make corrections.