376 lines
11 KiB
Plaintext
376 lines
11 KiB
Plaintext
====== 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]]. |