Pi-hole – Network-Wide Ad Blocking DNS Server

What is Pi-hole?

Pi-hole is a network-level ad blocker that functions as a DNS sinkhole, protecting all devices on your network from unwanted content without requiring any client-side software. Originally designed to run on a Raspberry Pi (hence the name), Pi-hole has evolved to run on various Linux systems, Docker containers, and virtual machines, providing whole-network protection from a single installation.

Unlike browser-based ad blockers that only protect individual applications, Pi-hole operates at the network’s DNS level. When devices request DNS resolution for known advertising or tracking domains, Pi-hole returns a null address instead of the actual server IP, preventing connections before they start. This approach blocks ads in apps, smart TVs, IoT devices, and anywhere else advertising appears.

Beyond ad blocking, Pi-hole provides detailed analytics about network DNS queries, revealing which devices make what requests and how much malicious content is blocked. The web-based admin interface makes management straightforward, while the API enables integration with other systems and monitoring tools.

Key Features and Capabilities

Network-Wide Protection

A single Pi-hole installation protects every device on your network—computers, phones, tablets, smart TVs, gaming consoles, and IoT devices—without installing software on each device. Configure your router’s DHCP to use Pi-hole as DNS, and all connected devices benefit automatically.

Customizable Blocklists

Pi-hole blocks domains using community-maintained blocklists containing millions of known advertising, tracking, and malware domains. Add additional lists for specific needs, create personal blacklists for domains you want blocked, and whitelist domains that shouldn’t be filtered.

Query Logging and Analytics

Detailed logging shows every DNS query made by network devices. The dashboard displays real-time statistics, historical data, and breakdowns by client, domain, and query type. Identify which devices generate the most traffic and what domains they contact.

DHCP Server

Optional built-in DHCP server eliminates the need to configure your router, automatically assigning Pi-hole as the DNS server to all devices. DHCP reservations enable static IPs for specific devices while maintaining automatic configuration.

API and Integrations

REST API enables querying statistics and controlling Pi-hole programmatically. Integration with Home Assistant, Grafana, and other platforms provides enhanced monitoring and automation capabilities.

System Requirements

Hardware Requirements

Pi-hole is extremely lightweight, running comfortably on a Raspberry Pi Zero with 512 MB RAM. Recommended minimum: 2 GB storage, 512 MB RAM. Any Raspberry Pi model, old laptop, virtual machine, or Linux server works well.

Supported Platforms

Pi-hole runs on Raspberry Pi OS, Ubuntu, Debian, Fedora, CentOS, and other Linux distributions. Docker installations work on any platform supporting Docker. ARM and x86/x64 architectures both supported.

Installation Guide

Automated Installation

# One-line installation (recommended)
curl -sSL https://install.pi-hole.net | bash

# Or using wget
wget -O basic-install.sh https://install.pi-hole.net
sudo bash basic-install.sh

# Follow interactive prompts:
# 1. Select upstream DNS provider
# 2. Choose blocklists
# 3. Select protocols (IPv4/IPv6)
# 4. Confirm IP address
# 5. Install web interface
# 6. Configure logging
# 7. Set admin password

Docker Installation

# Docker run
docker run -d \
  --name pihole \
  -p 53:53/tcp -p 53:53/udp \
  -p 80:80 \
  -e TZ="America/New_York" \
  -e WEBPASSWORD="your_password" \
  -v pihole_data:/etc/pihole \
  -v dnsmasq_data:/etc/dnsmasq.d \
  --dns=127.0.0.1 \
  --dns=1.1.1.1 \
  --restart=unless-stopped \
  pihole/pihole:latest

# Docker Compose
version: "3"
services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80"
    environment:
      TZ: 'America/New_York'
      WEBPASSWORD: 'your_password'
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    cap_add:
      - NET_ADMIN
    restart: unless-stopped

Post-Installation

# Access web interface
http://pi.hole/admin
# or
http://YOUR_PI_IP/admin

# Set or change admin password
pihole -a -p

# View Pi-hole status
pihole status

# Update Pi-hole
pihole -up

# Update blocklists
pihole -g

Configuration

Network Setup Options

Option 1: Router DHCP (Recommended)
- Access router admin interface
- Find DHCP settings
- Set DNS server to Pi-hole IP
- All devices automatically use Pi-hole

Option 2: Pi-hole DHCP
- Disable router DHCP
- Enable Pi-hole DHCP in settings
- Pi-hole handles all addressing

Option 3: Manual Per-Device
- Configure DNS on individual devices
- Set primary DNS to Pi-hole IP
- Optional secondary DNS (bypasses Pi-hole)

Router DNS Examples:
Primary DNS: 192.168.1.100 (Pi-hole)
Secondary DNS: Leave blank or same

Upstream DNS Providers

Popular Options:
- Cloudflare: 1.1.1.1, 1.0.0.1
- Google: 8.8.8.8, 8.8.4.4
- Quad9: 9.9.9.9, 149.112.112.112
- OpenDNS: 208.67.222.222, 208.67.220.220

Privacy-Focused:
- DNS over HTTPS (DoH)
- DNS over TLS (DoT)
- Cloudflare DoH: https://cloudflare-dns.com/dns-query

Configure via:
Settings > DNS > Upstream DNS Servers

Command Line Interface

Essential Commands

# Status and information
pihole status            # Show Pi-hole status
pihole version           # Show version information
pihole -v               # Verbose version info

# Enable/Disable
pihole enable            # Enable blocking
pihole disable           # Disable blocking permanently
pihole disable 5m        # Disable for 5 minutes
pihole disable 1h        # Disable for 1 hour

# Blocklist management
pihole -g               # Update gravity (blocklists)
pihole -q domain.com    # Query blocklists for domain
pihole -q -adlist domain.com  # Show which list blocked

# Whitelist/Blacklist
pihole -w domain.com    # Add to whitelist
pihole -w -d domain.com # Remove from whitelist
pihole -b domain.com    # Add to blacklist
pihole -b -d domain.com # Remove from blacklist
pihole --wild domain.com # Wildcard blacklist

# Logging
pihole -t               # Tail the log (live)
pihole -c               # Show chronometer stats
pihole -l on           # Enable logging
pihole -l off          # Disable logging

# Flush logs
pihole flush            # Flush logs (keep stats)
pihole flush -l         # Flush logs (reset stats)

# Update
pihole -up              # Update Pi-hole
pihole updatechecker    # Check for updates

# Admin password
pihole -a -p            # Set new password
pihole -a -p ""         # Remove password

# Reconfigure
pihole reconfigure      # Run installer again

# Uninstall
pihole uninstall        # Remove Pi-hole

Web Interface

Dashboard Overview

Dashboard Sections:
- Total Queries: All DNS lookups
- Queries Blocked: Filtered requests
- Percent Blocked: Block rate
- Domains on Blocklists: Total blocked domains

Charts:
- Queries over last 24 hours
- Query types distribution
- Upstream DNS usage
- Top permitted/blocked domains
- Top clients

Query Log

Log Features:
- Real-time query display
- Filter by client, domain, type
- Quick whitelist/blacklist
- Query status (permitted, blocked, cached)
- Response time

Query Types:
A (IPv4), AAAA (IPv6), CNAME, MX, TXT, SRV, PTR, SOA

Blocklist Management

Adding Blocklists

Web Interface:
Group Management > Adlists
- Add URL to new blocklist
- Assign to groups
- Enable/disable lists

Popular Blocklists:
# StevenBlack Unified
https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts

# OISD Full
https://big.oisd.nl/

# Firebog Ticked Lists
https://v.firebog.net/hosts/lists.php?type=tick

# Energized Ultimate
https://block.energized.pro/ultimate/formats/hosts.txt

Update Lists:
pihole -g

Whitelist/Blacklist

Web Interface:
Domains > Add new domain

Domain Types:
- Exact: blocks/allows exact domain
- Regex: pattern matching
- Wildcard: all subdomains

Example Regex:
# Block all tracking subdomains
^(.+[-_.])?(tracking|analytics)[-_.]

# Block specific patterns
^ad[0-9]*\.

Wildcard Example:
# Block all of tracking.com
(\.|\.)tracking\.com$

Advanced Configuration

Custom DNS Records

# Local DNS Records
Settings > Local DNS > DNS Records
- Add hostname to IP mappings
- Create local domain names

Example:
server.local -> 192.168.1.50
nas.home -> 192.168.1.100

# CNAME Records
Local DNS > CNAME Records
myapp.local -> server.local

Conditional Forwarding

# Forward local domain to router/AD
Settings > DNS > Conditional Forwarding

Configuration:
Local network: 192.168.1.0/24
Router IP: 192.168.1.1
Local domain: home.lan

# Enables hostname resolution for local devices

Rate Limiting

# /etc/pihole/pihole-FTL.conf
RATE_LIMIT=1000/60

# 1000 queries per 60 seconds per client
# Prevents DNS amplification abuse

Monitoring and Statistics

API Usage

# Get summary stats
curl "http://pi.hole/admin/api.php?summary"

# Get top blocked domains
curl "http://pi.hole/admin/api.php?topItems"

# Get query types
curl "http://pi.hole/admin/api.php?getQueryTypes&auth=TOKEN"

# Enable/disable via API
curl "http://pi.hole/admin/api.php?disable=300&auth=TOKEN"
curl "http://pi.hole/admin/api.php?enable&auth=TOKEN"

Integration with Grafana

# Use InfluxDB + Telegraf
# Or Pi-hole Exporter for Prometheus

# Dashboard shows:
# - Queries over time
# - Block percentage trends
# - Client activity
# - Top domains

Troubleshooting

Common Issues

DNS Not Working:
1. Verify Pi-hole is running: pihole status
2. Check network config
3. Test direct DNS: dig @pihole-ip google.com
4. Verify upstream DNS connectivity

High CPU/Memory:
1. Reduce logging: pihole -l off
2. Flush logs: pihole flush
3. Reduce blocklist size

Legitimate Sites Blocked:
1. Check query log for domain
2. Whitelist domain: pihole -w domain.com
3. Review regex rules

Updates Failing:
1. Check internet connectivity
2. Verify DNS resolution
3. Manual update: pihole -up --repair

Best Practices

Security and Maintenance

Security:
1. Change default admin password
2. Use HTTPS if exposing externally
3. Keep Pi-hole updated
4. Monitor query logs for anomalies
5. Restrict admin access to local network

Maintenance:
1. Regular gravity updates (weekly)
2. Monitor storage usage
3. Review blocked/whitelisted domains
4. Backup configuration
5. Monitor Pi-hole health

Conclusion

Pi-hole provides powerful network-wide ad blocking with minimal resource requirements. Its DNS-based approach protects all devices automatically while providing valuable insights into network activity and blocked content.

Whether running on a dedicated Raspberry Pi or as a Docker container, Pi-hole delivers comprehensive protection against advertising, tracking, and malware domains across your entire network.