Hugey Studios
Apps
Info
Blog
Terms
Pi-Hole Setup
06-18-2019

Keywords: raspberry, pi, advertisements, dns, sinkhole

Pi Hole on Ubuntu Server 18.04 Setup

Author: Tyler Hugenberg Originally Posted On: Hugey Studios

Introduction

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 domain name google.com. This requires a DNS, or 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:

image

Do The Thing

Equipment

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

Get an 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 <disk/name>

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 ubuntu.

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 sudo reboot

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 ssh ubuntu@192.168.1.XXX.

Install Pi-hole Application

There are a couple methods of installing it, using git to 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:

  • Disable log queries
    • This is more imporant than you may think. The SD Card has both a capacity and a write limit. No card lasts forever.
  • enable FTL anonymous mode.
  • 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 http://192.168.1.123/admin.

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.

Further Configuration

Blacklists

These are the domains that will fail the name lookup, and therefore the request entirely.

Use the admin console to update the default blacklists with gravity. I found many quality blacklists by googling and searching around on github.

Whitelists

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.

Good Luck!

If there is anything incomplete or innacurate, please don't hesitate to reach out to me and I will make corrections.