homelab-pihole-dns

name homelab-pihole-dns description Pi-hole installation, blocklist management, DNS-over-HTTPS setup, DHCP integration, local DNS records, and troubleshooting broken DNS resolution on a home network. Use when the task explicitly involves Pi-hole — installing it, managing blocklists, configuring DoH or DHCP, adding local DNS records, or diagnosing DNS resolution with Pi-hole in the path. metadata {"origin":"community"} Homelab Pi-hole DNS Pi-hole is a network-wide DNS ad blocker that runs on a Raspberry Pi or any Linux host. Every device on your network gets ad and malware domain blocking automatically — no browser extension needed. When to Use Installing Pi-hole on a Raspberry Pi or Linux host Configuring Pi-hole as the DNS server for a home network Adding or managing blocklists Setting up DNS-over-HTTPS (DoH) upstream resolvers Creating local DNS records (e.g. nas.home.lan , pi.home.lan ) Troubleshooting devices that lose internet access after Pi-hole is installed Running Pi-hole alongside or instead of DHCP How Pi-hole Works Normal flow (without Pi-hole): Device → requests ads.tracker.com → ISP DNS → real IP → ads load With Pi-hole: Device → requests ads.tracker.com → Pi-hole DNS → blocked (returns 0.0.0.0) → no ad All DNS queries go through Pi-hole first. Pi-hole checks against blocklists. Blocked domains return a null response — the ad/tracker never loads. Allowed domains get forwarded to your upstream resolver (Cloudflare, Google, etc.). Installation Docker (Recommended) Docker is the easiest way to install Pi-hole and makes updates and backups straightforward. # docker-compose.yml services: pihole: image: pihole/pihole:<pinned-release-tag> container_name: pihole ports: - "53:53/tcp" - "53:53/udp" - "80:80/tcp" # Web admin environment: TZ: "America/New_York" WEBPASSWORD: "${PIHOLE_WEBPASSWORD}" # set via .env file or secret PIHOLE_DNS_: "1.1.1.1;1.0.0.1" DNSMASQ_LISTENING: "all" volumes: - "./etc-pihole:/etc/pihole" - "./etc-dnsmasq.d:/etc/dnsmasq.d" restart: unless-stopped cap_add: - NET_ADMIN # only needed if Pi-hole will serve DHCP Replace <pinned-release-tag> with a current Pi-hole release tag before deploying. Avoid latest for long-lived DNS infrastructure so upgrades are deliberate and reviewable. Set PIHOLE_WEBPASSWORD in a .env file next to docker-compose.yml , chmod it to 600 , and keep it out of git — do not put the password directly in the compose file. Access web admin at: http://<pi-ip>/admin Bare-Metal Install (Raspberry Pi OS / Debian / Ubuntu) Pi-hole requires a static IP before installing. # Step 1: Assign a static IP (edit /etc/dhcpcd.conf on Pi OS) sudo nano /etc/dhcpcd.conf # Add at the bottom: interface eth0 static ip_address=192.168.3.2/24 static routers=192.168.3.1 static domain_name_servers=192.168.3.1 # Step 2: Download and inspect the installer before running it. # Prefer the package or installer path documented by Pi-hole for your OS/version. curl -sSL https://install.pi-hole.net -o pi-hole-install.sh less pi-hole-install.sh # review before proceeding # Step 3: Run bash pi-hole-install.sh # Follow the interactive installer: # 1. Select network interface (eth0 for wired — recommended) # 2. Select upstream DNS (Cloudflare or leave default — can change later) # 3. Confirm static IP # 4. Install the web admin interface (recommended) # 5. Note the admin password shown at the end Pointing Your Network at Pi-hole # Method 1: Change DNS in your router DHCP settings (recommended) Router admin UI → DHCP Settings → DNS Server Primary DNS: 192.168.3.2 (Pi-hole IP) Secondary DNS: leave blank for strict blocking, or use a second Pi-hole. A public fallback such as 1.1.1.1 improves availability during rollout but can bypass blocking because clients may query it. All devices get Pi-hole as DNS automatically on next DHCP renewal. Force renewal: reconnect Wi-Fi or run 'sudo dhclient -r && sudo dhclient' on Linux # Method 2: Per-device DNS (useful for testing before network-wide rollout) Windows: Control Panel → Network Adapter → IPv4 Properties → set DNS manually macOS: System Settings → Network → Details → DNS → set manually Linux: /etc/resolv.conf or NetworkManager # Method 3: Pi-hole as DHCP server (replaces router DHCP) Pi-hole admin → Settings → DHCP → Enable Disable DHCP on your router first — two DHCP servers on the same network cause conflicts Advantage: hostname resolution works automatically (devices register their names) Blocklist Management # Pi-hole admin → Adlists → Add new adlist # Recommended blocklists: https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts # default — 200k+ domains https://blocklistproject.github.io/Lists/malware.txt # malware domains https://blocklistproject.github.io/Lists/tracking.txt # tracking/telemetry # After adding a list: Tools → Update Gravity (downloads and compiles all blocklists) # If a site is blocked that should not be (false positive): Pi-hole admin → Whitelist → Add domain Example: api.my-legitimate-service.com # Check what is being blocked in real time: Dashboard → Query Log (live DNS query stream with block/allow status) DNS-over-HTTPS Upstream DNS-over-HTTPS encrypts your DNS queries so your ISP cannot see what sites you resolve. # Install cloudflared (Cloudflare's DoH proxy). # Prefer Cloudflare's package repository for automatic signed package verification. # If you download a binary directly, pin a release version and verify its checksum. CLOUDFLARED_VERSION= "<pinned-version>" curl -LO "https://github.com/cloudflare/cloudflared/releases/download/ ${CLOUDFLARED_VERSION} /cloudflared-linux-arm64" # Verify the checksum/signature from Cloudflare's release notes before installing. sudo mv cloudflared-linux-arm64 /usr/local/bin/cloudflared sudo chmod +x /usr/local/bin/cloudflared # Create cloudflared config sudo mkdir -p /etc/cloudflared sudo tee /etc/cloudflared/config.yml << EOF proxy-dns: true proxy-dns-port: 5053 proxy-dns-upstream: - https://1.1.1.1/dns-query - https://1.0.0.1/dns-query EOF # Create systemd service sudo cloudflared service install sudo systemctl start cloudflared sudo systemctl enable cloudflared # Now point Pi-hole at the local DoH proxy: # Pi-hole admin → Settings → DNS → Custom upstream DNS # Set to: 127.0.0.1#5053 # Uncheck all other upstream resolvers Local DNS Records Make your services reachable by name (e.g. nas.home.lan , grafana.home.lan ). Domain name note: .home.lan is widely used in homelabs and works in practice. The IETF-reserved suffix for local use is .home.arpa (RFC 8375) — use that to follow the standard. Avoid .local for Pi-hole DNS records as it conflicts with mDNS/Bonjour. # Pi-hole admin → Local DNS → DNS Records Domain IP nas.home.lan 192.168.30.10 pi.home.lan 192.168.30.2 grafana.home.lan 192.168.30.3 proxmox.home.lan 192.168.30.4 # From any device on your network: ping nas.home.lan → 192.168.30.10 http://grafana.home.lan → your Grafana dashboard # For subdomains, add a CNAME: Pi-hole admin → Local DNS → CNAME Records Domain: portainer.home.lan → Target: pi.home.lan Troubleshooting # Pi-hole blocking something it should not pihole -q example.com # Check if domain is blocked and which list pihole -w example.com # Whitelist immediately # DNS not resolving at all pihole status # Check if pihole-FTL is running dig @192.168.3.2 google.com # Test DNS directly against Pi-hole # Restart Pi-hole DNS pihole restartdns # Check query logs for a specific device pihole -t # Live tail of all queries # Or filter by client in the web admin Query Log # Pi-hole gravity update (refresh blocklists) pihole -g Anti-Patterns # BAD: Depending on one Pi-hole without a recovery path # If Pi-hole crashes or the Pi loses power, DNS can stop working # GOOD: Keep a documented router fallback for rollback during setup # BETTER: Run two Pi-hole instances for redundancy; avoid public fallback DNS for strict blocking # BAD: Installing Pi-hole without a static IP # If the Pi gets a new DHCP IP, all devices lose DNS # GOOD: Set static IP first, then install Pi-hole # BAD: Enabling Pi-hole DHCP without disabling the router's DHCP first # Two DHCP servers on the same network hand out conflicting IPs # GOOD: Disable router DHCP, then enable Pi-hole DHCP # BAD: Never updating gravity (blocklists) # New ad and malware domains accumulate — stale lists miss them # GOOD: Schedule weekly gravity update: pihole -g (or enable in Settings → API) Best Practices Give the Pi a static IP or DHCP reservation before installing Pi-hole Use Pi-hole as primary DNS; for redundancy, add a second Pi-hole instead of a public resolver if you need strict blocking Enable DoH (DNS-over-HTTPS) with cloudflared for encrypted upstream queries Set home.lan as your local domain and create DNS records for all your services Review the Query Log occasionally — blocked queries show you what devices are doing Related Skills homelab-network-setup homelab-vlan-segmentation homelab-wireguard-vpn