Pi-hole Setup Guide: Network-Wide Ad Blocking

Quick Answer: One-line install: curl -sSL https://install.pi-hole.net | bash. Then set your router's DNS to the Pi-hole IP. Every device on your network is now ad-free — no extensions, no per-device setup needed.

Need a VPS? Vultr (free credit), DigitalOcean ($200 free credit), or RackNerd (cheap annual deals).

What Is Pi-hole?

Pi-hole is a network-level ad blocker. It acts as a DNS server for your network — when a device tries to load an ad, Pi-hole blocks the DNS request so the ad never loads.

Without Pi-hole:
  Device → Router DNS → ad-server.com → Ads load ✗

With Pi-hole:
  Device → Pi-hole DNS → ad-server.com → BLOCKED ✓
  Device → Pi-hole DNS → real-website.com → Loads normally ✓

Why Pi-hole?

Method 1: Docker Install (Recommended)

Docker Compose

services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    restart: unless-stopped
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"
    environment:
      TZ: 'America/Chicago'
      WEBPASSWORD: 'your-password-here'
      FTLCONF_LOCAL_IPV4: '192.168.1.100'
    volumes:
      - pihole-data:/etc/pihole
      - dnsmasq-data:/etc/dnsmasq.d
    dns:
      - 127.0.0.1
      - 1.1.1.1

volumes:
  pihole-data:
  dnsmasq-data:

docker compose up -d

Access dashboard: http://192.168.1.100/admin

Method 2: Bare Metal Install

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

The installer wizard asks:

1. Upstream DNS: Choose Cloudflare (1.1.1.1) or Google (8.8.8.8)
2. Blocklists: Accept defaults (you can add more later)
3. Web admin: Yes
4. Web server: Yes (installs lighttpd)
5. Log queries: Yes

After install:

# Set/reset your Pi-hole admin password
pihole setpassword your-new-password

Access dashboard: http://YOUR_PI_IP/admin

Configure Your Network to Use Pi-hole

Option A: Set Pi-hole as DNS on Router (Best)

1. Log into your router (usually 192.168.1.1)
2. Find DNS settings (under DHCP or WAN)
3. Set Primary DNS to your Pi-hole IP (e.g., 192.168.1.100)
4. Remove or set Secondary DNS to nothing (if you add a second DNS like 8.8.8.8, devices may bypass Pi-hole)
5. Save and reboot router

Now every device on your network automatically uses Pi-hole.

Option B: Set Per-Device

If you can't change router DNS, set Pi-hole DNS on individual devices:

Linux:

# Edit resolv.conf (temporary)
echo "nameserver 192.168.1.100" | sudo tee /etc/resolv.conf

# Or use Netplan (permanent)
# Set nameservers: addresses: [192.168.1.100] in your netplan config

Windows: Settings → Network → Ethernet → DNS → Manual → 192.168.1.100

macOS: System Settings → Network → Details → DNS → Add 192.168.1.100

iOS/Android: Wi-Fi settings → Your network → DNS → Manual → 192.168.1.100

Managing Pi-hole

Web Dashboard

The dashboard at http://pihole-ip/admin shows:

• Total queries today
• Queries blocked (percentage)
• Top blocked domains
• Top clients (devices)
• Real-time query log

Command Line

# Status
pihole status

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

# Update Pi-hole
pihole update

# Update gravity (blocklists)
pihole gravity update

# View logs
pihole log              # Tail the log (live)

# Query log
pihole query domain.com   # Check if a domain is blocked

# Flush logs
pihole flush

# Restart DNS
pihole restartdns

Blocklists

Pi-hole comes with a default blocklist. Add more for better coverage.

Add Blocklists (Web UI)

Adlists → Add new: paste the URL → Add → Update Gravity

Recommended Blocklists

Update Blocklists

# Update gravity (re-download all blocklists)
pihole gravity update

Whitelist and Blacklist

Whitelist (Allow a Domain)

# Whitelist a domain
pihole allow example.com

# Whitelist with regex (wildcard)
pihole --white-regex '(\.|^)example\.com$'

# Remove from whitelist
pihole allow -d example.com

Common domains to whitelist if things break:

• s.youtube.com — YouTube history
• clients4.google.com — Android connectivity check
• captive.apple.com — Apple captive portal
• msftconnecttest.com — Windows connectivity check

Blacklist (Block a Domain)

# Block a specific domain
pihole deny annoying-site.com

# Block with wildcard (and all subdomains)
pihole --wild annoying-site.com

# Remove from blacklist
pihole deny -d annoying-site.com

Unbound: Recursive DNS (Maximum Privacy)

By default, Pi-hole forwards queries to Cloudflare or Google. With Unbound, Pi-hole resolves DNS itself by talking directly to root DNS servers — no third-party sees your queries.

# Install Unbound
sudo apt install unbound -y

# Configure for Pi-hole
sudo nano /etc/unbound/unbound.conf.d/pi-hole.conf

server:
    verbosity: 0
    interface: 127.0.0.1
    port: 5335
    do-ip4: yes
    do-udp: yes
    do-tcp: yes
    do-ip6: no
    prefer-ip6: no
    harden-glue: yes
    harden-dnssec-stripped: yes
    use-caps-for-id: no
    edns-buffer-size: 1232
    prefetch: yes
    num-threads: 1
    so-rcvbuf: 1m
    private-address: 192.168.0.0/16
    private-address: 172.16.0.0/12
    private-address: 10.0.0.0/8

# Restart Unbound
sudo systemctl restart unbound

# Test
dig google.com @127.0.0.1 -p 5335

Then in Pi-hole: Settings → DNS → Custom upstream: 127.0.0.1#5335. Uncheck all other upstream DNS.

Queries flow: Device → Pi-hole → Unbound → Root DNS servers
No third party (Cloudflare/Google) sees your DNS queries

Pi-hole on a VPS (Cloud-Wide Ad Blocking)

Run Pi-hole on a VPS and use it as your DNS from anywhere:

1. Set up Pi-hole on your VPS using Docker
2. Restrict access — don't leave DNS open to the internet:

# Only allow your IPs
sudo ufw allow from YOUR_HOME_IP to any port 53
sudo ufw allow from YOUR_VPN_RANGE to any port 53

1. Use with your VPN (WireGuard):

Set DNS = YOUR_VPS_IP in your WireGuard client config. Now all VPN traffic uses Pi-hole for DNS.

Guide: WireGuard Setup

Troubleshooting

# Check if Pi-hole is running
pihole status

# Check DNS resolution
dig google.com @127.0.0.1

# Check which DNS is being used
nslookup google.com

# View real-time queries
pihole -t

# Check for port conflicts
ss -tlnp | grep :53
# systemd-resolved may conflict — disable it:
sudo systemctl disable --now systemd-resolved

Quick Reference

Related Guides

• How to Change DNS Server — DNS configuration
• DNS Explained — how DNS works
• Complete DNS Guide — deep DNS guide
• Raspberry Pi Setup — Pi-hole on a Raspberry Pi
• Docker Cheat Sheet — Docker basics
• WireGuard Setup — VPN + Pi-hole
• Complete Self-Hosting Guide — server setup
• Server Hardening Guide — secure your Pi-hole server

Related Tools

• DNS Toolbox — DNS lookup tool
• What's My IP — check your IP
• VPN Leak Test — verify DNS isn't leaking