Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท Projects

Project: A Network-Wide Ad Blocker with DNS

Understand how a Raspberry Pi DNS sinkhole such as Pi-hole blocks ads for the whole network: DNS lookups, blocklists, wildcards, caching and router setup, with a runnable resolver model.

Every time a web page loads an ad, a tracker or an analytics script, your device first asks a DNS server: "what is the IP address of ads.example.net?" A DNS sinkhole answers blocked names with a dead-end address, so the ad never loads, on every phone, TV and laptop in the house, without installing anything on them. A Raspberry Pi is the ideal host: it runs 24 hours a day, uses 3 to 5 watts and handles the DNS traffic of a home easily.

The best-known program for this is Pi-hole. This lesson explains how it works, what to configure, and the trade-offs. Pi-hole cannot run on this website, so installation and configuration commands are read-only. The resolver logic is modelled in Python so you can run and extend it.

How DNS works in two minutes

Your phone asks its configured resolver (usually the router, which forwards to your provider) for a name. The answer is an IP address; the phone then connects to it. Answers have a TTL, a number of seconds they may be cached.

flowchart LR
    A["Phone asks: ads.example.net?"] --> B["Pi-hole on the Pi"]
    B --> C{"On a blocklist?"}
    C -- yes --> D["Answer 0.0.0.0"]
    C -- no --> E{"In cache?"}
    E -- yes --> F["Cached answer"]
    E -- no --> G["Ask upstream: 1.1.1.1"]
    G --> F

Blocked names get a useless answer; everything else is forwarded and cached.

Installing Pi-hole

Give the Pi a fixed address first (a DHCP reservation, as in the network lesson). Then follow the project's official installer instructions, reading the script before you run it:

Terminal
curl -sSL https://install.pi-hole.net -o pihole-install.sh
less pihole-install.sh               # read what it does
sudo bash pihole-install.sh

The installer asks for the interface, an upstream DNS provider and which blocklists to enable, and shows an admin password. The web interface lives at http://pi.hole/admin. Finally point your router's DHCP DNS setting at the Pi's IP address, so every device uses it automatically. Alternatively set DNS manually on a single device to test.

A resolver model you can run

The stand-in reproduces the decision logic: exact matches, wildcard parent matches (blocking tracker.com also blocks a.b.tracker.com), an allow-list, a cache with TTL and the forwarded answer. The upstream is a dictionary.

Python Stand-in: a blocking DNS resolver

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that the second example.com is a cache hit, the nested name under ads.example.net is blocked by its parent, and cdn.tracker.example.org is allowed because the allow-list wins.

Blocklists and their parsing

Blocklists are plain text. The common "hosts" format puts a sinkhole address and a name on each line, with comments after #. Pi-hole imports millions of them into a small database. You can parse the same format yourself:

Python Parse a hosts-format blocklist

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Lists overlap heavily, so de-duplicating with a set matters. Choose a few well-maintained lists rather than dozens: more lists mean more broken sites and little extra blocking.

Living with a DNS blocker

  • Broken sites: some pages stop working when a tracker domain is blocked. The query log shows what was blocked at that moment; add the domain to the allow-list.
  • Not a security tool by itself: it blocks known names. It does not scan downloads and does not stop ads served from the same domain as the content (for instance some video platforms).
  • A single point of failure: if the Pi is down, nobody on the network resolves names. Give DHCP a secondary DNS (a public resolver) at the cost of letting some ads through, or run two Pis.
  • Encrypted DNS: modern browsers may use DNS-over-HTTPS and bypass your resolver. Disable it in the browser or block the common DoH hosts if you want complete coverage.
  • Privacy: your Pi logs every name every device asks for. Keep the admin page password-protected and decide how long logs are kept.

Housekeeping

Terminal
pihole status
pihole -g                 # update gravity (the blocklist database)
pihole -t                 # tail the query log
sudo pihole -up           # update Pi-hole itself

Plan an update routine and a backup of its settings ("Teleporter" export in the admin page). The backups lesson covers protecting the SD card too.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a DNS sinkhole return for a blocked name?

    The client gets an address that goes nowhere, so the ad never loads.
  2. 2. Why give the Pi a fixed IP before installing Pi-hole?

    A changing DNS server address would break name resolution for the whole network.
  3. 3. A site stops working after enabling blocklists. What is the usual fix?

    The query log shows which domain was blocked; allow-listing it restores the site.
  4. 4. What is a major weakness of a single DNS blocker Pi?

    It is a single point of failure unless you add a fallback resolver or a second unit.

Summary

  • DNS turns names into IPs; a sinkhole answers blocked names with a dead end.
  • Pi-hole runs on a Pi with a fixed address, and the router hands that address out as DNS.
  • Blocklists are simple text files; de-duplicate and keep only reliable ones.
  • Expect to allow-list occasionally and to plan for the Pi being unavailable.
  • DNS blocking is not a replacement for security software.

Next: Project: A Plant Monitor and Automatic Watering