Skip to main content
Agent skill

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 started

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?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/homelab-pihole-dns
# Save SKILL.md to ~/.claude/skills/homelab-pihole-dns/SKILL.md
  1. 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.
  2. 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.
  3. 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.

Starter prompt
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.