Repository navigation
Description
Sub-issue of #102.
What and why
AdGuard Home GPL-3.0 Docker — awesome-selfhosted README.md:732.
The deployment shape is already decided — do not improvise it
ADR-0010 (#125) settles how clients reach this, and that question carried more risk than where the container runs:
- DHCP scopes do not change. Every client keeps pfSense as its only resolver.
- Unbound runs in forwarding mode, with AdGuard's Winterfell address first and the existing public upstreams still listed after it.
- The public upstreams stay in the list deliberately. With AdGuard as sole forwarder, a dead AdGuard costs every external name in the house — which is the household-wide single point of failure the ADR rejected.
matrix.elysiumhost overrides stay on pfSense.
Two consequences to build with rather than around:
- Per-client attribution is gone. AdGuard sees every query as coming from pfSense. Its dashboard is a single aggregate and per-device rules are not possible. ADR-0010 rests entirely on per-client filtering is not wanted; if that changes, reopen the ADR rather than working around it.
- Filtering is a convenience, not a control. The design lets it fail open on purpose. Nothing should be documented as relying on DNS blocking for security.
Detection is tracked elsewhere, and belongs there
#126 already covers the silent-failure problem in full, including the trap that a probe through the normal resolver path always passes because the fallback is doing its job. The mechanism is the blackbox-exporter in #91. Nothing about detection belongs in this issue — it is noted here only so the two are not solved twice or, worse, solved wrongly.
What it needs
- Blocklist selection, and a record of which lists are enabled — a blocklist set that exists only in the container's own database is the same failure mode ADR-0004 called out for Grafana dashboards.
- Admin credentials in
secrets/*.sops.yaml. - The Unbound forwarder edit on
morpheus, which is the entire client-side change. ADR-0010 notes this is also what makes the decision cheap to reverse: one config file, no DHCP change, no lease TTL to wait out. - Port 53 reachable from the firewall only — not from client VLANs, which is what keeps low-trust DNS out of VLAN 99.
Which VLAN this touches
🔴 99 — Winterfell (management)
Security review
- Does not weaken the default-deny posture between VLANs — ADR-0010 notes this arrangement strengthens it: DNS from low-trust segments terminates at their gateway and never enters 99
- Any new credential goes in
secrets/*.sops.yaml - Any new device is added to
docs/network.mdwith an OUI-truncated MAC — n/a
Depends on
#129 (Caddy) and the mini PC in #102. Governed by #125 / ADR-0010. Detection: #126, mechanism #91.
Corrected 2026-09-19
Authored in #429: the service, adguard/AdGuardHome.yaml as the tracked blocklist set, the admin credential as a bcrypt hash in SOPS, port 53 published on 10.0.99.40 only. The morpheus half is written and not run. "Depends on #102" → #404.
Done here is three acts, and the body names none of them:
- the forwarding-mode change on
morpheusperforward-dns-to-adguard.md— note the roadmap's warning that ADR-0010 is a resolution-mode change, not a list edit: Unbound today is recursive with zeroforward-zoneblocks; - the deliberate-failure test ADR-0010 asks for, with the runbook's measurement table (today:
| *not yet run* |) filled in; - the two
blackbox-dns.yamltargets uncommented instacks/observability.
Activity
Merge pull request #429 from Gerrrt/gerrrt/adguard-unbound-forwarder-…
Merge origin/main into gerrrt/paperless-ngx-sensitive-tier-ed6912
Merge origin/main into gerrrt/vaultwarden-sensitive-tier-b3ae98: AdGu…
Gerrrt commentedon Sep 28, 2026
Status as of 2026-09-28, against the three acts in the correction above:
morpheus: done. It is a single forwarder, not the three the body describes. With the public resolvers beside AdGuard, 38 of 60 blocked names leaked, so ADR-0055 superseded ADR-0010's fallback (docs(sensitive): trinity as built, and DNS forwarded to AdGuard alone (#404) #691). Re-checked fromtrinity: blocked names through10.0.99.1get no answer, and DNSSEC still validates.AdGuardNotAnsweringpages, not a fallback. Runforward-dns-to-adguard.mdstep 4 and fill in its table. That closes this issue.blackbox-dns.yamltargets: live since feat(dns): probe AdGuard on trinity (#404, #126) #690.Roadmap updated in #696.
docs(roadmap): AdGuard serving, failure test outstanding (#135) (#696)
fix(sensitive): size AdGuard for the daily refresh, not the first boot (
feat(sensitive): AdGuard blocks threat domains, and says why the rest…