145 lines
5.1 KiB
Markdown
145 lines
5.1 KiB
Markdown
# Pi-hole Stack
|
|
|
|
A network-wide ad blocker that acts as a DNS sinkhole, protecting your entire network from ads, trackers, and malicious domains. Enhanced with DNSCrypt-proxy for encrypted upstream DNS queries.
|
|
|
|
## Services Overview
|
|
|
|
- **server**: Pi-hole DNS server with web interface for ad blocking and network monitoring
|
|
- **dnscrypt-proxy**: Encrypted DNS proxy for secure upstream DNS resolution
|
|
|
|
## Key Features
|
|
|
|
- **Network-wide Ad Blocking**: Blocks ads for all devices on your network
|
|
- **DNS Sinkhole**: Prevents requests to known advertising and tracking domains
|
|
- **Encrypted DNS**: DNSCrypt-proxy provides encrypted communication with upstream DNS servers
|
|
- **Web Interface**: Comprehensive dashboard for monitoring and configuration
|
|
- **Query Logging**: Detailed logs of all DNS queries with filtering capabilities
|
|
- **Whitelist/Blacklist**: Custom domain allow/block lists
|
|
- **Multiple Blocklists**: Support for various community-maintained blocklists
|
|
- **Network Monitoring**: Real-time network activity and top blocked domains
|
|
- **DHCP Server**: Optional DHCP functionality for network management
|
|
|
|
## Architecture
|
|
|
|
### DNS Flow
|
|
1. Client DNS requests → Pi-hole (port 53)
|
|
2. Pi-hole checks blocklists → Blocks or allows
|
|
3. Allowed requests → DNSCrypt-proxy (port 5353)
|
|
4. DNSCrypt-proxy → Encrypted upstream DNS servers
|
|
5. Response flows back through the chain
|
|
|
|
### Security Features
|
|
- **Encrypted Upstream**: DNSCrypt-proxy encrypts DNS queries to upstream servers
|
|
- **Privacy Protection**: Prevents DNS queries from being monitored
|
|
- **Malware Protection**: Blocks known malicious domains
|
|
|
|
## Links & Documentation
|
|
|
|
### Pi-hole
|
|
- **Official Website**: https://pi-hole.net/
|
|
- **GitHub Repository**: https://github.com/pi-hole/pi-hole
|
|
- **Documentation**: https://docs.pi-hole.net/
|
|
- **Docker Hub**: https://hub.docker.com/r/pihole/pihole
|
|
- **Community**: https://discourse.pi-hole.net/
|
|
|
|
### DNSCrypt-proxy
|
|
- **GitHub Repository**: https://github.com/DNSCrypt/dnscrypt-proxy
|
|
- **Documentation**: https://github.com/DNSCrypt/dnscrypt-proxy/wiki
|
|
- **Docker Image**: https://hub.docker.com/r/klutchell/dnscrypt-proxy
|
|
|
|
### Blocklists
|
|
- **StevenBlack's List**: https://github.com/StevenBlack/hosts
|
|
- **AdguardTeam Lists**: https://github.com/AdguardTeam/AdguardFilters
|
|
- **Firebog Lists**: https://firebog.net/
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
Copy `stack.env` to `stack.env.real` and configure:
|
|
|
|
- `TZ`: Timezone for log timestamps
|
|
- `PIHOLE_WEBPASSWORD`: Password for Pi-hole web interface
|
|
- `PIHOLE_DNS_PORT`: DNS server port (default: 53)
|
|
- `PIHOLE_HTTP_PORT`: Web interface port (default: 80)
|
|
- `SERVICE_DATA_ROOT_PATH`: Base path for Pi-hole configuration data
|
|
|
|
### DNSCrypt Configuration
|
|
The DNSCrypt-proxy configuration file is located at:
|
|
`${SERVICE_DATA_ROOT_PATH}/dnscrypt/dnscrypt-proxy.toml`
|
|
|
|
### Network Access
|
|
- **DNS Service**: Port 53 (TCP/UDP) - Configure as DNS server for network devices
|
|
- **Web Interface**: Port 80 (or configured `PIHOLE_HTTP_PORT`)
|
|
- **Admin Panel**: Access via `http://your-server-ip:port/admin`
|
|
|
|
## Setup Instructions
|
|
|
|
### 1. Network Configuration
|
|
Configure your router or devices to use Pi-hole as the DNS server:
|
|
- **Router**: Set DNS server to Pi-hole IP address
|
|
- **Individual Devices**: Configure network settings to use Pi-hole IP
|
|
|
|
### 2. Initial Setup
|
|
1. Access web interface at `http://your-server-ip:port/admin`
|
|
2. Login with configured password
|
|
3. Configure blocklists under "Group Management" → "Adlists"
|
|
4. Update gravity database to apply blocklists
|
|
|
|
### 3. Testing
|
|
- Visit `http://doubleclick.net` - should be blocked
|
|
- Check Pi-hole dashboard for blocked queries
|
|
- Verify DNS resolution is working for legitimate domains
|
|
|
|
## Blocklist Management
|
|
|
|
### Default Lists
|
|
Pi-hole comes with several default blocklists. Popular additions include:
|
|
|
|
- **StevenBlack Unified**: Comprehensive hosts file
|
|
- **AdGuard Base Filter**: AdGuard's main blocklist
|
|
- **EasyList**: Popular browser extension list
|
|
- **Malware Domain List**: Security-focused blocking
|
|
|
|
### Custom Lists
|
|
Add custom blocklists via:
|
|
- Web interface: Group Management → Adlists
|
|
- Manual file editing: Add domains to local blocklist files
|
|
|
|
## Advanced Features
|
|
|
|
### Conditional Forwarding
|
|
Configure local domain resolution for internal networks.
|
|
|
|
### DHCP Replacement
|
|
Pi-hole can replace your router's DHCP server for better integration.
|
|
|
|
### API Access
|
|
REST API available for external integrations and monitoring.
|
|
|
|
## Performance Considerations
|
|
|
|
- **Memory Usage**: Minimal resource requirements (~100MB RAM)
|
|
- **Storage**: Logs and configuration require modest disk space
|
|
- **Network Impact**: Negligible latency impact on DNS resolution
|
|
- **Query Volume**: Handles thousands of queries per minute efficiently
|
|
|
|
## Monitoring & Maintenance
|
|
|
|
### Dashboard Metrics
|
|
- Total queries processed
|
|
- Percentage of blocked queries
|
|
- Top blocked domains
|
|
- Query volume over time
|
|
- Client activity statistics
|
|
|
|
### Log Management
|
|
- Query logs with filtering options
|
|
- Long-term trend analysis
|
|
- Privacy-focused logging controls
|
|
|
|
## Dependencies
|
|
|
|
- Network access for initial blocklist downloads
|
|
- DNSCrypt-proxy configuration file
|
|
- Persistent storage for Pi-hole configuration and logs
|