Skip to content

pihole

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

pihole

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
.env.example
.env.example
 
 
README.md
README.md
 
 
docker-compose.yml
docker-compose.yml
 
 

README.md

pihole

DNS sinkhole for network-wide ad blocking. Serves as the primary DNS resolver for the network.

Design Decisions

Why Host Network Mode?

Pi-hole needs to bind to port 53 (DNS) on the host. With bridge networking, port 53 conflicts with systemd-resolved on many Linux distributions. Host mode avoids this and simplifies DNS configuration.

Why Not Bind to Specific IP?

Host mode with DNSMASQ_LISTENING=all allows Pi-hole to respond on all interfaces. This is simpler than managing interface-specific bindings and works across network changes.

Conditional Forwarding

REV_SERVER settings enable reverse DNS lookups for local devices. Pi-hole forwards PTR queries to the router (OPNsense) which knows device hostnames from DHCP leases.

Configuration

Variable Purpose
PIHOLE_PASSWORD Web UI password
PIHOLE_IP Host IP for FTL binding
PIHOLE_DNS_ Upstream DNS servers
WEB_PORT Web UI port (8053 to avoid conflicts)
REV_SERVER_TARGET Router IP for reverse DNS
LAN_CIDR Local network range

Ports

Port Protocol Purpose
53 TCP/UDP DNS
8053 HTTP Web UI (configurable)

Capabilities

Pi-hole requires elevated capabilities:

Capability Why
NET_ADMIN Manage network interfaces
SYS_TIME NTP synchronization for accurate query logging
SYS_NICE Set process priorities

Resource Limits

Memory CPU Rationale
256M 0.25 DNS is lightweight; logs can grow

Increase memory if enabling extensive query logging.

Data Persistence

Path Contents
etc-pihole/ Configuration, blocklists, query database
etc-dnsmasq.d/ Custom dnsmasq configuration

Blocklist Management

Update blocklists via web UI or:

docker exec pihole pihole -g

Add custom blocklists in web UI: Group Management → Adlists

Network Integration

  1. Point DHCP server (router) to use Pi-hole as DNS
  2. Or configure individual devices to use Pi-hole IP

Ensure Pi-hole is highly available — DNS outage = network outage for name resolution.

Troubleshooting

DNS not resolving:

# Test from host
dig @127.0.0.1 google.com

# Check Pi-hole status
docker exec pihole pihole status

Port 53 conflict:

  • Disable systemd-resolved: sudo systemctl disable systemd-resolved
  • Or configure it to not listen on port 53

High memory usage:

  • Query logging fills the database; set retention in Settings → Privacy
  • Flush logs: docker exec pihole pihole flush

Upstream DNS

Default upstream is Cloudflare (1.1.1.1). Alternatives:

  • Quad9: 9.9.9.9
  • Google: 8.8.8.8
  • Local recursive resolver (Unbound)

Configure in web UI or via PIHOLE_DNS_ environment variable.