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.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- homelab-pihole-dns
- metadata
- { "origin": "community" }
- 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.
03 SKILL.md 正文
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.lanis 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.localfor 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.lanas 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
04 同仓库更多 Skills
system-lifecycle-designer
Universal architectural methodology for designing granular, atomic, and sub-atomic lifecycles and end-to-end workflows for single functionality integrations across any domain (daemons, batch jobs, request transactions, resource pools). Provides patterns for deterministic identity, pre-commit validation, differential reconciliation, sticky leasing, state machines, transactional persistence, and closed-loop feedback.
style-sampling
Make a new episode in a proven video style - Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime - on the person's topic. Use for "an episode of", "in the style of", "sample this style", 「用这个风格做一集」. One video to copy is reverse-any-video.
reverse-any-video
Rebuild any video file as an editable HyperFrames project - motion graphics, talking heads, live action or AI-generated footage - checked against the original frame by frame. Use to reverse, recreate, remake, replicate or copy a video, or 「复刻这个视频」「照着这个视频做一个」.
typescript-patterns
TypeScript patterns for strict, type-safe, maintainable code in modern TypeScript and JavaScript applications. Covers strict compiler configuration, type design, narrowing, discriminated unions, generics, async and error handling, module boundaries, dependency hygiene, and type-level testing. Use when writing or reviewing TypeScript or JavaScript code.
test-collaboration
Inventory and govern a project's test assets. Connect requirements, business rules, risks, bugs, and cross-boundary contracts to stable TEST-IDs and executable evidence in the repository's existing test registry or TESTS.md. Use for test inventory, test gap analysis, unit/integration/contract/E2E/smoke classification, bug-to-test regression protection, consumer/provider contract testing, test-necessity review, and pre-delivery evidence review.
story-lifecycle
Manage a file-based epic → story → sprint development loop without requiring an external project management tool. Creates and tracks epics, breaks them into user stories, assigns them to sprints, and drives implementation story by story. Use when starting a new feature initiative or when the team has no Jira/Linear/Taiga but needs structured delivery tracking.