Homelab Pihole Dns
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.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Homelab Pihole Dns when an AI agent needs a reusable SKILL.md workflow for this job: 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.
When not to use it
Skip Homelab Pihole Dns when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/homelab-pihole-dns # Save SKILL.md to ~/.claude/skills/homelab-pihole-dns/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/homelab-pihole-dns/SKILL.md. For a shared project, commit the folder at .claude/skills/homelab-pihole-dns/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Homelab Pihole Dns skill for this task: Installing Pi-hole on a Raspberry Pi or Linux host. Confirm any required inputs or files before making changes.
What supports this recommendation?
88/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 100/100
- Practical detail
- 100/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# 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.
```yaml # 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.
```bash # 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.
```bash # 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
```bash # 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
Intended uses
- 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
Implementation notes
- 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
- 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
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.