Menü
Pi-hole installation, blocklist management, DNS-over-HTTPS setup, DHCP integration, local DNS records, and troubleshooting broken DNS resolution on a home network.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Basierend auf der SOC-Berufsklassifikation
| 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. |
| metadata | {"origin":"community"} |
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.
nas.home.lan, pi.home.lan)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.).
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
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
# 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)
# 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 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
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
# 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
# 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)
home.lan as your local domain and create DNS records for all your servicesShare durable, inspectable context and handoffs between Claude, Codex, Hermes, Cursor, OpenCode, and other agents through the local ECC Memory Vault. Use when an agent must save work state, transfer context, resume another agent's task, or search shared project knowledge.
Share durable, inspectable context and handoffs between Claude, Codex, Hermes, Cursor, OpenCode, and other agents through the local ECC Memory Vault. Use when an agent must save work state, transfer context, resume another agent's task, or search shared project knowledge.
Share durable, inspectable context and handoffs between Claude, Codex, Hermes, Cursor, OpenCode, and other agents through the local ECC Memory Vault. Use when an agent must save work state, transfer context, resume another agent's task, or search shared project knowledge.
Use when multiple consumers and providers must evolve an API or event schema without field drift, integration surprises, or one side silently redefining the interface.
Instinct-based learning system that observes sessions via hooks, creates atomic instincts with confidence scoring, and evolves them into skills/commands/agents. v2.1 adds project-scoped instincts to prevent cross-project contamination.
Query live GPU inventory, submit an authenticated Itô fixed-rate RFQ, inspect RFQ or procurement status, and run explicitly gated node qualification through the separately installed canonical CLI. Use when a user asks to find H100/H200 capacity, request a fixed compute rate, check Itô compute status, or validate GPU nodes.