Pi-hole

What is Pi-hole?

Pi-hole is a network-level advertisement and internet tracker blocking application that acts as a DNS sinkhole. Instead of installing ad blockers on every device, Pi-hole blocks ads for your entire network from a single location.

By intercepting DNS requests, Pi-hole prevents ads, tracking domains, and malicious sites from loading on any device connected to your network – phones, tablets, smart TVs, IoT devices, and computers. Even devices that don’t support browser extensions benefit from Pi-hole’s protection.

Originally designed for the Raspberry Pi (hence the name), Pi-hole runs on virtually any Linux system, in Docker, or even in a VM. It’s lightweight, fast, and provides detailed statistics about your network’s DNS queries.

Minimum Requirements

• CPU: Any (Raspberry Pi Zero or better)
• RAM: 512 MB minimum
• Storage: 2 GB for OS + Pi-hole
• Network: Ethernet or WiFi connection
• OS: Linux, Docker, or Raspberry Pi OS
• Ports: 53 (DNS), 80 (Web interface)

Recommended Setup

• Hardware: Raspberry Pi 3/4 or dedicated server
• RAM: 1-2 GB for smooth operation
• Storage: 8+ GB for logs and updates
• Connection: Wired Ethernet for reliability
• Redundancy: Second Pi-hole for backup DNS
• Power: UPS to prevent DNS outages

1. Create Configuration Directories

Create directories to store Pi-hole configuration:

mkdir -p ~/pihole/{etc-pihole,etc-dnsmasq.d}
cd ~/pihole

2. Create Docker Compose File

Create docker-compose.yml with the following configuration:

version: '3'

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    restart: unless-stopped
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"
    environment:
      TZ: 'America/New_York'
      WEBPASSWORD: 'your_secure_password'
      FTLCONF_LOCAL_IPV4: '192.168.1.100'  # Your server's IP
      PIHOLE_DNS_: '1.1.1.1;1.0.0.1'  # Upstream DNS servers
      DNSSEC: 'true'
      DNSMASQ_LISTENING: 'all'
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    cap_add:
      - NET_ADMIN
    dns:
      - 127.0.0.1
      - 1.1.1.1

3. Start Pi-hole

Launch Pi-hole container:

docker-compose up -d

4. Access Web Interface

Open your browser and navigate to:

http://your-server-ip/admin

Login with the password you set in WEBPASSWORD environment variable.

5. Configure Your Network to Use Pi-hole

Option A: Router-Wide (Recommended)

1. Login to your router’s admin interface
2. Find DHCP settings
3. Set primary DNS to your Pi-hole IP address
4. Set secondary DNS to another Pi-hole or public DNS
5. Save and reboot router
6. All devices will automatically use Pi-hole

Option B: Per-Device Configuration

Manually set DNS on each device to your Pi-hole IP address.

6. Verify Pi-hole is Working

1. Visit http://pi.hole/admin (works if DNS configured correctly)
2. Check dashboard for query activity
3. Browse websites and watch blocked queries increase
4. Test with known ad-heavy websites

Quick Reference

Default Blocklists

Pi-hole comes with default blocklists, but you can add more:

• Go to Group Management → Adlists
• Click “Add a new adlist”
• Paste blocklist URL
• Save and update gravity

Popular Blocklists

• OISD: Comprehensive blocklist (recommended)
• 1Hosts: Aggressive ad/tracker blocking
• Hagezi: Multi-tier protection lists
• StevenBlack: Unified hosts lists
• Firebog: Curated collection of lists

Update Gravity

After adding blocklists, update gravity database:

docker exec pihole pihole -g

Whitelist & Blacklist

Whitelist (Allow domains):

1. Go to Whitelist section
2. Enter domain to allow (e.g., example.com)
3. Add comment explaining why
4. Save

Blacklist (Block domains):

1. Go to Blacklist section
2. Enter domain to block
3. Use wildcards: *.ads.example.com
4. Save

Regex Filtering

Advanced users can use regex patterns:

• Block patterns across multiple domains
• More precise targeting
• Group Management → Regex Filters

Dashboard Overview

The Pi-hole dashboard provides real-time insights:

• Total Queries: DNS requests processed
• Queries Blocked: Percentage of blocked requests
• Blocklist Size: Number of domains on blocklist
• Queries Over Time: Historical graph
• Query Types: A, AAAA, PTR, etc.
• Top Permitted Domains: Most accessed sites
• Top Blocked Domains: Most blocked trackers
• Top Clients: Devices making most queries

Query Log

• Real-time DNS query log
• See which device queried what domain
• One-click whitelist/blacklist from log
• Filter by client, domain, or status

Long-term Statistics

Pi-hole stores historical data for analysis:

• View trends over days, weeks, months
• Identify patterns in network usage
• Export data for external analysis
• Database grows over time (manage disk space)

Privacy Modes

• Show Everything: Full query logging
• Hide Domains: Anonymize domain names
• Hide Domains & Clients: Maximum privacy
• Anonymous: No logging at all

API Access

Access Pi-hole data programmatically:

• RESTful API for statistics
• Integrate with monitoring tools
• Create custom dashboards

Conditional Forwarding

Resolve local hostnames from your router:

• Enable in Settings → DNS
• Enter local network domain and router IP
• See device names instead of IP addresses

DNSSEC Validation

• Verify DNS responses are authentic
• Prevent DNS spoofing attacks
• Enable in Settings → DNS

Local DNS Records

Create custom DNS entries for local services:

• Local DNS → DNS Records
• Map domain names to IP addresses
• Example: server.home → 192.168.1.50

Group Management

• Create device groups (Kids, Adults, IoT)
• Apply different blocklists per group
• More restrictive filtering for kids’ devices
• Lighter filtering for trusted devices

Upstream DNS Servers

Configure where Pi-hole forwards queries:

• 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
• Custom: Your own DNS server

Custom Blocking Page

Customize the page users see when accessing blocked domains.

Common Issues

Website not loading:

Check query log to see if domain is blocked. Whitelist if needed. Clear browser cache.

No queries showing:

Verify DNS is set to Pi-hole IP. Check pihole container is running. Verify port 53 is accessible.

Slow DNS resolution:

Try different upstream DNS servers. Check network latency. Reduce blocklist size.

Port 53 already in use:

Stop systemd-resolved or other DNS service using port 53.

Maintenance Tasks

Update Pi-hole regularly:

docker-compose pull
docker-compose down
docker-compose up -d

Update gravity (blocklists):

docker exec pihole pihole -g

Backup Configuration

Backup Pi-hole settings from web interface:

• Settings → Teleporter
• Click “Backup” to download config
• Restore from backup file if needed