Containr/templates/pihole.md

Pi-hole DNS Ad Blocker Template

Overview

Pi-hole is a DNS sinkhole that protects your devices from unwanted content without installing any client-side software.

Quick Start

# Create docker-compose.yml with the content below
docker-compose up -d

Docker Compose

version: '3.8'

services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    restart: unless-stopped
    hostname: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"
      - "443:443/tcp"
    environment:
      - TZ=America/New_York
      - FTLCONF_webserver_api_password=your-secure-password
      - FTLCONF_dns_listeningMode=ALL
    volumes:
      - pihole-config:/etc/pihole
      - pihole-dnsmasq:/etc/dnsmasq.d
      - pihole-logs:/var/log
    cap_add:
      - NET_ADMIN
      - SYS_TIME
      - SYS_NICE
    networks:
      - pihole-network

volumes:
  pihole-config:
  pihole-dnsmasq:
  pihole-logs:

networks:
  pihole-network:
    driver: bridge

Environment Variables

• TZ: Timezone (find yours: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
• FTLCONF_webserver_api_password: Admin password for web interface
• FTLCONF_dns_listeningMode: DNS listening mode ('ALL' for bridge networks)

Setup Guide

1. Generate Secure Password:

   openssl rand -base64 16
   

2. Deploy:

   docker-compose up -d
   

3. Access: Open http://localhost/admin

4. Login: Use your WEBPASSWORD

5. Configure DNS Settings:

   • Set upstream DNS servers
   • Configure local network settings
   • Enable/disable features

Configuration Files

Custom DNS Records (pihole-dnsmasq.d/02-custom.conf)

# Custom DNS records
address=/homeserver.lan/192.168.1.100
address=/nas.lan/192.168.1.101
address=/camera.lan/192.168.1.102

# Local domain resolution
local=/lan/
domain=lan
expand-hosts

Custom Blocklists (pihole-dnsmasq.d/03-blocklist.conf)

# Additional blocklists
conf-file=/etc/pihole/custom.list

# Block specific domains
address=/ads.example.com/0.0.0.0
address=/tracker.example.com/0.0.0.0

DHCP Configuration (pihole-dnsmasq.d/04-dhcp.conf)

# DHCP settings (optional)
dhcp-range=192.168.1.50,192.168.1.150,12h
dhcp-option=option:router,192.168.1.1
dhcp-option=option:dns,192.168.1.10
dhcp-option=option:ntp,192.168.1.1

# Static leases
dhcp-host=aa:bb:cc:dd:ee:ff,192.168.1.100,server

Network Configuration

Router Setup

1. Disable DHCP on router (if using Pi-hole for DHCP)
2. Set DNS on router to Pi-hole IP (192.168.1.10)
3. Configure devices to use router DNS

Device Configuration

# Linux
echo "nameserver 192.168.1.10" | sudo tee /etc/resolv.conf

# Windows (PowerShell)
Set-DnsClientServerAddress -InterfaceAlias "Ethernet" -ServerAddresses "192.168.1.10"

# macOS
sudo networksetup -setdnsservers Wi-Fi 192.168.1.10

Blocklist Management

Default Blocklists

• Steven Black's blocklists
• Firebog blocklists
• Malware domains
• Ad-serving domains

Custom Blocklists

# Add custom blocklist
curl -s https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts | sudo tee /etc/pihole/custom.list

# Add specific domains
echo "ads.example.com" | sudo tee -a /etc/pihole/custom.list

Whitelisting

# Add domain to whitelist
docker exec pihole pihole -w example.com

# Remove from whitelist
docker exec pihole pihole -w -d example.com

Advanced Configuration

Conditional Forwarding

environment:
  - CONDITIONAL_FORWARDING=true
  - CONDITIONAL_FORWARDING_IP=192.168.1.1
  - CONDITIONAL_FORWARDING_DOMAIN=lan
  - CONDITIONAL_FORWARDING_REVERSE=192.168.1.0/24

DNSSEC

environment:
  - DNSSEC=true

DNS over TLS

environment:
  - PIHOLE_DNS_=1.1.1.1@853#cloudflare-dns.com;1.0.0.1@853#cloudflare-dns.com
  - DNS_FQDN_REQUIRED=true
  - DNSSEC=true

Monitoring and Statistics

Web Interface

• Dashboard: Overview of DNS queries
• Queries: Real-time query log
• Statistics: Top domains, clients, and queries
• Blocklists: Manage blocklists and whitelists

CLI Commands

# Check status
docker exec pihole pihole status

# View query log
docker exec pihole pihole -t

# Show top clients
docker exec pihole pihole -c

# Show top domains
docker exec pihole pihole -t -l

# Flush logs
docker exec pihole pihole -f

API Usage

# Get stats
curl -s http://localhost/admin/api.php?summary

# Get top items
curl -s http://localhost/admin/api.php?topItems

# Get recent queries
curl -s http://localhost/admin/api.php?recentBlocked

# Add to whitelist
curl -X POST -d "list=whitelist&add=example.com" \
  http://localhost/admin/api.php

# Add to blacklist
curl -X POST -d "list=blacklist&add=ads.example.com" \
  http://localhost/admin/api.php

Backup Strategy

# Backup Pi-hole configuration
docker run --rm -v pihole-config:/etc/pihole -v $(pwd):/backup alpine tar czf /backup/pihole-config-backup.tar.gz -C /etc/pihole .

# Backup gravity database
docker exec pihole cp /etc/pihole/gravity.db /tmp/gravity.db
docker cp pihole:/tmp/gravity.db ./gravity.db.backup

# Restore configuration
docker run --rm -v pihole-config:/etc/pihole -v $(pwd):/backup alpine tar xzf /backup/pihole-config-backup.tar.gz -C /etc/pihole

# Restart after restore
docker-compose restart pihole

Performance Optimization

# For better performance
environment:
  - DNSMASQ_CACHE_SIZE=10000
  - DNSMASQ_NEG_CACHE_TTL=3600
  - DNSMASQ_LOG_QUERIES=false

# Resource limits
deploy:
  resources:
    limits:
      memory: 512M
      cpus: '1.0'
    reservations:
      memory: 256M
      cpus: '0.5'

Security

Firewall Configuration

# Allow DNS (port 53)
sudo ufw allow 53/tcp
sudo ufw allow 53/udp

# Allow HTTP (port 80)
sudo ufw allow 80/tcp

# Allow from local network only
sudo ufw allow from 192.168.1.0/24 to any port 53
sudo ufw allow from 192.168.1.0/24 to any port 80

Access Control

# Restrict web access
environment:
  - WEBTHEME=default-darker
  - TEMPERATUREUNIT=c
  - WEBUIBOXEDLAYOUT=traditional

# Enable password protection
environment:
  - WEBPASSWORD=your-secure-password

Troubleshooting

• DNS not working: Check upstream DNS configuration
• Web interface inaccessible: Verify port and firewall settings
• Performance issues: Monitor resource usage
• Blocklist not updating: Check internet connectivity
• DHCP conflicts: Disable router DHCP if using Pi-hole DHCP

Maintenance

# Update blocklists
docker exec pihole pihole -g

# Restart DNS service
docker exec pihole pihole restartdns

# Check logs
docker-compose logs -f pihole

# Update image
docker-compose pull && docker-compose up -d

# Clean up old logs
docker exec pihole find /var/log/pihole -name "*.log.*" -mtime +30 -delete

Integration Examples

Home Assistant

# In Home Assistant configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.1.10/admin/api.php?summary
    name: Pi-hole Stats
    value_template: "{{ value_json.ads_blocked_today }}"

Grafana Dashboard

# Add to Prometheus scrape config
- job_name: 'pihole'
  static_configs:
    - targets: ['pihole:80']
  metrics_path: /admin/api.php?summaryRaw

Unifi Network

• Set Pi-hole as DNS server in Unifi Controller
• Configure DNS for all networks
• Monitor DNS queries through Unifi

Advanced Features

Regex Blocking

# Add regex blocklist
docker exec pihole pihole -b -adlist.regex "ads.*\.example\.com"

Per-Client Blocking

# Create group for specific client
docker exec pihole pihole -g add "family" "Family Group"

# Add client to group
docker exec pihole pihole -c add "192.168.1.50" "family"

# Assign blocklist to group
docker exec pihole pihole -g assign "family" "default"

Query Logging

# Enable detailed logging
environment:
  - DNSMASQ_LOG_QUERIES=true
  - DNSMASQ_LOG_CACHE=true

Privacy Considerations

• Local DNS: All queries processed locally
• No tracking: Pi-hole doesn't track users
• Configurable logging: Control what gets logged
• Blocklist choice: Choose your blocklists
• Data retention: Configure log retention policies