Homelab Pihole Dns
Stand up and tune Pi-hole for network-wide DNS filtering, local hostnames, DoH upstreams, and DHCP on a home lab.
Overview
Homelab-pihole-dns is an agent skill for the Operate phase that installs and manages Pi-hole DNS blocking, local records, DoH, and DHCP on a home network.
Install
npx skills add https://github.com/affaan-m/everything-claude-code --skill homelab-pihole-dnsWhat is this skill?
- Covers Docker-based Pi-hole install as the recommended deployment path
- Explains DNS interception flow: blocklists return 0.0.0.0 for ads and trackers before upstream forward
- DoH upstream configuration and local DNS records (e.g. nas.home.lan)
- Troubleshooting when clients lose internet after pointing DNS at Pi-hole
- DHCP alongside or instead of router DHCP for consistent Pi-hole assignment
Adoption & trust: 1.1k installs on skills.sh; 210k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want network-wide ad and malware DNS blocking without per-device browser extensions, but Pi-hole setup, upstream DNS, and broken client DNS feel opaque.
Who is it for?
Indie developers or homelab operators who control their router or DHCP and want centralized DNS policy for every device.
Skip if: Managed corporate DNS you cannot change, pure SaaS hosting with no LAN, or teams needing enterprise zero-trust DNS instead of Pi-hole.
When should I use this skill?
Installing Pi-hole, managing blocklists, configuring DoH upstreams, local DNS records, DHCP integration, or troubleshooting DNS on a home network.
What do I get? / Deliverables
Pi-hole runs as your LAN DNS resolver with managed blocklists, optional DoH upstreams, local hostnames, and steps to restore connectivity when DNS misconfiguration breaks clients.
- docker-compose.yml or equivalent Pi-hole deployment
- Documented blocklist, upstream, and local DNS record configuration
Recommended Skills
Journey fit
Pi-hole runs as always-on infrastructure on your LAN, matching Operate when you maintain services devices depend on daily. Infra fits because the skill covers installation, blocklists, upstream DNS, DHCP integration, and recovery—not app feature code.
How it compares
Homelab DNS appliance guidance—not a cloud CDN, Kubernetes ingress, or application-level ad blocker skill.
Common Questions / FAQ
Who is homelab-pihole-dns for?
Solo builders and homelab users who run Linux or a Raspberry Pi and want Pi-hole as network-wide DNS with blocklists and local name resolution.
When should I use homelab-pihole-dns?
Use it in Operate infra work when installing Pi-hole, adding blocklists, enabling DoH, defining local DNS records, or fixing devices that stop reaching the internet after DNS changes.
Is homelab-pihole-dns safe to install?
Review the Security Audits panel on this Prism page; misconfigured DNS or DHCP can take down your whole network, so validate changes on one client before rolling out network-wide.
SKILL.md
READMESKILL.md - Homelab Pihole Dns
# 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-devic