Raspberry Pi Projects

Project 2 — Setting up a Pi-hole (Network-Wide Ad Blocker)

What is Pi-hole?

Pi-hole is a DNS sinkhole — it acts as a DNS server for your whole network and intercepts requests for known ad-serving and tracking domains, returning nothing instead of the ad. Because it works at the DNS level, it blocks ads in every app and on every device — phones, smart TVs, game consoles, tablets — without installing anything on those devices.

What You Will Need

Step 1 — Update Your Pi

Start with a clean, up-to-date system:

pi@raspberrypi:~$ sudo apt update && sudo apt upgrade -y
pi@raspberrypi:~$ sudo reboot

Reconnect via SSH after about 30 seconds.

Step 2 — Set a Static IP Address

Before installing Pi-hole, give your Pi a fixed local IP. If your router restarts and assigns the Pi a different IP, DNS will break for your whole network — so this step is important.

Option A (recommended): DHCP reservation in your router. Find the MAC address of your Pi and tell your router to always give it the same IP. The MAC address is shown by:

pi@raspberrypi:~$ ip link show eth0
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 ...
    link/ether dc:a6:32:ab:12:34 brd ff:ff:ff:ff:ff:ff

Option B: Static IP in /etc/dhcpcd.conf (see Project 1 for the full configuration snippet).

Step 3 — Run the Pi-hole Installer

Pi-hole provides a single installer script that handles everything. The project recommends inspecting the script before running it — you can view it at install.pi-hole.net.

pi@raspberrypi:~$ curl -sSL https://install.pi-hole.net | bash

The installer launches a blue text-based setup wizard. Work through the screens:

• Network interface: choose eth0 (wired) or wlan0 (Wi-Fi). Wired is preferred.
• Upstream DNS provider: choose who Pi-hole asks when a domain is not blocked. See the options below — Cloudflare (1.1.1.1) is a good default choice.
• Blocklists: accept the default StevenBlack list. You can add more lists later from the admin dashboard.
• Admin web interface: select On. This gives you the statistics dashboard.
• Web server (lighttpd): select On — this serves the admin interface.
• Log queries: select On — useful for seeing what is being blocked.
• Privacy level: Show everything gives you the most useful statistics on a home network.

At the end of the install, the wizard will display your admin dashboard URL and the randomly generated admin password. Copy this password now — you will need it to log in.

  [i] The install log is in /etc/pihole/install.log

  Pi-hole installation complete!
  ──────────────────────────────────────────────────────────
  Web interface address: http://192.168.1.100/admin
  Admin password:       a7fX92mQ           ← copy this!
  ──────────────────────────────────────────────────────────

Step 4 — Choose Your Upstream DNS

Pi-hole only handles blocked domains itself. For everything else it forwards the query to an upstream DNS provider. You set this during install but can change it at any time in the admin dashboard.

Step 5 — Point Your Router to Pi-hole

This is the step that makes Pi-hole work for every device on your network. You need to change your router's DNS setting to use the Pi's IP address instead of your ISP's DNS servers.

1. Log in to your router admin panel (usually http://192.168.1.1)
2. Find the DHCP settings — not the WAN/Internet DNS, but the DNS that your router hands out to local devices
3. Set the Primary DNS to your Pi's IP (e.g. 192.168.1.100)
4. Set the Secondary DNS to a fallback such as 1.1.1.1 (optional — see note below)
5. Save and apply

After saving your router settings, reconnect a device (or wait for its DHCP lease to renew) then verify it is using Pi-hole as its DNS:

# On Windows:
nslookup google.com
Server:  192.168.1.100    ← this should show your Pi's IP
Address: 192.168.1.100#53

# On Mac / Linux:
dig google.com | grep "SERVER:"
;; SERVER: 192.168.1.100#53(192.168.1.100)

Step 6 — Explore the Admin Dashboard

Open http://192.168.1.100/admin (replace with your Pi's IP) in a browser and log in with the password from Step 3.

Dashboard overview

The home screen shows your key statistics at a glance:

Useful dashboard sections

Step 7 — Add Extra Blocklists

The default StevenBlack blocklist is solid, but the community maintains many specialist lists. Add them in Group Management → Adlists in the admin dashboard, then update gravity:

pi@raspberrypi:~$ pihole -g
  [i] Pi-hole version is v5.18.3
  [i] Neutrino emissions detected...
  [✓] Pulling blocklist source list into range
  [✓] Preparing new gravity database
  [✓] Retrieving blocklist from: https://raw.githubusercontent.com/StevenBlack/hosts/...
  [✓] Storing downloaded list in temporary space
  [✓] Number of domains being pulled in by gravity: 131,818
  [✓] Gravity blocking is enabled

Popular additional lists:

Step 8 — Whitelisting and Blacklisting

Whitelisting (un-blocking a domain)

Sometimes Pi-hole blocks something it shouldn't — a streaming service CDN, a bank's security check, a game's update server. Whitelist from the command line or the admin dashboard:

pi@raspberrypi:~$ pihole -w domain.example.com
  [i] Adding domain.example.com to the whitelist...
  [✓] domain.example.com has been whitelisted

Blacklisting (blocking an extra domain)

pi@raspberrypi:~$ pihole --blacklist annoyingsite.example.com
  [i] Adding annoyingsite.example.com to the blacklist...
  [✓] annoyingsite.example.com has been blacklisted

Regex blacklisting

You can block entire patterns using regular expressions:

pi@raspberrypi:~$ pihole --regex '(.+\.)?ads\..*'
# blocks any domain matching this regex pattern

Step 9 — Keeping Pi-hole Updated

Pi-hole has its own update mechanism separate from apt:

pi@raspberrypi:~$ pihole -up
  [i] See a log of this update at: /var/log/pihole/pihole_updatecheck.log
  [✓] Pi-hole core files are up to date
  [✓] Pi-hole Web Interface files are up to date
  [✓] FTL binary is up to date

Also update your blocklists regularly to catch new ad domains:

pi@raspberrypi:~$ pihole -g     # update gravity (blocklists)

Automate blocklist updates with cron

pi@raspberrypi:~$ sudo crontab -e

Add this line to update gravity every Sunday at 03:00:

0 3 * * 0  pihole -g > /dev/null 2>&1

Optional: Enable DNSSEC

DNSSEC verifies that DNS responses haven't been tampered with in transit. Enable it in Settings → DNS → Advanced DNS settings → Use DNSSEC in the admin dashboard. Your chosen upstream DNS provider must also support DNSSEC (Cloudflare, Google, and Quad9 all do).

Optional: Enable Conditional Forwarding

By default, the Query Log shows device IP addresses (like 192.168.1.12) rather than device names (like Phillips-iPhone). Conditional forwarding tells Pi-hole to ask your router to resolve local IP addresses to hostnames.

Enable it in Settings → DNS → Advanced DNS settings → Use Conditional Forwarding and enter your router's IP and local domain (often local or home).

Troubleshooting Common Problems

Quick Reference