EZ-Homelab/config-templates/dokuwiki/data/pages/services/infrastructure/pihole.txt

====== Pi-hole ======

Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole, blocking advertisements and tracking domains at the network level. It provides DNS-based ad blocking, DHCP server capabilities, and comprehensive network statistics.

===== Overview =====

**Purpose:** Network-wide ad blocking and DNS
**URL:** http://pihole.yourdomain.duckdns.org (HTTP only)
**Authentication:** Authelia SSO protected
**Deployment:** Infrastructure stack
**Protocol:** DNS (port 53), DHCP (optional)

===== Key Features =====

**Ad Blocking:**
  * **DNS Sinkhole**: Blocks ad/tracking domains
  * **Network Wide**: Protects all devices on network
  * **Custom Lists**: Support for custom blocklists
  * **Whitelist/Blacklist**: Fine-grained control

**DNS Services:**
  * **Recursive DNS**: Full DNS resolution
  * **DNSSEC**: DNS security extensions
  * **Conditional Forwarding**: Local hostname resolution
  * **Rate Limiting**: Query rate limiting

**DHCP Server:**
  * **IP Address Assignment**: Dynamic IP allocation
  * **Static Leases**: Reserved IP addresses
  * **Network Configuration**: Gateway and DNS settings
  * **Client Management**: Device tracking

===== Configuration =====

**Container Configuration:**
```yaml
services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    restart: unless-stopped
    environment:
      - TZ=${TZ}
      - WEBPASSWORD=${PIHOLE_PASSWORD}
      - PIHOLE_DNS_=1.1.1.1;1.0.0.1;8.8.8.8;8.8.4.4
      - DHCP_ACTIVE=false  # Set to true to enable DHCP
      - DHCP_START=192.168.1.100
      - DHCP_END=192.168.1.200
      - DHCP_ROUTER=192.168.1.1
      - DHCP_LEASETIME=24
    volumes:
      - ./pihole/etc-pihole:/etc/pihole
      - ./pihole/etc-dnsmasq.d:/etc/dnsmasq.d
    ports:
      - 53:53/tcp
      - 53:53/udp
      - 8082:80/tcp  # Web interface
    networks:
      - traefik-network
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 256M
        reservations:
          cpus: '0.1'
          memory: 64M
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.pihole.rule=Host(`pihole.${DOMAIN}`)"
      - "traefik.http.routers.pihole.entrypoints=websecure"
      - "traefik.http.routers.pihole.tls.certresolver=letsencrypt"
      - "traefik.http.routers.pihole.middlewares=authelia@docker"
      - "traefik.http.services.pihole.loadbalancer.server.port=80"
      - "x-dockge.url=http://pihole.${DOMAIN}"
    dns:
      - 127.0.0.1
      - 1.1.1.1
```

**Environment Variables:**
```bash
# Required
PIHOLE_PASSWORD=your-secure-password

# Optional DNS servers (comma-separated)
PIHOLE_DNS_=1.1.1.1;1.0.0.1;8.8.8.8;8.8.4.4

# DHCP Configuration (if enabled)
DHCP_ACTIVE=true
DHCP_START=192.168.1.100
DHCP_END=192.168.1.200
DHCP_ROUTER=192.168.1.1
DHCP_LEASETIME=24
```

===== DNS Configuration =====

**Upstream DNS Servers:**
  * **Cloudflare**: 1.1.1.1, 1.0.0.1 (default)
  * **Google**: 8.8.8.8, 8.8.4.4
  * **Quad9**: 9.9.9.9, 149.112.112.112
  * **OpenDNS**: 208.67.222.222, 208.67.220.220

**DNS Settings:**
```bash
# In Pi-hole admin interface
# Settings > DNS
# Enable DNSSEC for enhanced security
# Configure conditional forwarding for local network
```

**Client Configuration:**
  * **Router DNS**: Set router to use Pi-hole IP
  * **Device DNS**: Configure individual devices
  * **DHCP**: Enable DHCP server in Pi-hole
  * **IPv6**: Configure IPv6 DNS if needed

===== Ad Blocking Setup =====

**Blocklists:**
  * **Default Lists**: Pre-configured ad/tracking lists
  * **Custom Lists**: Add your own blocklists
  * **Gravity Update**: Regular list updates
  * **Regex Filtering**: Advanced pattern matching

**Whitelist/Blacklist:**
  * **Whitelist**: Allow specific domains
  * **Blacklist**: Block additional domains
  * **Regex**: Pattern-based filtering
  * **Client Groups**: Per-device rules

**Group Management:**
```bash
# Create client groups for different policies
# Assign devices to groups
# Apply different filtering rules per group
```

===== DHCP Server Configuration =====

**DHCP Setup:**
```yaml
environment:
  - DHCP_ACTIVE=true
  - DHCP_START=192.168.1.100
  - DHCP_END=192.168.1.200
  - DHCP_ROUTER=192.168.1.1
  - DHCP_LEASETIME=24
```

**Static Leases:**
  * **MAC Address**: Device hardware address
  * **IP Address**: Reserved static IP
  * **Hostname**: Device name
  * **Description**: Device description

**DHCP Options:**
  * **Domain Name**: Local domain suffix
  * **NTP Servers**: Time synchronization
  * **PXE Boot**: Network boot options
  * **Vendor Options**: Device-specific options

===== Monitoring & Statistics =====

**Dashboard Overview:**
  * **Total Queries**: DNS query volume
  * **Blocked Domains**: Ad blocking statistics
  * **Top Clients**: Most active devices
  * **Top Domains**: Frequently queried domains

**Query Log:**
  * **Real-time Monitoring**: Live query feed
  * **Filtering**: Search and filter queries
  * **Blocking Status**: See what's blocked/allowed
  * **Client Tracking**: Per-device statistics

**Long-term Statistics:**
  * **Historical Data**: Query trends over time
  * **Blocking Efficiency**: Ad blocking performance
  * **Client Usage**: Device activity patterns
  * **Domain Analysis**: Popular domain tracking

===== Security Features =====

**Access Control:**
  * **Web Interface**: Password protected
  * **Authelia Integration**: SSO authentication
  * **IP Restrictions**: Limit admin access
  * **Session Management**: Secure login sessions

**DNS Security:**
  * **DNSSEC**: Domain signature validation
  * **Query Logging**: Audit trail of requests
  * **Rate Limiting**: Prevent DNS amplification
  * **Cache Poisoning**: Protection against attacks

**Network Security:**
  * **Firewall Integration**: UFW/iptables rules
  * **Port Protection**: Restrict unnecessary ports
  * **Traffic Monitoring**: Network traffic analysis
  * **Intrusion Detection**: Suspicious activity alerts

===== Performance Optimization =====

**DNS Performance:**
```yaml
# Optimize DNS settings
# Settings > DNS > Interface Settings
# Enable cache optimization
# Configure upstream server timeout
```

**Resource Limits:**
```yaml
deploy:
  resources:
    limits:
      cpus: '0.5'
      memory: 256M
    reservations:
      cpus: '0.1'
      memory: 64M
```

**Caching:**
  * **DNS Cache**: Local query caching
  * **Blocklist Cache**: Efficient blocklist lookups
  * **Negative Cache**: Failed query caching
  * **TTL Management**: Cache expiration handling

===== Troubleshooting =====

**DNS Resolution Issues:**
```bash
# Check DNS resolution
nslookup google.com 127.0.0.1

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

# Check upstream connectivity
dig @8.8.8.8 google.com
```

**Ad Blocking Problems:**
  * **Test Blocking**: Visit ad-heavy sites
  * **Check Lists**: Verify blocklists are updating
  * **Whitelist Issues**: Check whitelist configuration
  * **Client Bypass**: Some apps bypass DNS

**DHCP Issues:**
  * **IP Conflicts**: Check for IP address conflicts
  * **Lease Problems**: Clear DHCP leases
  * **Router Settings**: Verify router DHCP disabled
  * **Network Issues**: Check network connectivity

**Web Interface Problems:**
  * **Login Issues**: Reset admin password
  * **SSL Problems**: Check certificate validity
  * **Authelia**: Verify SSO configuration
  * **Browser Cache**: Clear browser cache

**Troubleshooting Steps:**
  1. **Check logs**: `docker logs pihole`
  2. **Test DNS**: Verify DNS resolution works
  3. **Check configuration**: Validate environment variables
  4. **Network connectivity**: Test upstream DNS
  5. **Restart service**: `docker restart pihole`

===== Advanced Configuration =====

**Custom DNS Records:**
```bash
# Add local DNS records
# Settings > Local DNS > DNS Records
# Add A, AAAA, CNAME, PTR records
```

**Conditional Forwarding:**
```bash
# Forward local queries to router
# Settings > DNS > Advanced Settings
# Enable conditional forwarding
# Set router IP and local domain
```

**Regex Blocking:**
```bash
# Advanced blocking patterns
# Settings > DNS > Group Management
# Create regex filters for complex patterns
```

**API Access:**
```bash
# Enable API for external tools
# Settings > API > Show API token
# Use token for programmatic access
```

===== Integration with Other Services =====

**Router Integration:**
  * **DNS Settings**: Configure router to use Pi-hole
  * **DHCP Disable**: Disable router DHCP if using Pi-hole
  * **Port Forwarding**: Forward port 53 to Pi-hole
  * **Static IP**: Give Pi-hole static IP address

**Monitoring Integration:**
  * **Prometheus**: Export metrics for monitoring
  * **Grafana**: Create dashboards for Pi-hole stats
  * **Uptime Kuma**: Monitor Pi-hole availability
  * **Alerting**: Set up alerts for service issues

**Backup Integration:**
  * **Configuration Backup**: Backup Pi-hole settings
  * **Blocklist Backup**: Save custom lists
  * **DHCP Backup**: Backup DHCP leases
  * **Automated Backups**: Schedule regular backups

===== Best Practices =====

**DNS Configuration:**
  * **Multiple Upstream**: Use multiple DNS servers
  * **DNSSEC**: Enable DNS security
  * **Conditional Forwarding**: Enable for local network
  * **Rate Limiting**: Prevent abuse

**Ad Blocking:**
  * **Regular Updates**: Keep blocklists current
  * **Custom Lists**: Add domain-specific blocks
  * **Whitelist Carefully**: Only whitelist necessary sites
  * **Test Blocking**: Verify blocking effectiveness

**DHCP Management:**
  * **IP Planning**: Plan IP address ranges
  * **Static Leases**: Reserve IPs for servers
  * **Lease Time**: Appropriate lease durations
  * **Monitoring**: Track DHCP usage

**Security:**
  * **Strong Password**: Secure admin password
  * **Access Control**: Limit admin access
  * **Updates**: Keep Pi-hole updated
  * **Monitoring**: Monitor for security issues

**Maintenance:**
  * **Log Rotation**: Manage log file sizes
  * **Database Optimization**: Regular database maintenance
  * **Backup Routine**: Regular configuration backups
  * **Performance Monitoring**: Track resource usage

===== Common Use Cases =====

**Home Network:**
  * **Ad Blocking**: Block ads on all devices
  * **Parental Controls**: Block inappropriate content
  * **Device Management**: Track and manage devices
  * **Network Monitoring**: Monitor network activity

**Small Office:**
  * **Content Filtering**: Block productivity-draining sites
  * **Guest Network**: Separate guest DNS
  * **Device Control**: Manage corporate devices
  * **Reporting**: Generate usage reports

**Development:**
  * **Local DNS**: Resolve development domains
  * **Testing**: Test ad blocking effectiveness
  * **Network Simulation**: Simulate network conditions
  * **Debugging**: Debug DNS-related issues

Pi-hole provides essential network services with powerful ad blocking capabilities, serving as the DNS backbone of your homelab network.

**Next:** Learn about [[services:infrastructure:dozzle|Dozzle]] or explore [[architecture:networking|Network Architecture]].