vps/docs/adguard-home-official-review-2026-08.md

AdGuard Home official configuration review basis (2026-08)

This page is the official source basis and recommendation baseline used during the on-site review of AdGuard Home (AGH) on 192.168.66.36. It does not claim to have read that host's configuration and contains no credentials. On-site conclusions must be based on the live AdGuardHome.yaml, OpenWrt dnsmasq/DHCP, firewall, routing, and actual client leases.

Official sources (AdGuard only):

• Configuration
• Setting up AdGuard Home securely
• Getting started
• DHCP
• DNS encryption

Recommended role split (for the existing OpenWrt gateway)

Preferred: keep OpenWrt/dnsmasq as the single DHCP and local-domain authority, with AGH as the LAN DNS filter/forwarder: DHCP option 6 hands clients .36; AGH sets the router's local DNS (usually the gateway LAN IP) as local_ptr_upstreams and, where needed, uses domain-specific upstreams to route the LAN search domain / local names back to dnsmasq. Clients are filtered while still keeping DHCP lease names, static hosts, local reverse resolution, and gateway-internal service discovery.

Rationale: AGH supports dnsmasq-style domain-specific upstreams for internal private name servers; private PTR should be configured in Private reverse DNS servers / local_ptr_upstreams rather than regular upstreams; when not explicitly configured, it falls back to the OS default resolver, which shifts as host networking changes. Official config: domain-specific upstreams; private rDNS.

Do not have OpenWrt dnsmasq and AGH both listen on :53 at the same LAN IP; port conflicts, or pointing dnsmasq's upstream at AGH while AGH points back at dnsmasq, cause failures/forwarding loops. When AGH runs on a separate .36 host, the simplest topology is clients → AGH .36:53 → public/encrypted upstreams, forwarding only local resolution (PTR, LAN domain) → gateway dnsmasq. This is an operational inference based on the official capabilities above and must be validated against the live ss -lntup, dnsmasq config, and query path.

AGH also has built-in DHCP, but it should only be enabled after disabling the existing gateway DHCP, explicitly migrating leases/reservations and verifying options 3/6. The official docs describe it as an alternative when the router cannot hand out custom DNS, not as a dual-DHCP setup; the DHCP docs also state leases/static leases are managed by AGH. Getting started: router DHCP/DNS handout and alternative DHCP; DHCP configuration.

Exposure and access control

1. dns.bind_hosts should bind only loopback and the actual LAN address (here prefer .36's LAN address); do not use 0.0.0.0/public interfaces for a home recursive resolver. The official docs note full-interface binding exposes DDoS risk; a small isolated network should pick local service interfaces and may add loopback alongside. Secure deployment: server addresses; bind_hosts definition.
2. In the firewall, allow only managed LAN/VLAN → .36 TCP/UDP 53; bind the web admin UI to the management network/loopback and avoid WAN forwarding. At the app layer, further restrict with allowed_clients to the local subnets; when non-empty, only the CIDR/IP/ClientIDs in it are accepted, and it overrides the effect of disallowed_clients. Official access control.
3. Keep refuse_any: true and a non-zero ratelimit (default 20 qps), unless on-site evidence shows the service can never be reached from the internet and LAN high-concurrency needs are data-backed; the official docs list both as protection against reflection/DDoS. Configuration notes.
4. The web UI must have a user with login-failure lockout enabled; users: [] disables authentication, and auth_attempts or block_auth_min of 0 disables the corresponding lockout logic. Web/auth parameters.

Upstreams, encryption, and DNSSEC

• Use two trusted, differently-networked DoH/DoT/DoQ upstreams for normal public resolution; AGH supports these protocols and DNS Stamps. If an upstream URL/hostname needs resolving, bootstrap_dns is its initial resolver; do not point bootstrap at a name that requires AGH itself to resolve, and use directly reachable, stable IPs. A fallback_dns can be set separately; it is used only when primary upstreams do not respond. Upstream protocols and bootstrap/fallback.
• If local IPv6's actual egress path is unstable, do not enable bootstrap_prefer_ipv6; the official docs note it makes DoH/DoQ/DoT bootstrap prefer IPv6. Decide on-site based on each upstream's IPv4/IPv6 reachability, latency, and failure rate. Same reference.
• Consider enabling enable_dnssec, choosing recursive upstreams that actually handle DNSSEC; but understand precisely: officially AGH sets the DO flag on requests to upstreams; it does not perform recursive validation itself. On site, query a known-bad-signature domain and observe AD/failure responses to confirm upstream validation behavior. DNSSEC parameter definition.
• Prefer upstream_mode: load_balance unless measurement shows parallel first answer latency is clearly worth the privacy/traffic cost of querying all upstreams. The former picks by failure rate and average latency weighting; the latter queries all upstreams concurrently; this is an operational judgment based on documented behavior. Upstream modes.

Cache, ECS, and privacy

• Keep DNS cache enabled; use cache_ttl_min/cache_ttl_max overrides cautiously to avoid stale or unnecessarily short TTLs. cache_optimistic answers with a 10-second TTL after expiry and attempts refresh — good for low-latency scenarios that tolerate briefly stale results, not to be enabled blindly on internal domains sensitive to immediate changes. Cache parameters.
• ECS is off by default: when enabled, AGH adds EDNS Client Subnet to upstream requests; if CDN geo-scheduling is truly needed, use use_custom: true with a coarse, non-real-client-subnet custom_ip, then compare hit rate vs. privacy impact. ECS parameters.
• Review log retention and who can read it. If device identity is not needed, consider anonymize_client_ip: true; this anonymizes client addresses in logs and stats. Anonymization parameter.

Proxy / OpenClash coexistence

If OpenClash/transparent proxy redirects DNS, validate hop by hop to ensure: client DNS requests reach AGH uniquely; AGH's outbound traffic to public encrypted upstreams is not hijacked back to AGH; and the router's local dnsmasq PTR/local-domain requests return to dnsmasq. Create explicit proxy/hijack exceptions for .36 and its upstreams, or explicitly design the proxy to take over AGH's outbound resolution; do not rely on "it seems to resolve" to conclude there is no loop.

This is not an AGH-official OpenClash instruction (the official docs do not maintain that integration), but an on-site verification requirement derived from AGH's independent listening, upstream forwarding, and local-PTR-split capabilities. The officially supported mechanisms are referenced at bind_hosts/upstreams/PTR.

If serving DoH via a reverse proxy, trusted_proxies must list only the actual proxy IP/CIDR; AGH will only trust X-Real-IP, X-Forwarded-For, etc. from those sources. Do not write the whole LAN/WAN for convenience; http.doh.insecure_enabled should only be enabled when a reverse proxy really terminates TLS in front. Proxy and DoH; encrypted DNS docs. For a pure-LAN plaintext-53 service, publishing DoH/DoT/DoQ outward is usually unnecessary.

On-site review checklist (read-only)

1. Record the version, service method, and the full effective configuration (secrets redacted); run the AGH config check. Officially provided via --check-config. Command-line arguments.
2. On .36, the gateway, and a wired/wireless client, record ss listeners, DHCP option 6, default route, /etc/config/dhcp, and OpenClash DNS/firewall-redirect rules.
3. From a client test: public A/AAAA, ad-rule hits, DHCP hostnames, forward LAN domain, private PTR, DNSSEC bad-signature domain, and the expected failure mode when AGH stops. Then check whether client IPs in AGH query logs are still genuinely identifiable.
4. From the AGH host, test each upstream and bootstrap over the actual protocol for IPv4 and IPv6 reachability; compare with transparent proxy on/off to rule out loops and leaks.
5. Verify the web UI/DNS ports have no WAN exposure; confirm allowed clients and firewall match actual LAN/VLAN, guest network, and VPN subnets.

Before changing anything, export the current configuration and DHCP/firewall state; adjust one layer at a time (DHCP handout, AGH listening, upstreams, or DNS hijack) and keep a known-good management and DNS fallback path.