mirror of
https://github.com/Dvorinka/Containr.git
synced 2026-06-04 20:42:58 +00:00
small fix, don't worry about it
This commit is contained in:
Tomas Dvorak
@@ -0,0 +1,378 @@
|
||||
# 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
|
||||
```bash
|
||||
# Create docker-compose.yml with the content below
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Docker Compose
|
||||
```yaml
|
||||
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**:
|
||||
```bash
|
||||
openssl rand -base64 16
|
||||
```
|
||||
|
||||
2. **Deploy**:
|
||||
```bash
|
||||
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`)
|
||||
```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`)
|
||||
```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`)
|
||||
```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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```yaml
|
||||
environment:
|
||||
- CONDITIONAL_FORWARDING=true
|
||||
- CONDITIONAL_FORWARDING_IP=192.168.1.1
|
||||
- CONDITIONAL_FORWARDING_DOMAIN=lan
|
||||
- CONDITIONAL_FORWARDING_REVERSE=192.168.1.0/24
|
||||
```
|
||||
|
||||
### DNSSEC
|
||||
```yaml
|
||||
environment:
|
||||
- DNSSEC=true
|
||||
```
|
||||
|
||||
### DNS over TLS
|
||||
```yaml
|
||||
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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```yaml
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```yaml
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```yaml
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Add regex blocklist
|
||||
docker exec pihole pihole -b -adlist.regex "ads.*\.example\.com"
|
||||
```
|
||||
|
||||
### Per-Client Blocking
|
||||
```bash
|
||||
# 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
|
||||
```yaml
|
||||
# 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
|
||||
Reference in New Issue
Block a user