↓ Skip to main content
Zac Trolley
  1. Building Your Own Server/

Pi-hole - Network-Wide Ad Blocker

·820 words·4 mins

Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole, blocking ads, trackers, and malicious websites before they reach your devices. By running Pi-hole on your own server, you protect all devices on your network without needing to install apps on each one.

Pi-Hole

Why Pi-hole:

  • Network-Wide Protection: Blocks ads on all devices - phones, tablets, smart TVs, gaming consoles. Your network, your rules. No corporation tracks your browsing habits.
  • Privacy First: No data is sent to third parties; everything stays on your network. Stop advertisers from building profiles about your online activity
  • Fast Browsing: Blocks ads and trackers, making web pages load faster
  • Parental Controls: Block inappropriate content for your family

Resources
#

Installation Prep
#

Before installing Pi-hole, ensure you have the following ready:

Time to Complete
#

  • Total Time: ~20 minutes
    • 5 min: File system prep
    • 5 min: Docker setup
    • 5 min: Download Pi-hole image
    • 5 min: Router configuration
  • Difficulty: Beginner
  • Note: Pi-hole will become your network’s DNS server. Ensure you can access your router’s admin panel.

Installation
#

Step 1: File System Prep
#

We need to create the directories to keep the docker-compose file and Pi-hole configuration.

Create the Pi-hole directory

mkdir -p ~/docker/pihole/

Create the folders where your data will live:

mkdir -p ~/docker/pihole/{etc,libdnsmasq}

This creates the following structure:

/home/USER/docker/pihole/etc/          # Pi-hole configuration
/home/USER/docker/pihole/libdnsmasq/   # DNSMasq configuration

Step 2: Docker Setup
#

Make sure you are in your Pi-hole directory:

cd ~/docker/pihole

To double check you are in the right place, type pwd to see your current directory.

Create the docker-compose.yaml file:

sudo touch docker-compose.yaml

Use the nano program to edit the file:

sudo nano docker-compose.yaml

Step 3: docker-compose file
#

Copy the following text into the docker-compose file:

version: "3.8"
services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"
    environment:
      - TZ=America/Edmonton
      - WEBPASSWORD=your_secure_password
    volumes:
      - ./etc:/etc/pihole
      - ./libdnsmasq:/etc/dnsmasq.d
    restart: unless-stopped

Important: Replace your_secure_password with a strong password for the Pi-hole web interface.

Save and exit the file by pressing Ctrl+X and saying Y to save.

Step 4: Start Pi-hole
#

Now you can download and start Pi-hole:

sudo docker-compose pull
sudo docker-compose up -d

Once the pull is complete, verify the container is running:

docker ps

You should see pihole running.

Initial Setup and Configuration
#

Step 1: Access Pi-hole Web Interface
#

Open your browser and navigate to:

http://192.168.99.1/admin

This is the IP address of your Linux Mint machine where Pi-hole is installed.

Log in with the password you set in the docker-compose file.

Step 2: Change Router DNS Settings
#

To make Pi-hole your network’s DNS server, you need to change your router’s DNS settings:

  1. Access your router’s admin panel (usually http://192.168.1.1 or check your router’s documentation)
  2. Log in with your router credentials
  3. Find the DHCP/DNS Settings section
  4. Change Primary DNS to 192.168.99.1 (your Pi-hole server)
  5. Change Secondary DNS to a public DNS like 8.8.8.8 (Google) or 1.1.1.1 (Cloudflare)
  6. Save the settings

Alternative: Instead of changing router settings, you can configure individual devices to use Pi-hole as their DNS server.

Step 3: Test Pi-hole
#

  1. Open a web browser on any device connected to your network
  2. Visit a site with ads (e.g., youtube.com)
  3. You should see fewer ads than before
  4. Check the Pi-hole dashboard at http://192.168.99.1/admin to see blocked queries

Usage
#

Web Interface
#

The Pi-hole web interface (http://192.168.99.1/admin) provides:

  • Dashboard: Overview of blocked queries, top domains, recent activity
  • Query Log: View all DNS queries in real-time
  • Block Lists: Manage which domains are blocked
  • Tools: Flush DNS cache, test DNS resolution
  • Settings: Configure Pi-hole behavior

Common Tasks
#

View Blocked Queries:

  • Check the dashboard for real-time statistics
  • Use the Query Log to see detailed records

Add/Remove Domains:

  • Go to Block Lists to manage lists
  • Use White List to allow previously blocked domains
  • Use Black List to block additional domains

Flush DNS Cache:

  • Go to Tools > Flush DNS Cache

Maintenance
#

Updates
#

Update Pi-hole and Docker images:

cd ~/docker/pihole
sudo docker-compose pull
sudo docker-compose up -d

Block List Management
#

Regularly update your block lists:

  1. Go to Settings > Blocklists
  2. Click Update Gravity to refresh all lists

Troubleshooting
#

Pi-hole Not Blocking Ads
#

  1. Check that your devices are using Pi-hole as DNS
  2. Flush DNS cache on your devices
  3. Check the Query Log to see if queries are being made to Pi-hole

Web Interface Not Accessible
#

  1. Verify Pi-hole container is running: docker ps
  2. Check if port 80 is already in use: sudo netstat -tulpn | grep :80
  3. Restart Pi-hole: sudo docker-compose restart

DNS Resolution Issues
#

  1. Check your router’s DNS settings
  2. Verify Pi-hole is running: sudo docker ps
  3. Test DNS resolution: nslookup google.com 192.168.99.1