Fixing a hole: reinstalling pi-hole

I run two pi-holes on my home network (details here). The older of the two was in need of a refresh. Here are some notes on how I did a reinstall.

For those that don’t know, a pi-hole is a simple ad-blocking solution. You can donate to the project here.


The pi-hole itself can be easily updated over ssh using pihole -up however the OS also needs occasional updating for security. OS updates can be done using sudo apt update and sudo apt full-upgrade

My install was Raspian Stretch OS-lite which is now very much out of date, so I was keen to do a complete refresh. In the end I needed to do a reinstall because the sd card became corrupted and this forced me to take action.


Using the web interface, I saved a copy of my settings using Teleporter. To do this, click Settings > Teleporter and then click Backup. Next, and this is specific to my setup, I pointed my router towards the second pihole so that the internet would stay up while I worked on the pi-hole. Finally, I switched off the Raspberry Pi that runs the pi-hole and backed up the SD card in case anything went wrong.

I am using a mac, so in the terminal I ran diskutil list to determine which device the SD card has been assigned. Then I used sudo dd if=/dev/disk1 of=path/to/PiSDBackup.dmg to generate a backup image. Note that ~ does not resolve and a full path is required for of. This is a slow process for a large card. You can press ctrl + t to get a progress update and calculate for yourself how long it will take.


There are many options to install Raspbery Pi OS. I used balena etcher to flash the Raspberry Pi OS to the SD card (a new one in my case as the old one was faulty). I had already downloaded the zipped OS image from the Rasperry Pi website. This pi-hole runs on a RPi Model 3B+ and this Pi can take Bullseye 64-bit OS-lite. Check the Raspberry Pi page for details of what OS version can run on your hardware.

Once installed, I remounted the card on my mac and made a file in the root directory of the card called ssh to enable ssh on the pi. I did this by cd Volumes/boot and touch ssh

This step is necessary because I was just going to plug it back in and work on it remotely (rather than connect a monitor and keyboard to it to continue the setup).

After reconnecting the ethernet cable and power, I could connect via ssh. If you are doing this for the first time you will need to find the IP address of the Pi. I had previously assigned a static IP to the Pi on the router. Since this works by recognising the MAC address of the device, it assigned the previous IP to the Pi and I could connect using the previous credentials. ssh note that the password was reset to raspberry

The scariest error message

At this point, I met “the scariest error message”. All it means is that the key for the device has changed and doesn’t match the one stored on my mac. The quick solution here is to open the known_hosts file, delete the old key and connect again.

nano ~/.ssh/known_hosts

Find the line with the ip address in question and delete the line. Save and exit with ctrl + x and follow the prompts.

Now ssh will prompt to save a new key and a connection is possible.

Now, over ssh, there are a couple of “housekeeping” things that need attending to before installing the pi-hole software.

  • Change password from the default (you are prompted to do this using pwd when you first login, otherwise use raspi-config)
  • Change hostname. This can be done by editing /etc/hostname or using raspi-config This step is necessary if you run multiple Raspberry Pis on your network.
  • Set locale. Again this can be done in raspi-config

The last thing is to do, again over ssh:

sudo nano /etc/dhcpcd.conf

and then add details of the static IP address that is assigned to the device.

interface eth0

Replace the first address with the assigned IP for the Pi. The router and DNS should be replaced with the IP address of the router.

At this point, we have a Raspberry Pi running OS-lite correctly configured on the network. Now to install pi-hole. Over ssh we can do:

curl -sSL | bash

Next you will be prompted to set up the pi-hole. I followed the recommended default options and selected openDNS as a provider (we will overwrite the settings shortly anyway).

Now, we can contact the web interface of the pi-hole. But first we need to set a password for the web interface. Over ssh do:

pihole -a -p

Now, in a browser enter the IP address followed by /admin/ and you should see the familiar interface. Login using the password set previously. Now select Settings from the menu on the left panel and select the Teleporter tab. Use the browse function to find the gzip file downloaded from Teleporter earlier and click Restore.

That’s it! Your pi-hole should be restored. At this point I pointed my router back to use the pi-hole as DNS server and I was done!

The post title is taken from “Fixing a Hole” by The Beatles which is on “Sgt Pepper’s Lonely Hearts Club Band”. Amazing that this album was recorded on four-track.