Software-Engineering-Lessons/lesson3.md

Raspberry Pi Pihole (DNS)

In this lesson you'll turn your Raspberry Pi into a Pi-hole, a network-wide ad and tracker blocker. Once it's running, every device on your Wi-Fi gets ads blocked automatically — including devices you can't install anything on.

What is DNS?

When you type example.com into a browser, your computer first asks a DNS server: "what's the IP address of example.com?" DNS is the internet's phone book. Computers only speak IP addresses.

By default, the phone book is run by your internet provider (or whoever your network uses). That means they can see every website you visit. Ad companies lean on this: your devices look up ad servers before the ad loads, and those lookups are how tracking works.

Pi-hole is a DNS server you run on your own network. It checks every name lookup against blocklists of ads and trackers. Bad lookups get a "nope" answer, so the ad never loads. Everything else is forwarded to a real DNS server upstream.

phone / laptop / tablet
    |  "who is doubleclick.net?"
    v
Pi (Pi-hole) --- "blocked"
Pi (Pi-hole) --- forwards good lookups to upstream DNS (e.g. 1.1.1.1)

What you need

• A Raspberry Pi running Raspberry Pi OS, connected to your network (wired ethernet is best)
• Access to your router's admin page

Step 0 — Give the Pi a fixed IP

Pi-hole needs an IP address that never changes, because every device on the network will be pointed at it.

1. On the Pi, find its current IP:

   hostname -I
   

2. In your router's admin page, add a DHCP reservation for the Pi (this binds that IP to the Pi's MAC address so the router always hands out the same one). This is the simplest way to make the IP permanent.

Step 1 — Install Pi-hole

sudo apt update
curl -sSL https://install.pi-hole.net | bash

That downloads and runs Pi-hole's official installer. It walks you through a few questions in the terminal:

• Accept the defaults for everything (press Enter).
• If asked about the upstream/private DNS provider, keep the default unless you have a specific one you want to use.

When it finishes, it prints your admin page URL (it looks like http://192.168.1.42/admin) and a password. Write both down.

Step 2 — Point your network at the Pi

This is the step that makes it network-wide. In your router's admin page, set the DNS server for DHCP to the Pi's IP address (the one from Step 0).

From now on, every device that gets an address from your router automatically asks the Pi for DNS. Phones, laptops, tablets, smart TVs — all covered, no setup on each device.

If your router doesn't let you change its DHCP DNS, Pi-hole has a built-in DHCP server you can run instead (you'd turn the router's DHCP off first). As a last resort, you can set the DNS address manually on individual devices — but the router method is the one to use when you can.

Step 3 — Let the Pi use itself too

By default, the Pi doesn't use Pi-hole for its own lookups. Two things to set up:

sudo usermod -aG pihole $USER

That adds your account to the pihole group so the command-line tools work without asking for a password every time. Log out of the terminal and back in (so the change takes effect).

Optionally, make the Pi itself resolve through Pi-hole by adding this line to /etc/dhcpcd.conf:

static domain_name_servers=127.0.0.1

Be aware of the trade-off: if Pi-hole ever breaks, the Pi itself won't be able to resolve names until you fix it — which can make fixing it annoying.

Step 4 — The admin dashboard

Open http://YOUR_PI_IP/admin in a browser and log in with the password the installer gave you. The pages that matter:

• Dashboard — live stats. Watch the query counter climb and the red "Blocked" numbers appear within a minute of your network using it.
• Query Log — every single name lookup your network made, and what Pi-hole answered. Search it to see what a device looked up.
• Domain Lists — block or allow specific domains for the whole network. Type a domain, add it, choose "Always deny", and that site is dead on every device.
• Settings — choose the upstream DNS provider Pi-hole forwards to, the privacy level, and the blocking mode. "Allow only local requests" is a sensible secure default.

Step 5 — Check it's actually blocking

1. On your phone or laptop, visit a website you know is full of ads. The ads should be gone or greatly reduced.

2. In the dashboard's Query Log, you should see blocked lookups marked in red.

3. On the Pi, confirm the service is healthy:

   pihole status
   

   It should say the DNS server is up and running.

Useful commands

pihole status    # is everything running?
pihole -h        # list all available commands
pihole update    # update Pi-hole and its blocklists (run this now and then)

Blocklists grow stale, so run pihole update once in a while to keep blocking current.

Where this goes next

If you followed the VPN lesson, you can already reach the Pi from anywhere — so once this is done, you can manage your whole house's ad-blocking from your phone at school or on vacation, at http://YOUR_PI_IP/admin through the tunnel.

If you want, the tunnel can also ask Pi-hole for names: add this line to the [Interface] section of your client config, then regenerate and rescan the QR code:

DNS = 10.100.0.1

Now any name lookups the phone makes go through Pi-hole first.