Pi-hole on Linux: Network-Wide Ad Blocking Complete Setup Guide

Network-wide ad blocking transforms your entire home network’s browsing experience by filtering advertisements, trackers, and malicious domains at the DNS level. Pi-hole, originally designed for Raspberry Pi but running on any Linux system, acts as a DNS sinkhole that blocks unwanted content before it reaches any device. This comprehensive guide walks you through installing and configuring Pi-hole on Linux for whole-network ad blocking.

How Pi-hole Works

Pi-hole intercepts DNS queries from devices on your network. When a device requests the IP address for an advertising domain, Pi-hole checks against blocklists and returns a null response instead of the actual address. The ad never loads because the browser can’t connect to a non-existent destination. This approach blocks ads in applications, smart TVs, and IoT devices where browser-based ad blockers can’t operate.

Unlike browser extensions that process each page’s content, DNS-level blocking requires minimal resources and adds negligible latency. A single Pi-hole instance can serve hundreds of devices simultaneously. The centralized approach means you configure blocking once rather than installing extensions on every device and browser.

System Requirements and Preparation

Pi-hole runs on minimal hardware—a Raspberry Pi Zero handles typical home networks comfortably. For larger deployments or virtual machines, allocate at least 512MB RAM and 2GB storage. Pi-hole supports Debian, Ubuntu, Fedora, and CentOS distributions.

Before installation, assign a static IP address to your Pi-hole server. DHCP-assigned addresses can change, breaking DNS resolution for your entire network. Configure static IP through your router’s DHCP reservation or directly in Linux’s network configuration.

# Ubuntu/Debian static IP via netplan (/etc/netplan/01-netcfg.yaml)
network:
  version: 2
  ethernets:
    eth0:
      addresses:
        - 192.168.1.100/24
      gateway4: 192.168.1.1
      nameservers:
        addresses: [8.8.8.8, 8.8.4.4]

Installing Pi-hole

Pi-hole provides an automated installer that handles dependencies and configuration. The installer works interactively or can accept preset answers for automated deployments.

Interactive Installation

Run the official installation script:

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

The installer guides you through configuration options: selecting upstream DNS providers (Google, Cloudflare, OpenDNS, or custom), choosing blocklists, enabling the web interface, and configuring logging preferences. Note the randomly generated admin password displayed at installation completion—you’ll need it for the web interface.

Docker Installation

For containerized deployments, use the official Docker image:

docker run -d \
    --name pihole \
    -p 53:53/tcp -p 53:53/udp \
    -p 80:80 \
    -e TZ="America/New_York" \
    -e WEBPASSWORD="your-secure-password" \
    -v "${PWD}/etc-pihole:/etc/pihole" \
    -v "${PWD}/etc-dnsmasq.d:/etc/dnsmasq.d" \
    --restart=unless-stopped \
    pihole/pihole:latest

Configuring Network Devices

After installation, configure devices to use Pi-hole as their DNS server. The most effective approach modifies your router’s DHCP settings to distribute Pi-hole’s IP as the DNS server to all connected devices.

Router Configuration

Access your router’s administration interface and locate DHCP or DNS settings. Change the primary DNS server to your Pi-hole’s IP address. Some routers require disabling their DNS proxy or enabling custom DNS options. After saving, devices receiving new DHCP leases will automatically use Pi-hole.

Manual Device Configuration

For devices requiring immediate configuration or static settings:

# Linux manual DNS configuration
sudo nano /etc/resolv.conf
nameserver 192.168.1.100  # Your Pi-hole IP

# Or use systemd-resolved
sudo nano /etc/systemd/resolved.conf
[Resolve]
DNS=192.168.1.100

Web Interface Administration

Access the Pi-hole dashboard at http://your-pihole-ip/admin. The interface displays real-time statistics including total queries, blocked percentages, and query sources. The dashboard visualizes blocking effectiveness and helps identify problematic domains.

Managing Blocklists

Navigate to Group Management → Adlists to add or remove blocklists. Pi-hole includes default lists blocking common advertising and tracking domains. Community-maintained lists extend coverage:

# Popular additional blocklists
https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
https://s3.amazonaws.com/lists.disconnect.me/simple_tracking.txt
https://s3.amazonaws.com/lists.disconnect.me/simple_ad.txt
https://raw.githubusercontent.com/crazy-max/WindowsSpyBlocker/master/data/hosts/spy.txt

After adding lists, update the gravity database:

pihole -g

Whitelist and Blacklist Management

Some legitimate services share domains with advertising networks. When blocking causes functionality issues, add domains to the whitelist. The Query Log helps identify blocked domains affecting specific services.

# Command line whitelist management
pihole -w example.com
pihole -w --list  # Show whitelist

# Blacklist specific domains
pihole -b annoying-tracker.com

Advanced Configuration

DNS Over HTTPS (DoH) with Cloudflared

Encrypt DNS queries between Pi-hole and upstream resolvers using cloudflared:

# Install cloudflared
wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

# Configure as DNS proxy
sudo nano /etc/cloudflared/config.yml

proxy-dns: true
proxy-dns-port: 5053
proxy-dns-upstream:
  - https://1.1.1.1/dns-query
  - https://1.0.0.1/dns-query

# Start service
sudo systemctl enable cloudflared
sudo systemctl start cloudflared

Configure Pi-hole to use cloudflared as upstream DNS by setting custom DNS to 127.0.0.1#5053 in the web interface.

Local DNS Records

Pi-hole can resolve local hostnames, eliminating the need to remember IP addresses for network devices:

# Add local DNS entries via web interface or command line
echo "192.168.1.50 nas.local" | sudo tee -a /etc/pihole/custom.list
echo "192.168.1.51 printer.local" | sudo tee -a /etc/pihole/custom.list

pihole restartdns

DHCP Server

Pi-hole includes an optional DHCP server, useful when router DHCP doesn’t allow custom DNS configuration. Enable in Settings → DHCP, specifying the IP range and gateway. Disable your router’s DHCP to prevent conflicts.

Monitoring and Maintenance

Regular maintenance ensures optimal Pi-hole performance. Update blocklists weekly and the Pi-hole software monthly:

# Update Pi-hole
pihole -up

# Update blocklists
pihole -g

# Check status
pihole status

# View real-time log
pihole -t

# Flush logs (privacy)
pihole flush

Troubleshooting Common Issues

When websites break after enabling Pi-hole, check the Query Log for blocked domains. Temporarily disable blocking with “pihole disable” to confirm Pi-hole causes the issue. Whitelist necessary domains rather than disabling blocking entirely.

If devices can’t resolve any domains, verify Pi-hole is running and accessible. Test upstream DNS connectivity:

# Test Pi-hole DNS
dig @192.168.1.100 google.com

# Check Pi-hole service
sudo systemctl status pihole-FTL

# Verify listening ports
sudo netstat -tulpn | grep 53

Conclusion

Pi-hole transforms network-wide ad blocking from device-by-device configuration into centralized management. The combination of DNS-level blocking, detailed logging, and simple administration makes Pi-hole an essential component for privacy-conscious home networks. Once configured, every device benefits automatically—including those where traditional ad blockers can’t operate.