Workflow·Cloud & DevOps

Homelab Pi-hole DNS

Pi-hole installation, blocklist management, DNS-over-HTTPS setup, DHCP integration, local DNS records, and troubleshooting broken DNS…

You say
Buy it · $49 Read it before you buy $49 Written by affaan-m · unverified publisher
Context cost
2.4k tokensestimated from the bundle, loaded when it triggers
Bundle
1 file · 9.6 kBtext throughout, nothing executable
Licence
MITpaid listing
Last change
no release on file
Servers it uses
Noneruns standalone

What it does

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.

Installed, it changes the agent in these ways.

What this skill changes about the agent is not written down here yet. The listing was collected from its source, and the description is in its own SKILL.md.

Workflow

Runs a procedure end to end.

cloud
Filed under

Cloud & DevOps

The skill itself

This is the whole product. A skill is instructions the model reads, so there is nothing behind the listing you cannot see first — the front matter loads with every session, and the body below it loads when the skill triggers.

SKILL.md9.6 kB · 276 lines
--- 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. 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. metadata: origin: community ---
8# Homelab Pi-hole DNS
9
10Pi-hole is a network-wide DNS ad blocker that runs on a Raspberry Pi or any Linux host.
11Every device on your network gets ad and malware domain blocking automatically — no browser
12extension needed.
13
14## When to Use
15
16- Installing Pi-hole on a Raspberry Pi or Linux host
17- Configuring Pi-hole as the DNS server for a home network
18- Adding or managing blocklists
19- Setting up DNS-over-HTTPS (DoH) upstream resolvers
20- Creating local DNS records (e.g. nas.home.lan, pi.home.lan)
21- Troubleshooting devices that lose internet access after Pi-hole is installed
22- Running Pi-hole alongside or instead of DHCP
23
24## How Pi-hole Works
25
26```
27Normal flow (without Pi-hole):
28 Device → requests ads.tracker.com → ISP DNS → real IP → ads load
29
30With Pi-hole:
31 Device → requests ads.tracker.com → Pi-hole DNS → blocked (returns 0.0.0.0) → no ad
32
33All DNS queries go through Pi-hole first.
34Pi-hole checks against blocklists.
35Blocked domains return a null response — the ad/tracker never loads.
36Allowed domains get forwarded to your upstream resolver (Cloudflare, Google, etc.).
37```
38
39## Installation
40
41### Docker (Recommended)
42
43Docker is the easiest way to install Pi-hole and makes updates and backups
44straightforward.
45
46```yaml
47# docker-compose.yml
48services:
49 pihole:
50 image: pihole/pihole:<pinned-release-tag>
51 container_name: pihole
52 ports:
53 - "53:53/tcp"
54 - "53:53/udp"
55 - "80:80/tcp" # Web admin
56 environment:
57 TZ: "America/New_York"
58 WEBPASSWORD: "${PIHOLE_WEBPASSWORD}" # set via .env file or secret
59 PIHOLE_DNS_: "1.1.1.1;1.0.0.1"
60 DNSMASQ_LISTENING: "all"
61 volumes:
62 - "./etc-pihole:/etc/pihole"
63 - "./etc-dnsmasq.d:/etc/dnsmasq.d"
64 restart: unless-stopped
65 cap_add:
66 - NET_ADMIN # only needed if Pi-hole will serve DHCP
67```
68
69Replace <pinned-release-tag> with a current Pi-hole release tag before deploying.
70Avoid latest for long-lived DNS infrastructure so upgrades are deliberate and
71reviewable.
72
73Set PIHOLE_WEBPASSWORD in a .env file next to docker-compose.yml, chmod it to
74600, and keep it out of git — do not put the password directly in the compose file.
75
76Access web admin at: http://<pi-ip>/admin
77
78### Bare-Metal Install (Raspberry Pi OS / Debian / Ubuntu)
79
80Pi-hole requires a static IP before installing.
81
82```bash
83# Step 1: Assign a static IP (edit /etc/dhcpcd.conf on Pi OS)
84sudo nano /etc/dhcpcd.conf
85# Add at the bottom:
86interface eth0
87static ip_address=192.168.3.2/24
88static routers=192.168.3.1
89static domain_name_servers=192.168.3.1
90
91# Step 2: Download and inspect the installer before running it.
92# Prefer the package or installer path documented by Pi-hole for your OS/version.
93curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
94less pi-hole-install.sh # review before proceeding
95
96# Step 3: Run
97bash pi-hole-install.sh
98
99# Follow the interactive installer:
100# 1. Select network interface (eth0 for wired — recommended)
101# 2. Select upstream DNS (Cloudflare or leave default — can change later)
102# 3. Confirm static IP
103# 4. Install the web admin interface (recommended)
104# 5. Note the admin password shown at the end
105```
106
107## Pointing Your Network at Pi-hole
108
109```
110# Method 1: Change DNS in your router DHCP settings (recommended)
111 Router admin UI → DHCP Settings → DNS Server
112 Primary DNS: 192.168.3.2 (Pi-hole IP)
113 Secondary DNS: leave blank for strict blocking, or use a second Pi-hole.
114 A public fallback such as 1.1.1.1 improves availability during
115 rollout but can bypass blocking because clients may query it.
116
117 All devices get Pi-hole as DNS automatically on next DHCP renewal.
118 Force renewal: reconnect Wi-Fi or run 'sudo dhclient -r && sudo dhclient' on Linux
119
120# Method 2: Per-device DNS (useful for testing before network-wide rollout)
121 Windows: Control Panel → Network Adapter → IPv4 Properties → set DNS manually
122 macOS: System Settings → Network → Details → DNS → set manually
123 Linux: /etc/resolv.conf or NetworkManager
124
125# Method 3: Pi-hole as DHCP server (replaces router DHCP)
126 Pi-hole admin → Settings → DHCP → Enable
127 Disable DHCP on your router first — two DHCP servers on the same network cause conflicts
128 Advantage: hostname resolution works automatically (devices register their names)
129```
130
131## Blocklist Management
132
133```
134# Pi-hole admin → Adlists → Add new adlist
135
136# Recommended blocklists:
137 https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
138 # default — 200k+ domains
139
140 https://blocklistproject.github.io/Lists/malware.txt
141 # malware domains
142
143 https://blocklistproject.github.io/Lists/tracking.txt
144 # tracking/telemetry
145
146# After adding a list:
147 Tools → Update Gravity (downloads and compiles all blocklists)
148
149# If a site is blocked that should not be (false positive):
150 Pi-hole admin → Whitelist → Add domain
151 Example: api.my-legitimate-service.com
152
153# Check what is being blocked in real time:
154 Dashboard → Query Log (live DNS query stream with block/allow status)
155```
156
157## DNS-over-HTTPS Upstream
158
159DNS-over-HTTPS encrypts your DNS queries so your ISP cannot see what sites you resolve.
160
161```bash
162# Install cloudflared (Cloudflare's DoH proxy).
163# Prefer Cloudflare's package repository for automatic signed package verification.
164# If you download a binary directly, pin a release version and verify its checksum.
165CLOUDFLARED_VERSION="<pinned-version>"
166curl -LO "https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-arm64"
167# Verify the checksum/signature from Cloudflare's release notes before installing.
168sudo mv cloudflared-linux-arm64 /usr/local/bin/cloudflared
169sudo chmod +x /usr/local/bin/cloudflared
170
171# Create cloudflared config
172sudo mkdir -p /etc/cloudflared
173sudo tee /etc/cloudflared/config.yml << EOF
174proxy-dns: true
175proxy-dns-port: 5053
176proxy-dns-upstream:
177 - https://1.1.1.1/dns-query
178 - https://1.0.0.1/dns-query
179EOF
180
181# Create systemd service
182sudo cloudflared service install
183sudo systemctl start cloudflared
184sudo systemctl enable cloudflared
185
186# Now point Pi-hole at the local DoH proxy:
187# Pi-hole admin → Settings → DNS → Custom upstream DNS
188# Set to: 127.0.0.1#5053
189# Uncheck all other upstream resolvers
190```
191
192## Local DNS Records
193
194Make your services reachable by name (e.g. nas.home.lan, grafana.home.lan).
195
196> **Domain name note:** .home.lan is widely used in homelabs and works in practice.
197> The IETF-reserved suffix for local use is .home.arpa (RFC 8375) — use that to
198> follow the standard. Avoid .local for Pi-hole DNS records as it conflicts with
199> mDNS/Bonjour.
200
201```
202# Pi-hole admin → Local DNS → DNS Records
203
204 Domain IP
205 nas.home.lan 192.168.30.10
206 pi.home.lan 192.168.30.2
207 grafana.home.lan 192.168.30.3
208 proxmox.home.lan 192.168.30.4
209
210# From any device on your network:
211 ping nas.home.lan → 192.168.30.10
212 http://grafana.home.lan → your Grafana dashboard
213
214# For subdomains, add a CNAME:
215 Pi-hole admin → Local DNS → CNAME Records
216 Domain: portainer.home.lan → Target: pi.home.lan
217```
218
219## Troubleshooting
220
221```bash
222# Pi-hole blocking something it should not
223pihole -q example.com # Check if domain is blocked and which list
224pihole -w example.com # Whitelist immediately
225
226# DNS not resolving at all
227pihole status # Check if pihole-FTL is running
228dig @192.168.3.2 google.com # Test DNS directly against Pi-hole
229
230# Restart Pi-hole DNS
231pihole restartdns
232
233# Check query logs for a specific device
234pihole -t # Live tail of all queries
235# Or filter by client in the web admin Query Log
236
237# Pi-hole gravity update (refresh blocklists)
238pihole -g
239```
240
241## Anti-Patterns
242
243```
244# BAD: Depending on one Pi-hole without a recovery path
245# If Pi-hole crashes or the Pi loses power, DNS can stop working
246# GOOD: Keep a documented router fallback for rollback during setup
247# BETTER: Run two Pi-hole instances for redundancy; avoid public fallback DNS for strict blocking
248
249# BAD: Installing Pi-hole without a static IP
250# If the Pi gets a new DHCP IP, all devices lose DNS
251# GOOD: Set static IP first, then install Pi-hole
252
253# BAD: Enabling Pi-hole DHCP without disabling the router's DHCP first
254# Two DHCP servers on the same network hand out conflicting IPs
255# GOOD: Disable router DHCP, then enable Pi-hole DHCP
256
257# BAD: Never updating gravity (blocklists)
258# New ad and malware domains accumulate — stale lists miss them
259# GOOD: Schedule weekly gravity update: pihole -g (or enable in Settings → API)
260```
261
262## Best Practices
263
264- Give the Pi a static IP or DHCP reservation before installing Pi-hole
265- Use Pi-hole as primary DNS; for redundancy, add a second Pi-hole instead of a
266 public resolver if you need strict blocking
267- Enable DoH (DNS-over-HTTPS) with cloudflared for encrypted upstream queries
268- Set home.lan as your local domain and create DNS records for all your services
269- Review the Query Log occasionally — blocked queries show you what devices are doing
270
271## Related Skills
272
273- homelab-network-setup
274- homelab-vlan-segmentation
275- homelab-wireguard-vpn
276
In the file
SKILL.md1,339 words
Files1
LicenceMIT
Why you can read it

Nothing in a skill executes. The client loads the text and the model follows it, so a skill can be audited the way a runbook is — by reading it.

What it costs in context

Skills are not billed by the call. They are paid for in context: every token the instructions occupy is a token your code, your diff and your conversation cannot use. Here is what this one takes and when it takes it.

≈110
always loaded
The name and description, so the model knows the skill exists and when to reach for it.
2,290
on trigger
The instruction body, read only when the skill fires.
1.2%
of a 200k window
Ten skills this size would take about 12% of the window before you open a file.
050k100k150k200k context window

2.4k tokens, estimated from the bundle at four bytes to the token, held for the rest of the session once it triggers. Middling. Fine to keep on in a project where you use it weekly, worth unloading in one where you never do.

Servers bill, skills cost

A server charges by the month. A skill charges once per session, in context, and then keeps charging it for as long as the session lives.

Before and after

The same question, put to the same model twice: once as it comes, and once with these instructions loaded.

No worked example has been published for this skill yet.

Adoption
Installsnone yet
Ratingno reviews yet

The procedure it runs

The procedure has not been published here. It is in the skill’s own SKILL.md, which its author has not sent to the marketplace yet.

Prose, not code

These steps are written for a model to follow, not executed by a runtime. It can still be told to skip one, and it will say so when it does.

Servers it uses

None. This skill calls no MCP servers at all.

Everything it needs is in the instructions, so it works in a project with nothing connected — the model reads the file and changes how it works with what it can already reach.

It writes no files and reaches no network. All it changes is how the model reasons and writes.

What it asks for
Writes filesno
Network accessno

Read from the allowed-tools line of this skill’s own SKILL.md. A skill grants no permissions of its own — it can only ask for tools your client already has.

What it will not do

Every skill is narrow, and the useful ones say where they stop. These are the jobs this one is the wrong tool for.

What this skill is not for has not been published here. Nothing is implied by that: it is a section the author has not filled in.

What is in the bundle

1 file, 9.6 kB on disk. A bundle is text throughout: the instructions the model reads, plus the templates it fills in.

  • SKILL.md9.6 kB
What is not in it

No dependencies and nothing executable: a skill is text the agent reads, so the bundle is 1 file you can review in full before installing. The MIT licence covers the templates and examples as well as the instructions.

Install

Installing copies the bundle into your project. Nothing runs at install time — the files sit on disk until the model reads them.

$49 once
Homelab Pi-hole DNS · MIT · affaan-m
one-time
Price$49 once
LicenceMIT — the author’s, unchanged by this purchase
Paid throughStripe, once, on the card you add at the checkout
Keeps workingfor good — the files are yours once they are on disk
Updatesevery update its author ships, delivered through this account

You can read the whole bundle before paying — the SKILL.md above is the product, not a preview of it. What the money buys is the delivery: the folder packaged and handed to your machine by key, every update its author ships, and our support if it does not do what this listing says. The terms of use are MIT, set by the author and unchanged by buying it here.

Payment runs through Stripe, on a page like this one rather than a redirect. Once there is an account it joins the same mcprush invoice as everything else you run, so there is never a second card to enter.

Which clients pick it up on their own

A skill is a folder of text. A client with a skills folder reads it without being told; everywhere else the same text works, it is just handed to the model rather than found.

Claude Code.claude/skills/
Claude Desktop
ChatGPT
Cursor.cursor/skills/
VS Code.github/skills/
Codex CLI.agents/skills/
Gemini CLI.gemini/skills/
Grok.grok/skills/
Zed.agents/skills/
Windsurf.windsurf/skills/
Agent SDK.claude/skills/
HTTP / API
This release
Versionnot versioned
Publishedno release date on file
Price$49
Referenceaffaan-m/homelab-pi-hole-dns

Versions

Its author publishes no version number, so there is nothing here to pin to: what you install is the folder as it stands today. Instructions change more often than APIs do — a skill can be rewritten entirely without anything it depends on moving.

v
  • No earlier releases have been published to the marketplace.
Pinning

Nothing to pin to: this skill carries no version number of its own. What you install is what the folder holds on the day you install it.

Reviews

no reviews yet · no installs yet

Nobody has reviewed this skill yet. The rating is the mean of the reviews written here, so there is none until somebody writes the first.

Who can post

Only accounts that have had the skill installed for fourteen days, so a review is written after living with it rather than after reading it. Publishers may reply once.

Publisher
Servers0