windy/vps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
c445c5f51225b3e001b8961e46cac334b4b4a9bf
vps/docs/adguard-home-official-review-2026-08.md
T
windyboy b03d7019c4 docs: onboard AdGuard Home to Ansible; retire check-mx2; migrate plan to Linear 
- Add dns.windy.lan to Ansible inventory (adguardhome group/profile) with a
  read-only healthcheck template, systemd timer, and on-demand report parity
  with the other active hosts; verified green on the host.
- Add synapse.chans.xyz to the AGENTS.md active-host quick map.
- Remove plans/; migrate decisions/verification to a Linear vps project doc and
  file the remaining gaps as W1N-46..49 with blocking edges.
- Retire scripts/check-mx2.sh; point mailcow health/update runbooks and the
  mx2 host file at the Ansible health report.
- Trim us2 stub software to verified running services; note dormant dirs.
- Normalize repo docs to English; drop the non-existent CONTEXT.md/ADR claim
  and remove docs/agents/domain.md.
2026-08-06 15:48:48 +08:00

164 lines
10 KiB
Markdown
Raw Blame History

# 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](https://adguard-dns.io/kb/adguard-home/configuration/)
- [Setting up AdGuard Home securely](https://adguard-dns.io/kb/adguard-home/running-securely/)
- [Getting started](https://adguard-dns.io/kb/adguard-home/getting-started/)
- [DHCP](https://adguard-dns.io/kb/adguard-home/dhcp/)
- [DNS encryption](https://adguard-dns.io/kb/adguard-home/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](https://adguard-dns.io/kb/adguard-home/configuration/#configuring-upstreams);
[private rDNS](https://adguard-dns.io/kb/adguard-home/configuration/#private-addresses).
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](https://adguard-dns.io/kb/adguard-home/getting-started/#router);
[DHCP configuration](https://adguard-dns.io/kb/adguard-home/dhcp/).
## 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](https://adguard-dns.io/kb/adguard-home/running-securely/#choosing-server-addresses);
[`bind_hosts` definition](https://adguard-dns.io/kb/adguard-home/configuration/#dns).
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](https://adguard-dns.io/kb/adguard-home/configuration/#dns).
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](https://adguard-dns.io/kb/adguard-home/configuration/#dns).
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](https://adguard-dns.io/kb/adguard-home/configuration/#users).
## 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](https://adguard-dns.io/kb/adguard-home/configuration/#dns).
- 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](https://adguard-dns.io/kb/adguard-home/configuration/#dns).
- 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](https://adguard-dns.io/kb/adguard-home/configuration/#dns).
- 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](https://adguard-dns.io/kb/adguard-home/configuration/#dns).
## 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](https://adguard-dns.io/kb/adguard-home/configuration/#dns).
- 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](https://adguard-dns.io/kb/adguard-home/configuration/#dns).
- 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](https://adguard-dns.io/kb/adguard-home/configuration/#dns).
## 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](https://adguard-dns.io/kb/adguard-home/configuration/#dns).
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](https://adguard-dns.io/kb/adguard-home/configuration/#dns); [encrypted DNS
docs](https://adguard-dns.io/kb/adguard-home/encryption/). 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](https://adguard-dns.io/kb/adguard-home/configuration/#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.
Reference in New Issue View Git Blame Copy Permalink