pihole
Installation
SKILL.md
Identity
- Service unit:
pihole-FTL.service(the DNS resolver + stats engine) - Config dir:
/etc/pihole/(setupVars.conf, pihole-FTL.conf, custom.list, etc.) - Web interface: runs on port 80 (or configured port) —
http://<ip>/admin - Logs:
journalctl -u pihole-FTL,/var/log/pihole/pihole.log,/var/log/pihole/FTL.log - Data/lists:
/etc/pihole/gravity.db(SQLite, blocklist database) - Install: Official script:
curl -sSL https://install.pi-hole.net | bash(review before running)
Key Operations
| Goal | Command |
|---|---|
| Check service status | pihole status |
| Update blocklists | pihole -g (gravity update) |
| Enable/disable blocking | pihole enable / pihole disable |
| Disable for X seconds | pihole disable 300 |
| View query log | pihole -t (tail) or pihole -q domain.com (query) |
| Whitelist a domain | pihole -w domain.com |
| Blacklist a domain | pihole -b domain.com |
| Remove from whitelist | pihole -w -d domain.com |
| Update Pi-hole | pihole -up |
| Repair/reinstall | pihole -r |
| Check version | pihole version |
| Flush log | pihole flush |
| Tail FTL log | pihole -t |
| View statistics | pihole -c (chronometer in terminal) |
| Backup config | pihole -a -t (generates teleporter backup) |
Expected Ports
- 53/udp+tcp (DNS — primary function)
- 80/tcp (web interface, can be changed)
- 67/udp (DHCP server, if enabled)
- 4711/tcp (FTL API, localhost only by default)
Health Checks
pihole status→[✓] FTL is listening on port 53systemctl is-active pihole-FTL→activedig @127.0.0.1 google.com→ resolves (Pi-hole answering)dig @127.0.0.1 doubleclick.net→ returns 0.0.0.0 (blocked)
Common Failures
| Symptom | Likely cause | Check/Fix |
|---|---|---|
| DNS not resolving | FTL not running or port conflict | pihole status; ss -ulnp | grep :53 |
| Port 53 conflict | systemd-resolved using port 53 | Disable resolved stub listener; see Pain Points |
| Web interface 404 | lighttpd not running | systemctl status lighttpd |
| Gravity update fails | Network issue or blocklist URL down | Check internet connectivity; try pihole -g manually |
| Too many false positives | Aggressive blocklists | Whitelist domains; switch to less aggressive lists |
| Clients not using Pi-hole | DHCP/DNS not configured on router | Set Pi-hole as DNS server in router DHCP settings |
SERVFAIL for valid domains |
Upstream DNS issue or FTL crash | Check /var/log/pihole/FTL.log; check upstream DNS |
Pain Points
- systemd-resolved conflict on Ubuntu: Ubuntu 18.04+ runs
systemd-resolvedwith a stub listener on 127.0.0.53:53. This conflicts with Pi-hole on port 53. Fix: disable the stub listener in/etc/systemd/resolved.conf(DNSStubListener=no) and point/etc/resolv.confat Pi-hole. - Runs as root: Pi-hole's FTL service runs as root. Keep the host updated and network-isolated.
- Teleporter backup: Use
pihole -a -tto export config before OS upgrades or migration. Restores blocklists, settings, and custom DNS entries. - Custom DNS entries:
/etc/pihole/custom.listfor local DNS A/CNAME records. Format:IP hostname. Editable butpihole restartdnsneeded after changes. - unbound integration: Pi-hole → unbound is a common stack. Pi-hole handles blocking; unbound handles recursive resolution. Use
127.0.0.1#5335as Pi-hole's upstream when unbound listens on 5335. - Docker installs: Official Docker image (
pihole/pihole) requiresnetwork_mode: hostor careful port mapping for DNS to work on all network interfaces. - DHCP conflicts: Only enable Pi-hole's DHCP server if you can disable your router's DHCP server first. Running two DHCP servers causes chaos.
References
See references/ for:
configuration.md— setupVars.conf and pihole-FTL.conf referencedocs.md— official documentation links
Related skills