zsp/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-05-15 13:23:13 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: add homelab config skills (VLAN segmentation, Pi-hole DNS, WireGuard VPN) (#1838)

Browse Source 
* feat: add homelab config skills (VLAN, Pi-hole, WireGuard)

Adds three homelab configuration skills, extracted from the stale PR #1413
with the same safety treatment applied to the previously accepted batch:

- homelab-vlan-segmentation: IoT/guest/trusted/server VLAN design for UniFi,
  pfSense/OPNsense, and MikroTik. All firewall rules add isolation, not remove
  protections. Added change-window guidance and AP trunk port clarification.

- homelab-pihole-dns: Pi-hole install, blocklists, DNS-over-HTTPS, local DNS
  records, troubleshooting. Docker is now the lead install method; bare-metal
  uses inspect-first pattern before running the installer script.

- homelab-wireguard-vpn: WireGuard server, peer config, split tunnel, DDNS.
  Replaced broad iptables FORWARD ACCEPT with scoped directional rules
  (wg0→eth0 forward + established return only). Credentials moved to env
  files with explicit notes against inline secrets and version control.

Continues the contribution from PR #1413; the eight skills/agents from
that PR are already in main via #1729 and #1731.

* docs: harden homelab skill pack

---------

Co-authored-by: Affaan Mustafa <affaan@dcube.ai>
This commit is contained in:
Arsal Sajjad
2026-05-12 18:20:53 -07:00
committed by GitHub
parent 7f3dfde6d7
commit 71ed7c58d4
10 changed files with 903 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

274
skills/homelab-pihole-dns/SKILL.md Normal file
View File

@@ -0,0 +1,274 @@
---
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.
origin: community
---
# 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