Jul 31, 2024 3 min read

Pi-hole: Self-Hosting Made Simple

Pi-hole: Self-Hosting Made Simple
Table of Contents

Pi-hole is a self-hosted network-wide ad blocker that acts as a Domain Name System (DNS) sinkhole, effectively blocking unwanted ads and trackers at the network level. Ideal for developers, system administrators, and privacy enthusiasts, Pi-hole offers unparalleled customization, enhanced data control, and optimization for resource-constrained environments. This guide will walk you through deploying Pi-hole, configuring it for secure and efficient use, logging and debugging, backup and recovery, updating to new versions, and leveraging its advanced features.

Installing Pi-hole

πŸ“¦ Docker/Docker Compose Setup

Using Docker simplifies Pi-hole deployment, ensuring portability and consistent performance. Below is a docker-compose.yml file tailored for Pi-hole:


version: "3"

services:

pihole:

image: pihole/pihole:latest

container_name: pihole

environment:

TZ: 'America/New_York' # Adjust your timezone

WEBPASSWORD: 'your_secure_password' # Protect the web interface

volumes:

- './etc-pihole:/etc/pihole'

- './etc-dnsmasq.d:/etc/dnsmasq.d'

ports:

- "53:53/tcp"

- "53:53/udp"

- "80:80/tcp"

restart: unless-stopped

dns:

- 127.0.0.1

- 8.8.8.8

Save this file in a directory and run the following commands:


docker-compose up -d

This will download the Pi-hole image, create the necessary containers, and start your Pi-hole instance.

πŸš€ Manual Installation

For those who prefer a direct setup on a Linux server, follow these steps:

  1. Update your system and install dependencies:

sudo apt update && sudo apt upgrade -y

sudo apt install -y curl

  1. Run the official Pi-hole installer:

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

  1. Follow the on-screen prompts to configure DNS, the admin password, and other settings.

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

To serve Pi-hole behind an Nginx reverse proxy, create a new server block file:


sudo nano /etc/nginx/sites-available/pihole

Add the following configuration:


server {

listen 80;

server_name pi-hole.example.com;

location / {

proxy_pass http://127.0.0.1:80;

proxy_set_header Host $host;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

}

}

Enable the configuration and restart Nginx:


sudo ln -s /etc/nginx/sites-available/pihole /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl reload nginx

πŸ”’ SSL/TLS Setup

Secure your Pi-hole instance with Let's Encrypt:

  1. Install Certbot:

sudo apt install -y certbot python3-certbot-nginx

  1. Request and apply a certificate:

sudo certbot --nginx -d pi-hole.example.com

  1. Restart Nginx to apply changes:

sudo systemctl reload nginx

πŸ› οΈ Testing and Reloading Nginx

Verify your configuration:


sudo nginx -t

sudo systemctl reload nginx

Ensure connections to https://pi-hole.example.com route correctly.

Logging and Debugging Pi-hole

πŸ—ƒοΈ Enabling Debug Logs

To enable debug-level logging, modify the Pi-hole configuration file:


sudo nano /etc/pihole/pihole-FTL.conf

Add or edit the following line:


DEBUG_ALL=true

Restart Pi-hole for the changes to take effect:


sudo systemctl restart pihole-FTL

πŸ“„ Viewing Logs

Access Pi-hole logs via the terminal:


sudo tail -f /var/log/pihole.log

For Docker users:


docker logs pihole

πŸ› οΈ Troubleshooting Common Issues

Check for specific errors in the logs:


grep "error" /var/log/pihole.log

Resolve common DNS or ad-blocking issues by analyzing log entries.

πŸ“€ Exporting Logs

Send logs to an external system using tools like rsyslog or Filebeat:


sudo apt install -y rsyslog

sudo nano /etc/rsyslog.conf

Add a rule to forward logs to a remote server.

Backup and Restore

πŸ—‚οΈ File-Based Backups

Backup Pi-hole configuration files:


tar -czvf pihole-backup.tar.gz /etc/pihole /etc/dnsmasq.d

Restore files:


tar -xzvf pihole-backup.tar.gz -C /

πŸ”„ Database Backups

Export Pi-hole’s database (e.g., gravity.db):


sqlite3 /etc/pihole/gravity.db .dump > gravity-backup.sql

Restore from the backup:


sqlite3 /etc/pihole/gravity.db < gravity-backup.sql

πŸ“… Automated Backup Scripts

Set up a cron job for periodic backups:


crontab -e

Add this line:


0 2 * * * tar -czvf /home/user/pihole-backup-$(date +\%F).tar.gz /etc/pihole /etc/dnsmasq.d

Updating and Upgrading Pi-hole

⬆️ Updating Docker Images

Pull the latest Pi-hole image:


docker pull pihole/pihole:latest

Recreate the container:


docker-compose down

docker-compose up -d

πŸ› οΈ Manual Updates

Update Pi-hole directly on a server:


pihole -up

πŸ” Checking for Updates

Check for the latest available version:


pihole -v

Leveraging Pi-hole’s Unique Features

πŸ”§ Enabling APIs

Activate Pi-hole’s API and retrieve statistics using curl:


curl -X GET "http://pi-hole.example.com/admin/api.php?status"

Or, integrate programmatically using Python:


import requests

response = requests.get("http://pi-hole.example.com/admin/api.php?status")

print(response.json())

🌟 Advanced Configurations

Add custom blocklists:


pihole -a -g

pihole -b domain.com

Integrate third-party DNS resolvers for enhanced privacy.

Wrapping Up

This guide has covered everything you need to deploy, configure, and manage Pi-hole, from installation to advanced features. By following these steps, you can harness the full power of Pi-hole to block unwanted content, improve privacy, and maintain complete control over your network. Get started today and enjoy an ad-free digital experience!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.