1. What Pi-hole Is¶

Pi-hole is a network-wide ad- and tracker-blocking DNS sinkhole with a web management UI, built on top of dnsmasq's core DNS/DHCP logic (via its own fork/successor, FTLDNS, "Faster Than Light DNS"). Rather than blocking ads in individual browsers via extensions, Pi-hole blocks at the DNS resolution layer: it maintains large blocklists of known ad/tracker/malware domains, and when a client on the network queries one of those domains, Pi-hole answers with NXDOMAIN (or 0.0.0.0) instead of forwarding the query — every device on the network gets ad-blocking for free, with no per-device configuration, browser, or OS in the loop.

It's built for the same audience dnsmasq targets — home networks and small labs — but adds the pieces dnsmasq alone doesn't have: curated/updatable blocklists, a query log and web dashboard, and per-client/per-group policy.

2. Installation¶

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

(Running an installer via a piped curl | bash is worth being deliberate about — inspect the script first if that matters to your threat model: curl -sSL https://install.pi-hole.net -o install.sh && less install.sh before executing.) Official Docker images and a manual/offline install path are also available for environments where a network-connected interactive install script isn't appropriate.

3. Architecture¶

Client  →  Pi-hole (FTL/dnsmasq)  →  upstream resolver
              │
              ├── Blocklists (gravity.db)
              ├── Query log (SQLite)
              └── Web UI (lighttpd + PHP, port 80/443)

• FTL (pihole-FTL) is the actual DNS-answering daemon — a dnsmasq derivative extended with blocklist matching, statistics collection, and an API the web UI queries.
• Gravity is Pi-hole's term for the compiled blocklist database (gravity.db), rebuilt periodically from all configured blocklist sources.
• The web UI (pi.hole/admin or the box's IP) is where blocklists, whitelist/blacklist exceptions, per-client grouping, and the query log live — this is the layer that doesn't exist in plain dnsmasq.

4. Configuring Upstream DNS¶

Pi-hole itself doesn't resolve recursively by default — like dnsmasq, it's a forwarder, and needs upstream servers configured (Settings → DNS in the web UI, or /etc/pihole/setupVars.conf / pihole-FTL.conf depending on version):

PIHOLE_DNS_1=1.1.1.1
PIHOLE_DNS_2=1.0.0.1

Two meaningfully different upstream choices exist: - Point at a public resolver (Cloudflare, Quad9, Google) — simplest, but the same trust/privacy trade-off covered in the DNS-attacks and Unbound guides applies: that provider sees every non-blocked query. - Point at a local Unbound instance running recursively — the commonly recommended "maximum privacy" combo: Pi-hole filters and provides the dashboard/blocklists, Unbound (configured with no forwarders, doing genuine recursive resolution from the root) means no third-party resolver ever sees your query stream at all. This is a very common homelab pairing precisely because each tool does the part it's best at — Pi-hole doesn't do validating recursive resolution well, and Unbound has no blocklist/dashboard layer of its own.

5. Blocklists¶

Pi-hole ships with a default blocklist (StevenBlack's hosts-file aggregate) and supports adding more under Settings → Blocklists — each is just a URL to a hosts-file or domain-list format, fetched and merged during pihole -g (gravity update). Popular additions target specific categories (mobile app tracking, cryptomining domains, regional ad networks).

pihole -g          # rebuild gravity from all configured lists
pihole -q domain.com   # query whether/why a domain is blocked

Over-aggressive blocklists are the most common Pi-hole support issue — a site breaking because a shared CDN domain used for both ads and legitimate content got blocklisted. The whitelist (pihole -w domain.com) and regex whitelist/blacklist (pihole --white-regex, pihole --regex) exist specifically to handle these exceptions without disabling an entire list.

6. DHCP (Optional)¶

Like dnsmasq underneath it, Pi-hole can optionally run its own DHCP server (Settings → DHCP), giving it the same automatic DHCP-lease-to-hostname behavior described in the dnsmasq guide. This is usually only enabled if Pi-hole is meant to replace the router's DHCP entirely — running two DHCP servers on the same network without careful scope separation causes lease conflicts, so this is an either/or decision, not an addition.

7. Group and Per-Client Policy¶

Pi-hole supports Groups — named policies that can enable/disable specific blocklists per group, then assign specific clients (by MAC, IP, or hostname) to groups. This is how a household network commonly implements "kids' devices get an aggressive blocklist, everything else gets the default" without separate DNS infrastructure per policy tier.

8. High Availability¶

A single Pi-hole is a single point of failure for the entire network's DNS — if it goes down (an update gone wrong, an SD card failure on a Raspberry Pi) and it's the only configured resolver on client devices or the router's DHCP options, the whole network loses name resolution. Two common mitigations: - Always configure two DNS servers on the router/DHCP scope — Pi-hole as primary, a plain public resolver as secondary fallback (accepting that ad-blocking is bypassed during a Pi-hole outage, which is the acceptable trade-off versus total resolution failure). - Run two Pi-hole instances with gravity-sync or Pi-hole's built-in Teleporter/sync tooling to keep blocklists and settings in sync across both, giving actual redundancy rather than a degraded fallback.

9. Observability¶

The web dashboard is the main interface: queries per client, top blocked domains, query types, and a live query log — effectively the same data BIND's queries logging or Unbound's extended-statistics expose, but pre-aggregated into a UI rather than raw log lines needing separate parsing.

pihole -c          # chronometer — live terminal dashboard
pihole status      # quick enabled/disabled + upstream status check

10. Pi-hole vs. Plain dnsmasq/Unbound¶

11. Reference Links¶

• Official site: https://pi-hole.net/
• Documentation: https://docs.pi-hole.net/
• GitHub: https://github.com/pi-hole/pi-hole