Pi-hole DNS in a Multi-Machine Homelab
Separate container health, DNS service behavior and the client's chosen resolver.
When to use
Use when Pi-hole is in the DNS path or a Pi-hole change is requested. Use
docker-expert for general Compose failures and systematic-debugging for an
unexplained failure. This is not a replacement VPN, a generic VLAN installer,
or permission to change every machine's DNS settings.
First establish the path
- Identify the affected client, DNS host and connection (LAN, Wi-Fi, Tailscale,
VM or container). Record the actual resolver chain and whether DHCP, static
adapter settings, Tailscale or browser secure DNS selects it.
- Read the current Compose manifest and installed Pi-hole/FTL version. Keep
private addresses, credentials, raw query logs and client names out of public
reports. Inspect only necessary settings; avoid dumping full environments.
- Establish scope: one client, one domain, one host, or all resolution. Compare
a known allowed domain, a deliberately blocked test domain and any affected
internal name. Do not generate traffic to malware domains for a DNS test.
- Gather evidence before changes using diagnostic commands.
A healthy container, accessible web UI, working direct DNS query and correctly
routed client query prove different things. Report them separately.
Diagnose before changing
| Observation |
Investigate next |
| Direct query to Pi-hole fails |
FTL/service state, listening address, port 53 binding, upstream resolution |
| Direct query works; normal client query fails |
Client resolver selection, Tailscale DNS, adapter/VPN policy, caching |
| Public names work; internal names fail |
Local records, conditional forwarding and MagicDNS ownership |
| Resolution succeeds but filtering is bypassed |
Alternate resolvers, browser DoH, client routing and intended exceptions |
| DNS works but health check fails |
Health command, quoting, exit code, authentication and version mismatch |
| One Pi-hole differs from another |
Actual version/config and sync status; do not assume replicas agree |
Plan and apply a bounded fix
Use the current project's authorized change scope. Before touching DHCP, DNS,
routes or firewall settings, establish a working management/recovery path and
the exact setting to restore. Test one client/resolver before broad rollout.
Reuse existing Tailscale topology; do not install WireGuard or open router ports
as a side effect of this skill. Do not introduce Pi-hole DHCP where another DHCP
server already owns the network without an explicit migration plan.
For v6 Docker configuration, consult version-aware configuration.
Validate Compose without printing expanded secrets. Restart/recreate only the
affected service when the evidence and authorized fix require it. A restart
alone is not a root-cause explanation. Verify direct DNS, ordinary client DNS,
required internal names and intended filtering after a change.
Report
State the observed resolver path, checks run, root-cause evidence, exact changes,
post-change results and unresolved checks. A planned rollout, local success or
OneDrive delivery is not an observed result on another machine. Do not claim
all clients pass without testing them; honor the user's requested rollout scope.
Prerequisites and provenance
Requires access to the relevant client's DNS tools and authorized host/container
diagnostics. This skill installs nothing and contains no credentials or fleet IPs.
Load companions through skill-router.
Adapted from ECC Pi-hole guidance
and network readiness.
See MIT notice. Local adaptation replaces old installation recipes
with v6 checks, Windows diagnostics and existing-Tailscale safeguards.
1---2name: homelab-pihole-dns3description: >-4 Diagnose and plan Pi-hole DNS changes in Docker homelabs with Windows clients5 and Tailscale. Use for Pi-hole health, blocked domains, broken resolution,6 DNS routing, v6 configuration and resolver rollout readiness.7license: MIT8metadata:9 source: https://skillmd.com/skills/hongyime/homelab-pihole-dns10 author: Local setup, adapted from ECC11 version: "1.0.0"12 platform: Windows clients and Linux/Docker DNS hosts13---1415# Pi-hole DNS in a Multi-Machine Homelab1617Separate container health, DNS service behavior and the client's chosen resolver.1819## When to use2021Use when Pi-hole is in the DNS path or a Pi-hole change is requested. Use22`docker-expert` for general Compose failures and `systematic-debugging` for an23unexplained failure. This is not a replacement VPN, a generic VLAN installer,24or permission to change every machine's DNS settings.2526## First establish the path27281. Identify the affected client, DNS host and connection (LAN, Wi-Fi, Tailscale,29 VM or container). Record the actual resolver chain and whether DHCP, static30 adapter settings, Tailscale or browser secure DNS selects it.312. Read the current Compose manifest and installed Pi-hole/FTL version. Keep32 private addresses, credentials, raw query logs and client names out of public33 reports. Inspect only necessary settings; avoid dumping full environments.343. Establish scope: one client, one domain, one host, or all resolution. Compare35 a known allowed domain, a deliberately blocked test domain and any affected36 internal name. Do not generate traffic to malware domains for a DNS test.374. Gather evidence before changes using [diagnostic commands](references/diagnostics.md).38 A healthy container, accessible web UI, working direct DNS query and correctly39 routed client query prove different things. Report them separately.4041## Diagnose before changing4243| Observation | Investigate next |44|---|---|45| Direct query to Pi-hole fails | FTL/service state, listening address, port 53 binding, upstream resolution |46| Direct query works; normal client query fails | Client resolver selection, Tailscale DNS, adapter/VPN policy, caching |47| Public names work; internal names fail | Local records, conditional forwarding and MagicDNS ownership |48| Resolution succeeds but filtering is bypassed | Alternate resolvers, browser DoH, client routing and intended exceptions |49| DNS works but health check fails | Health command, quoting, exit code, authentication and version mismatch |50| One Pi-hole differs from another | Actual version/config and sync status; do not assume replicas agree |5152## Plan and apply a bounded fix5354Use the current project's authorized change scope. Before touching DHCP, DNS,55routes or firewall settings, establish a working management/recovery path and56the exact setting to restore. Test one client/resolver before broad rollout.57Reuse existing Tailscale topology; do not install WireGuard or open router ports58as a side effect of this skill. Do not introduce Pi-hole DHCP where another DHCP59server already owns the network without an explicit migration plan.6061For v6 Docker configuration, consult [version-aware configuration](references/configuration.md).62Validate Compose without printing expanded secrets. Restart/recreate only the63affected service when the evidence and authorized fix require it. A restart64alone is not a root-cause explanation. Verify direct DNS, ordinary client DNS,65required internal names and intended filtering after a change.6667## Report6869State the observed resolver path, checks run, root-cause evidence, exact changes,70post-change results and unresolved checks. A planned rollout, local success or71OneDrive delivery is not an observed result on another machine. Do not claim72all clients pass without testing them; honor the user's requested rollout scope.7374## Prerequisites and provenance7576Requires access to the relevant client's DNS tools and authorized host/container77diagnostics. This skill installs nothing and contains no credentials or fleet IPs.78Load companions through `skill-router`.7980Adapted from [ECC Pi-hole guidance](https://github.com/affaan-m/ECC/blob/e482e579415fde18357cafce70f177ae19fd7f03/skills/homelab-pihole-dns/SKILL.md)81and [network readiness](https://github.com/affaan-m/ECC/blob/e482e579415fde18357cafce70f177ae19fd7f03/skills/homelab-network-readiness/SKILL.md).82See [MIT notice](LICENSE.txt). Local adaptation replaces old installation recipes83with v6 checks, Windows diagnostics and existing-Tailscale safeguards.