Pi-Hole & Personal rDNS Server Appliance Setup Guide¶

Part 1: Installing the Raspberry Pi OS¶

Overview¶

This guide will walk you through the steps necessary to install and configure a Pi-Hole on your Raspberry Pi, along with a personal recursive DNS server that will keep your DNS queries out of your ISP's immediate view.

The core sections of this guide are broken down into 4 parts:

1. Installing the Raspberry Pi OS (you are here)
2. Installing the Pi-Hole Application
3. Installing the recursive DNS Server
4. Make Pi-Hole work for you!

Getting Started¶

The following steps may seem familiar, because they largely reflect the instructions from Project 1, "Pi Setup." Because by now we are all more experienced with Pi administration, these steps are streamlined. If you get stuck, feel free to reference the Pi Setup page from earlier in the quarter.

If you no longer have Etcher on your laptop, get it again from https://etcher.io. We will use it to install a clean version of the Raspberry Pi OS.

Install Raspberry Pi OS¶

This step is identical to what we did during the initial Pi setup at the beginning of the quarter.

Write Raspberry Pi OS to MicroSD¶

Download "Raspberry Pi OS Lite" from https://www.raspberrypi.org/software/operating-systems/.

Use Etcher to write the image you've downloaded to your microSD. Be aware that this process will overwrite any data that was already stored on the card. This means all the work you have done for Checkpoints 1 through 4.

Update Configuration¶

Etcher will eject the microSD once the image is completely rewritten. We want to edit some files on the SD, so you will need to briefly remove the card before inserting it again.

On macOS or Windows, you'll be limited to accessing the boot partition of the card. Use Explorer or Finder to locate and open the partition.

You must complete the following step before the first boot.

Enable SSH¶

Due to security considerations, the newest versions of Raspberry Pi OS disable SSH by default, but it's easy to turn the feature on so that we can use it for initial setup.

To enable SSH on the first boot, add an empty file named ssh to the boot volume. Instructions will vary slightly between macOS and Windows:

For Mac and Linus users

# Unix-based systems mount external storage to a path in the directory tree. 
# For a freshly written Raspberry Pi OS image, this path will be /Volumes/boot.

touch /Volumes/boot/ssh

For Windows users

# Windows mounts external storage to a drive letter. Replace E: with the letter assigned on your system.

New-Item -type File E:\ssh

Raspberry Pi OS will check for this file during the first startup and proceed to configure the SSH daemon to start automatically. The term daemon, by the way, is the name Unix operating systems use to describe a service that runs in the background (e.g., to respond to network requests).

Initial Boot¶

It's time to boot the Pi for the first time with its clean image. Close your editor and any windows that are open to the microSD so that you can eject the card gracefully from your OS.

• Remove the microSD and insert into the card slot on your Pi.

• Attach to your Pi with an Ethernet cable to your WiFi Router, Cable / DSL Modem, or similar device that has Ethernet jacks and is able to issue IP addresses via DHCP
• Connect power to the designated USB-C port of your Pi

• From terminal or PowerShell, connect to the Pi for the first time by running the following command:

# The default password for pi is raspberry
ssh pi@raspberrypi.local

This command directs your local SSH client to connect to a network host named raspberrypi.local with the username pi.

Since you previously connected to a host by the same name (raspberrypi.local- your "previous incarnation of the Pi used for Checkpoints 1-4), you will likely see this warning:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!

The first time you connect to a host, SSH will bind a cryptographic signature to the hostname, e.g., raspberrypi.local and store it within ~/.ssh/known_hosts. To prevent attacks, SSH warns us when the signature changes for a known host. The signature has changed because SSH will create a new private key every time we set up or rebuild a Raspberry Pi.

Since this is not an attack scenario, resolve the conflict by executing ssh-keygen -R raspberrypi.local from the same terminal that gave you the warning, and it which will remove the existing entry. Now try logging in again via

ssh pi@raspberrypi.local

Using the mDNS service, your computer will resolve the hostname to an IP address SSH will ask you to accept the connection of an unknown device before presenting you with a password prompt.

$ ssh pi@raspberrypi.local
The authenticity of host 'raspberrypi.local (some_IP_address)' can't be established.
ECDSA key fingerprint is SHA256:<some_hash>.
Are you sure you want to continue connecting (yes/no)?

After confirming the prompt shown above, you will see another short message followed by a password prompt.

Warning: Permanently added 'raspberrypi.local,fe80::1b9c:bcf2:acd6:bbbe%42' (ECDSA) to the list of known hosts.
pi@raspberrypi.local's password:

The default password for the pi user is raspberry. After a successful login, you should see the familiar pi@raspberrypi:~ $ prompt.

Choose a New Password¶

Security is still important, so you need to change the default password via the passwd command. You will be guided through three prompts to enter the current password and then to update/confirm the new password.

Default Configuration¶

After you changed the password, make the following changes to make your sysadmin life easier:

Setting your local time zone (example for US Pacific Time)

# You can see a list of timezones by running `timedatectl list-timezones`
sudo timedatectl set-timezone America/Los_Angeles

Set the locale and keymap to US to prevent issues

# Update /etc/locale.gen with your preferences
sudo nano /etc/locale.gen # Find and uncomment the en_US.UTF-8 locale 

# Re-generate locale information after updating the locale.gen file
sudo locale-gen

# Apply new settings
sudo localectl set-locale "LANG=en_US.UTF-8"
sudo localectl set-keymap us

Set a familiar editor as default

# Update default editor selections for the pi user
select-editor

# Modify the same setting for commands that require root privileges.
sudo select-editor

Update Hostname¶

Use the hostnamectl command to set a new name for your device: pihole

# Name it pihole
sudo hostnamectl set-hostname pihole

The main change that hostnamectl makes is visible in /etc/hostname. **Don't forget to change the hostname in /etc/hosts **

# Confirm your hostname is up to date in /etc/hostname
cat /etc/hostname

# Replace any references to raspberrypi in /etc/hosts
sudo nano /etc/hosts

Passwordless Login is Optional¶

After the initial setup, you will only need to SSH into your Pi on rare occasions. The main interaction will be over a Web Admin interface, which uses a separate password. You can set up login via SSH public key like we did originally, but it's optional and not required.

No systemd networking / WiFi / wlan0 / wpa_supplicant¶

We will neither configure a WiFi (wlan0) connection as part of the Pi-Hole setup, nor will we switch teh default networking to systemd networking. This was an important learning opportunity during Checkpoints 1-4, but for the Pi-Hole, it is not necessary and we will keep the stock networking configuration.

Your PiHole will get access to the Internet to download updates and make DNS queries via the wired Ethernet connection. To act as a DNS Server for your entire network, the connection must be reliable, and WiFi can be to temperamental and is generally not recommended for a Pi-Hole.

Update Software Packages¶

Since this is a brand new install, we need to update it again (this can take a few minutes on slow networks):

sudo apt update
sudo apt upgrade
sudo apt dist-upgrade

# We've found that an additional update is sometimes needed after a dist-upgrade
sudo apt update

# Install some useful packages while you're at it
sudo apt install dnsutils

Graceful Shutdown¶

Remember, don't yank the power from your Pi is you can at all avoid it! It can lead to data corruption on the microSD (they aren't as resilient as the drives installed in your laptop). Either issue the sudo poweroff command from an SSH connection, or once you have access to the Pi-Hole web interface, there will be a graceful shutdown option from there as well.

Troubleshooting¶

If you run into issues, you will likely know by now what to check and how to fix things. You can always reference the Checkpoint 1 troubleshooting guides.

Next Up: Installing the Pi-Hole Application¶