Wiki v1.0
Added a wiki
This commit is contained in:
kelinfoxy
@@ -0,0 +1,376 @@
|
||||
====== 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]].
|
||||
Reference in New Issue
Block a user