# Pi-hole — Network-Wide Ad Blocker and DNS Sinkhole

> Pi-hole blocks ads, trackers, and malicious domains for every device on your LAN by acting as a local DNS server — a simple self-hosted appliance with a polished admin UI.

## Install

Save as a script file and run:

# Pi-hole — Network-Wide Ad Blocker and DNS Sinkhole

## Quick Use
```bash
# One-line installer on a fresh Debian/Ubuntu/Raspbian box
curl -sSL https://install.pi-hole.net | bash

# Or run in Docker with compose
docker run -d --name pihole 
  -e TZ=UTC -e WEBPASSWORD=changeme 
  -p 53:53/tcp -p 53:53/udp -p 80:80 
  -v ./etc-pihole:/etc/pihole 
  -v ./etc-dnsmasq.d:/etc/dnsmasq.d 
  --cap-add=NET_ADMIN 
  pihole/pihole:latest

# Point your router's DNS to the Pi-hole IP, then visit http://PIHOLE_IP/admin
```

## Introduction
Pi-hole is a self-hosted DNS sinkhole that blocks ads, telemetry, and known-malicious domains across an entire network by intercepting DNS queries before they reach upstream resolvers. It started life as a weekend Raspberry Pi project and has grown into one of the most popular privacy appliances in the homelab world, with over 56,000 GitHub stars and active Reddit and Discord communities.

## What Pi-hole Does
- Runs a local recursive or forwarding DNS server (dnsmasq/FTLDNS) that answers queries from every device on your LAN.
- Blocks queries whose domain matches configurable blocklists, returning NXDOMAIN or a null address so ads and trackers simply fail to load.
- Ships with a web dashboard showing real-time query logs, top blocked domains, and per-client stats.
- Supports allowlisting, regex filters, per-group policies, and scheduled list updates via cron.
- Optionally handles local DHCP so clients get DNS + lease from the same box.

## Architecture Overview
Pi-hole layers a PHP/Lua admin UI and a Go/C FTL daemon on top of a patched dnsmasq. FTL (Faster Than Light) records every query into a SQLite long-term database, while a lightweight API exposes live stats. Blocklists are compiled into a local zone file (gravity.list) by the `pihole -g` gravity updater. Upstream DNS can be any recursive resolver you trust (Cloudflare, Quad9, or a paired unbound running locally). Clients send queries to Pi-hole → FTL checks the gravity database → allowed queries forward upstream, blocked ones return immediately.

## Self-Hosting & Configuration
- Install on any Debian-family Linux, or run the official Docker image on amd64/arm64.
- Reserve a static IP for the host and point your router's DHCP DNS setting at it so every client benefits automatically.
- Tune blocklists in Settings → Lists (defaults include StevenBlack's unified hosts list); run `pihole -g` to rebuild gravity after edits.
- Pair with unbound on 127.0.0.1#5335 for full recursive DNS without relying on a public upstream.
- Protect the admin UI with a strong password and expose only to your LAN or behind a VPN/WireGuard/Tailscale overlay.

## Key Features
- Network-wide blocking that works on smart TVs, IoT devices, and phones without installing anything per-device.
- Beautiful real-time dashboard with per-client and per-domain drilldowns.
- Group management lets you apply different blocklists to kids, guests, or IoT VLANs.
- Conditional forwarding integrates with your router so you still see device hostnames.
- First-class support for CNAME-cloaked tracker blocking and deep CNAME inspection.

## Comparison with Similar Tools
- **AdGuard Home** — similar concept, single Go binary, built-in DoH/DoT/DNSCrypt; Pi-hole focuses on depth and community blocklists.
- **NextDNS** — hosted service, no self-hosting needed, monthly fee; Pi-hole keeps data local.
- **Blocky** — lightweight Go DNS blocker designed for Kubernetes; fewer UI features.
- **Technitium DNS** — full authoritative + recursive DNS server with ad blocking; heavier but more flexible for DNS pros.
- **uBlock Origin** — browser-level blocking only; complements Pi-hole for per-page cosmetic filters.

## FAQ
**Q:** Does Pi-hole slow down my network?
A: No — DNS lookups are microseconds and Pi-hole caches aggressively. Most users see faster browsing because ad requests never fire.

**Q:** Can I run Pi-hole on the same box as other services?
A: Yes. The default web UI uses port 80; use `--net=host` + a reverse proxy or pick a different port in `setupVars.conf` if you need to share.

**Q:** How do I avoid losing DNS if the Pi-hole dies?
A: Run two Pi-holes and sync config with Orbital Sync or Gravity Sync, then hand out both IPs via DHCP.

**Q:** Will it break apps that require ads (Twitch, YouTube)?
A: Some. Use the allowlist or per-client group policy to disable blocking for those clients.

## Sources
- https://github.com/pi-hole/pi-hole
- https://docs.pi-hole.net/

---
Source: https://tokrepo.com/en/workflows/a6509f0d-3907-11f1-9bc6-00163e2b0d79
Author: Script Depot