NETWORK
PROTECTION

What is Pi-hole?

Pi-hole is a network-wide ad blocker that runs as a DNS sinkhole. Instead of blocking ads in each browser or app, you configure your network to use Pi-hole as your DNS server. Every DNS query from every device on your network passes through Pi-hole—and Pi-hole decides whether to resolve it or block it.

How DNS-Based Blocking Works

When you visit a website, your computer needs to translate the domain name (example.com) into an IP address. This is called a DNS query.

1. Your device asks Pi-hole: "What's the IP of ads.example.com?"
2. Pi-hole checks its blocklist
3. If blocked: Returns 0.0.0.0 (or NXDOMAIN)
4. If allowed: Forwards to upstream DNS, returns real IP

The ad server never gets queried, the ad never loads, and you save bandwidth.

Installation Methods

Official Installer (Recommended)

# Run installation script
curl -sSL https://install.pi-hole.net | bash

Docker

# Run Pi-hole in Docker
docker run -d \
    --name pihole \
    -e TZ=America/New_York \
    -e WEBPASSWORD=yourpassword \
    -p 53:53/tcp \
    -p 53:53/udp \
    -p 80:80 \
    -p 443:443 \
    -v pihole-data:/etc/pihole \
    -v pihole-dnsmasq:/etc/dnsmasq.d \
    --dns=127.0.0.1 \
    --restart=unless-stopped \
    pihole/pihole:latest

Manual Installation

# On Debian/Ubuntu
sudo apt update
sudo apt install -y git curl wget dnsmasq

# Clone and install
git clone --depth 1 https://github.com/pi-hole/pi-hole.git /tmp/pihole
cd /tmp/pihole/automated%20install/
sudo bash basic-install.sh

Hardware Requirements

• Raspberry Pi: Any model works (Zero to 4)
• VM: 1GB RAM, 2GB disk minimum
• Old Computer: Works on minimal hardware
• Docker: Any host with Docker

First-Time Setup Wizard

After installation, the setup wizard guides you through configuration:

1. Select Static IP: Choose a fixed IP address
2. Choose Upstream DNS: Select default DNS provider
3. Select Blocklists: Choose which ad lists to use
4. Enable Web Interface: Set admin password
5. Choose Protocol: IPv4 or IPv6

Web Interface Access

# Access via hostname
http://pi.hole/admin/
http://pihole.local/admin/

# Or via IP
http://192.168.1.100/admin/

Login with the password you set during installation.

Command-Line Basics

# View Pi-hole status
pihole status

# Enable/Disable blocking
pihole enable
pihole disable

# Temporarily disable (5 minutes)
pihole disable 5m

# Update Pi-hole
pihole -up

# View version
pihole -v

Configuring Your Router

To use Pi-hole network-wide, change your router's DHCP settings:

1. Login to your router
2. Find DHCP settings
3. Set DNS servers to Pi-hole IP
4. Save and restart router

Upstream DNS Providers

Pi-hole forwards allowed queries to upstream DNS servers. Choose privacy-respecting providers:

DNS-over-HTTPS (DoH)

Encrypt DNS queries to prevent snooping:

# Configure DoH in web interface:
# Settings > DNS > Upstream DNS Servers
# Check: "Use HTTPS"

# Cloudflare
https://cloudflare-dns.com/dns-query

# Google
https://dns.google/dns-query

# Quad9
https://dns.quad9.net/dns-query

DNS-over-TLS (DoT)

# Configure DoT in web interface
# Settings > DNS > Upstream DNS Servers

# Cloudflare
tls://cloudflare-dns.com

# Google
tls://dns.google

# Quad9
tls://dns.quad9.net

DNSSEC

Enable DNSSEC to verify DNS responses are authentic:

# In web interface:
# Settings > DNS > DNSSEC
# Check "Use DNSSEC"

Pi-hole will validate DNSSEC signatures before returning results.

Understanding Blocklists

Blocklists are lists of domain names that Pi-hole will block. They can include:

• Advertising domains
• Tracking domains
• Malware domains
• Phishing domains
• Social media trackers

Default Blocklists

Pi-hole comes with several pre-configured blocklists. View them in:

# Web interface: Group Management > Blocklists
# Or directly in /etc/pihole/*.list

Default lists include StevenBlack's list, MalwareDomains, and others.

Adding Custom Blocklists

1. Go to Group Management > Blocklists
2. Click "Add"
3. Enter the list URL (raw text file, one domain per line)
4. Add a comment
5. Click "Add"
6. Update gravity (pull list into Pi-hole)

# Popular blocklist sources:
# StevenBlack Hosts
https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts

# Firebog
https://v.firebog.net/hosts/AdguardDNS.txt
https://v.firebog.net/hosts/Easyprivacy.txt
https://v.firebog.net/hosts/Prigent-Crypto.txt
https://v.firebog.net/hosts/Prigent-Malware.txt

# oisd
https://oisd.nl/basicdomains
https://oisd.nl/mtmalwaredomains

Updating Gravity

After adding blocklists, update Pi-hole's database:

# Via web interface:
# Tools > Update Gravity > "Update"

# Via command line:
pihole -g

Why Whitelist?

Sometimes legitimate domains get blocked. You need to whitelist them to restore functionality.

Whitelisting Domains

# Via web interface:
# Whitelist > Add domain

# Via command line:
pihole whitelist doubleclick.net

Wildcards are supported:

# Block all subdomains of doubleclick.net
*.doubleclick.net

Common Whitelist Categories

• Functional: Google APIs, Microsoft Windows Update
• Social: Social media login buttons
• Email: Email tracking pixels
• Local: Your local network domains

Regex Whitelisting

# Add regex in Whitelist section
# Regular expression:
^([a-z0-9]+\.)?example\.com$

# This matches:
# example.com
# www.example.com
# anything.example.com

Using Pi-hole as DHCP Server

Pi-hole can serve as your network's DHCP server, automatically assigning IP addresses and telling devices to use Pi-hole for DNS.

1. Go to Settings > DHCP
2. Enable DHCP server
3. Configure IP range (e.g., 192.168.1.100 - 192.168.1.200)
4. Set router/gateway IP
5. Set local domain name
6. Disable DHCP on your router

Static DHCP Reservations

Assign fixed IPs to specific devices:

1. Go to Settings > DHCP > Static DHCP Leases
2. Click "Add new static lease"
3. Enter MAC address and desired IP
4. Add hostname and comment

# Find MAC address of a device
# Tools > Network > Recent Devices
# Or check your router's device list

Query Log

The query log shows every DNS query Pi-hole processes:

# Access via web interface:
# Query Log

# Via command line:
pihole -t

Each entry shows:

• Time
• Client (which device)
• Query domain
• Query type (A, AAAA, etc.)
• Status (Allowed/Blocked)

Top Permitted/Blocked Domains

# Via command line:
pihole -t -d 100

# Shows top 100 queries
pihole -q domain.com

Long-Term Statistics

View historical data in:

• Dashboard: Total queries, blocked percentage, top domains
• Long-term data: Daily/weekly/monthly trends
• Client activity: Which devices use most bandwidth

Client Groups

Apply different rules to different devices:

1. Go to Groups > Clients
2. Add client by IP or MAC
3. Assign to a group

Use cases:

• Block ads on all devices except smart TVs
• Allow certain domains only for work devices
• Create "kid-safe" profile

Creating Groups

# Via web interface:
# Groups > Add new group

# Example groups:
# - "Kids" (strict blocking)
# - "Work" (allow work domains)
# - "Guests" (minimal blocking)

Group-Specific Blocking

Assign blocklists and whitelists to specific groups:

1. Go to Group Management > Blocklists
2. Add blocklist
3. Select which groups it applies to

API Overview

Pi-hole has a comprehensive API for automation:

# Get auth token from web interface:
# Settings > API > Show API token

# Base URL
http://pi.hole/admin/api.php

Common API Calls

# Get summary statistics
curl -s "http://pi.hole/admin/api.php?summary" | jq .

# Get top domains
curl -s "http://pi.hole/admin/api.php?topDomains" | jq .

# Get query log (limited)
curl -s "http://pi.hole/admin/api.php?getAllQueries" | jq .

# Enable/Disable
curl -s "http://pi.hole/admin/api.php?enable&auth=YOUR_TOKEN"
curl -s "http://pi.hole/admin/api.php?disable&auth=YOUR_TOKEN"

Adding Domains via API

# Add to whitelist via API
curl -s "http://pi.hole/admin/api.php?list=white&add=example.com&auth=YOUR_TOKEN"

# Add to blacklist via API  
curl -s "http://pi.hole/admin/api.php?list=black&add=ads.example.com&auth=YOUR_TOKEN"

Query Optimization

• Minimize blocklists: More lists = more processing
• Use regex carefully: Complex regex slows queries
• Monitor load: Top clients > 50% CPU means too many lists

FTL Engine

Pi-hole FTL (Faster-Than-Light) is the database engine:

# Check FTL status
sudo systemctl status pihole-FTL

# Restart FTL
sudo systemctl restart pihole-FTL

# Check database size
ls -lh /etc/pihole/pihole-FTL.db

Multiple Pi-holes

Run multiple Pi-holes for redundancy:

1. Install Pi-hole on two machines
2. Configure both as DNS on your router
3. Keep blocklists in sync

If one goes down, devices automatically use the other.

Syncing Blocklists

# Option 1: Use same blocklists
# Configure both Pi-holes with identical blocklists

# Option 2: Sync script
# Create script that updates both via API

# Option 3: Shared database
# (Advanced - not officially supported)

Load Balancing

Pi-hole doesn't natively load-balance, but your router can distribute DNS queries:

# Router DNS settings:
# Primary DNS: 192.168.1.10 (Pi-hole 1)
# Secondary DNS: 192.168.1.11 (Pi-hole 2)

# Most devices will use primary
# Fallback to secondary if primary unreachable

Regex Blocking

Block domains using patterns:

# In Local DNS > Domain Blocking > Regex
# Block all tracking subdomains:
.*\.analytics\..*

# Block all ads from a domain:
^ads?\..+

# Common regex patterns:
.*\.doubleclick\..*     # Any subdomain of doubleclick
.*-tracker\..*         # Any domain ending with -tracker
.*\.googlesyndication\..*

Local DNS Records

Override DNS for local domains:

1. Go to Local DNS > DNS Records
2. Add domain and IP

# Examples:
# homerouter.local > 192.168.1.1
# nas.local > 192.168.1.50
# myserver.local > 192.168.1.100

CNAME Blocking

Block domains that use CNAME redirects:

# Add to /etc/pihole/custom.list
0.0.0.0 ad.doubleclick.net
0.0.0.0 pagead2.googlesyndication.com
0.0.0.0 googleadservices.com

Conclusion

You've completed the Pi-hole mastery guide. You now know how to:

• Install and configure Pi-hole
• Configure upstream DNS providers
• Manage blocklists effectively
• Whitelist domains as needed
• Use Pi-hole as DHCP server
• Analyze query logs
• Implement client-specific filtering
• Automate with the API
• Configure high availability
• Use advanced blocking techniques

Remember:

• Balance blocking with functionality
• Update blocklists regularly
• Monitor your network
• Keep Pi-hole updated