Skip to content

Sensitive tier: AdGuard Home, as a forwarder behind Unbound and not a client-facing resolver #135

Closed

Description

@Gerrrt

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.elysium host overrides stay on pfSense.

Two consequences to build with rather than around:

  1. 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.
  2. 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.md with 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:

  1. the forwarding-mode change on morpheus per forward-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 zero forward-zone blocks;
  2. the deliberate-failure test ADR-0010 asks for, with the runbook's measurement table (today: | *not yet run* |) filled in;
  3. the two blackbox-dns.yaml targets uncommented in stacks/observability.

Activity

  1. added this to the Wave 1 — trinity milestone on Sep 11, 2026
  2. Gerrrt commented on Sep 28, 2026

    @Gerrrt
    OwnerAuthor

    Status as of 2026-09-28, against the three acts in the correction above:

    1. Forwarding on 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 from trinity: blocked names through 10.0.99.1 get no answer, and DNSSEC still validates.
    2. Failure test: not yet run, deferred by choice. It takes outside DNS from the house for about 7–10 minutes. Since ADR-0055 it proves that AdGuardNotAnswering pages, not a fallback. Run forward-dns-to-adguard.md step 4 and fill in its table. That closes this issue.
    3. blackbox-dns.yaml targets: live since feat(dns): probe AdGuard on trinity (#404, #126) #690.

    Roadmap updated in #696.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureA new capability or a changesensitivestacks/sensitive on trinity (VLAN 99)

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions