For the technical audience
Decisions ADR-951 to ADR-1000
Every architecture decision record (ADR) behind WrenDNS: what we knew, what we chose, and what it costs. This page is built from the specification on every change, so it's always the current record.
ADR-951 OIDC without chrono: an in-tree verifier on ring, replacing openidconnect and oauth2openidconnect 4.x and oauth2 5.x pull chrono (RUSTSEC-2026-0543, unmaintained, no patched version), which deny.toml ignored (fork #17, T24.23).
Context
openidconnect 4.x and oauth2 5.x pull chrono (RUSTSEC-2026-0543, unmaintained, no patched version), which deny.toml ignored (fork #17, T24.23). cargo tree -i chrono showed chrono arriving only through oauth2 v5.0.0 and openidconnect v4.1.0, and openidconnect only through wrendns-api. rsa v0.9.10 (RUSTSEC-2023-0071, ignored) also arrived only through openidconnect. wrendns-api had its own chrono dev-dependency (flow_tests.rs). ring 0.17.14 is already a normal dependency (via rustls, rcgen, hickory-proto and others), so the in-tree verifier adds no crate.
Current behaviour (crates/wrendns-api/src/auth/oidc.rs before this change) that the replacement keeps:
- Discovery: the document's
issuermust equal the configured issuer; a second fetch readend_session_endpoint. Cached for 1 h (DISCOVERY_TTL). - Start and finish: authorization code with PKCE S256; random state and nonce; a flow lives 10 min (
FLOW_TTL), at most 1000 (MAX_FLOWS), is single-use, and is bound to the browser cookie and the provider. - Token exchange:
exchange_codewith the PKCE verifier, and HTTP Basic client authentication (openidconnect's default with a secret). - ID token: nine algorithms (RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, EdDSA). A signature failure ran a full discovery refresh with no rate limit.
- MCP access tokens (
verify_access_token):iss(trailing slash ignored),aud(string or array) equal tomcp.audience,expandnbfwith 60 s leeway, key chosen bykid, the nine algorithms. - Config (
crates/wrendns-config/src/validate.rs:1375-1380): the issuer must start withhttps://orhttp://, and a plain-HTTP issuer already produces the warning "plain HTTP is only safe for local testing". - Claims mapping (
identity,role_for,username_for, the agent role cap,oauth_principal) is pure and unchanged by this ADR.
Options
- (a) Keep
openidconnectandoauth2. Rejected:chronoand the ignore stay. - (b-ring) Chosen. An in-tree verifier on
ring: JWK-to-key conversion (RSAn/e, ECx/yas an uncompressed point, OKPxfor Ed25519), the JWS verification for the nine algorithms (ring::signature), the header rules, and all claim checks. No new crate. T24.23 asks for "a library without chrono, or a minimal flow on crates the tree already has", andringis such a crate. The signature glue is the riskiest code, so it is kept small, has one module (oidc/jose.rs), and is pinned by tests for each family and each rejection. - (b-p256) The same verifier on
rsa,p256andecdsa. Rejected:rsastays, so RUSTSEC-2023-0071 stays. - (c-9)
jsonwebtoken9.3.1. Rejected after the review. 9.x is a frozen line:cargo infoshows 12.0.0 as the latest, two majors ahead, and 9.x gets no fixes. 9.3.1 also silently ignores a claim of the wrong JSON type:validate()skipsiss,audandnbfthat fail to parse unless they are inrequired_spec_claims(src/validation.rs:255-330), so"nbf":"9999999999"is never checked. ItsValidationallow-list also refuses every token when it mixes algorithm families (src/decoding.rs:216-221). Using it for the signature only would still leave the claim parsing in-tree, and it adds thepemandsimple_asn1crates and a secondbase64. - (c-10 / c-12)
jsonwebtoken10 or 12. Rejected. Its crypto backend isaws-lc-rs(a C build, large image) or RustCrypto (includesrsa, so RUSTSEC-2023-0071 stays). Aring-backedCryptoProvider(12.0.0src/crypto/mod.rs:83-97) is possible, but then the crate contributes only the JWS parsing, which we write anyway, and it still adds a crate and itsCryptoProviderglue. - (d) Another OIDC client library. Not chosen. The two clients checked both list
chronoas a normal dependency on crates.io. Other crates were not surveyed exhaustively; reopen only if a candidate is shown chrono-free.
Recommendation
(b-ring). It removes openidconnect, oauth2, chrono and rsa from the tree, adds no crate (ring becomes a direct edge of wrendns-api), and keeps all OIDC policy (claims, nonce, state, discovery, key rotation) in wrendns-api, pinned by tests.
Decisions (accepted by the owner 2026-11-17 as implemented; the in-tree verifier on ring is the decision, and jsonwebtoken is not used, for the reasons in (c-9) and (c-10 / c-12)):
- Library: (b-ring), as above.
- Parity: observable behaviour stays the same, except these tightenings: (i) ID tokens use the nine algorithms intersected with the provider's
id_token_signing_alg_values_supportedwhen it lists them (an empty intersection refuses every ID token); MCP access tokens keep the nine, as today; (ii) a signature failure or an unknownkidrefetches the key set (not the discovery document), at most once per provider per 60 s, one fetch at a time per provider, and a failed fetch keeps the cached keys; (iii)noneand HS* are never accepted; (iv) an ID token's audience must be exactlyclient_id(any other audience is refused, even alongside it). - HTTP issuers stay accepted, as today. The plain-HTTP warning already exists (
validate.rs:1377-1380), so this ADR adds no startup warning. New rule: when the issuer is HTTPS, the discovery document'sauthorization_endpoint,token_endpointandjwks_urimust be HTTPS, or the discovery is refused; anend_session_endpointthat isn't HTTPS is dropped. Discovery and key-set responses over 1 MiB are refused (the binary's fetch already caps at 1 MiB). - Clock skew (review finding 5): ID tokens have no leeway on
exp, as openidconnect has today (cur_time >= expirationinopenidconnect-4.1.0/src/verification/mod.rs, around line 823). The 60 s leeway the first draft proposed forexpwould have loosened the check, so it is withdrawn.iatis required and may be at most 60 s in the future (openidconnect checks noiatby default, sinceiat_verifier_fnisOk,mod.rs:547, so this tightens it).nbf, when present, may be at most 60 s in the future. MCP access tokens keep 60 s forexpandnbf, as today. - Keys: an RSA key whose modulus is under 2048 bits is refused when read (ring's verification minimum; Keycloak and Authentik default to 2048 or more). An EC key must be on the curve its algorithm names (P-256 for ES256, P-384 for ES384); an OKP key must be Ed25519. A JWK with
useother thansigis ignored, and so is a JWK whosealgdiffers from the token's. Without akidin the token, exactly one fitting key must exist (more than one is refused as ambiguous, as openidconnect does viaAmbiguousKeyId).docs/running.mdsays so. - Client authentication (review finding 5): with a secret, HTTP Basic (
client_secret_basic), withclient_idandclient_secretform-encoded first (RFC 6749 §2.3.1). If the provider liststoken_endpoint_auth_methods_supportedwithoutclient_secret_basicbut withclient_secret_post, the secret goes in the form body. If it lists neither, sign-in is refused with a config-level message. Without a secret (a public client),client_idgoes in the body and no Basic header is sent. The openidconnect 4.1.0 source (src/client.rs:341-348) confirms Basic with a secret and the bodyclient_idwithout one, so the spike's "confirm in source" step is done. - No new setting in this change. The Settings page,
[auth.oidc]keys and help topics stay as they are. - Out of scope, unchanged: refresh tokens and userinfo are not implemented, and logout keeps using
end_session_endpointas today.
Algorithm and key rules (enforced in oidc/jose.rs before any signature is checked, in this order):
- The header must parse, and its
algmust be one of the allowed algorithms.none, HS256/384/512 and anything else are refused before any key is looked at, so an allow-list is never compared with a key of another family. typ, when present, must beJWT,application/jwtorapplication/josefor an ID token. An access token also acceptsat+jwtandapplication/at+jwt. Atypofat+jwttherefore can't pass as an ID token.ctyofJWT(orapplication/jwt) is refused (nested JWTs). Acritheader is refused (no critical extension is implemented).- A key fits the token when: its type matches the algorithm (RSA for RS* and PS*, EC P-256 for ES256, EC P-384 for ES384, OKP Ed25519 for EdDSA); its
useis absent orsig; itsalg, when present, equals the token's; and, when the token has akid, itskidequals it. - No fitting key refuses the token and may trigger a refetch. A
kidthe key set doesn't hold does the same. More than one fitting key without akidis refused as ambiguous, with no refetch. A fitting key whose signature doesn't verify refuses the token and may trigger a refetch. - The payload must be a JSON object.
ID-token checks (in finish, after the signature):
issis a string equal to the configured issuer (exact match, as openidconnect does).audis a string or an array of strings, every value equal toclient_id(an empty array is refused).azp, when present, is a string equal toclient_id;azpis required whenaudhas more than one value.subis a non-empty string.expis a whole-second JSON number, andnow < exp(no leeway).iatis a whole-second JSON number, present, and not more than 60 s ahead ofnow.nbf, when present, is a whole-second JSON number, not more than 60 s ahead ofnow.nonceis a string equal to the flow's nonce.- State is single-use, within the TTL, and bound to the browser; the PKCE verifier is sent with the token request.
at_hashis not checked (the code flow does not use it, as today).- Every date claim is strict: a string, a fraction or a negative value is refused, never skipped.
Discovery and transport
one discovery document per provider (cached 1 h) gives the endpoints, end_session_endpoint and the algorithm and client-auth lists. The key set is fetched from its jwks_uri. Requests don't follow redirects (the binary's fetch doesn't). Responses over 1 MiB are refused. The HTTPS rule is decision 3.
JWKS refetch
the key set is refetched after an unknown kid or a failed signature, at most once per provider per 60 s. One fetch runs at a time per provider (a per-provider async lock), so concurrent refetches collapse into one, and a request that waited uses the keys the first one fetched. A failed fetch keeps the cached keys and logs a warning.
Access tokens (MCP): the nine algorithms (not the discovery intersection, as today), the same key and header rules with the access-token typ set, and the existing iss (trailing slash ignored), aud, exp and nbf checks with 60 s leeway, unchanged. iat is not checked, as today.
Negative and positive tests (REQ API-004 and AGT-008; the names are the test functions in oidc/verify_tests.rs and oidc/flow_tests.rs). Each rejection is refused:
- bad signature (one flipped bit):
api_004_bad_signature_is_refused; signed by a key whosekidis not published:api_004_a_token_from_another_provider_is_refused,api_004_key_set_refetch_is_rate_limited_and_keeps_good_keys; audwithoutclient_id,audarray withoutclient_id, an extra untrusted audience (api_004_extra_untrusted_audience_rejected),audarray of two withoutazp, andazpnotclient_id:api_004_id_token_claims_are_checked_with_strict_types,api_004_tampered_claims_are_refused;- wrong
iss, and a number asiss:api_004_tampered_claims_are_refused; discoveryissuernot the configured one, and discovery with an HTTP endpoint for an HTTPS issuer:api_004_discovery_must_name_the_configured_issuer_and_https_endpoints,api_004_scheme_downgrade_is_refused; - expired token,
nbfin the future,iatmore than 60 s ahead, a missingiat,expandnbfas strings:api_004_id_token_expiry_has_no_leeway_and_iat_and_nbf_allow_sixty_seconds,api_004_tampered_claims_are_refused; - nonce mismatch, nonce replay (a second use of the same state), state mismatch, and a state this browser didn't start:
api_004_tampered_claims_are_refused,api_004_state_mismatch_and_replay_are_refused, and the existingapi_004_states_are_single_use_and_unknown_providers_404. A missingcode_verifieris refused by the fake provider's token endpoint, which requires it on every exchange; alg=none, and HS256 with the public key bytes as the secret:api_004_forged_and_mistyped_headers_are_refused,api_004_none_and_hmac_tokens_are_never_accepted;- key-kind mismatch, EC key on the wrong curve, OKP key that isn't Ed25519, RSA key under 2048 bits,
use=encignored, and a JWKalgthat differs from the token's:api_004_key_kind_and_curve_must_fit_the_algorithm,api_004_okp_key_must_be_ed25519_and_rsa_must_be_2048_bits,api_004_symmetric_and_encryption_keys_are_not_used,api_004_the_jwk_alg_must_equal_the_token_alg; - a provider that lists only RS256 in
id_token_signing_alg_values_supported, and an ES256 token arrives:api_004_the_provider_allow_list_refuses_other_algorithms,api_004_the_provider_allow_list_is_enforced_in_the_flow; typ=at+jwt,cty=JWTandcrit:api_004_typ_cty_and_crit_are_checked,api_004_forged_and_mistyped_headers_are_refused;- a missing
kidwith two eligible keys:api_004_a_missing_kid_with_two_eligible_keys_is_refused; - a token signed by provider B presented at provider A's callback:
api_004_a_token_from_another_provider_is_refused; - an oversized discovery or key-set response:
api_004_an_oversized_provider_response_is_refused; - JWKS rotation: a new
kidis refused before the refetch and accepted after it:api_004_a_new_kid_is_rejected_before_the_refetch_and_accepted_after_it,api_004_jwks_rotation_is_accepted_after_the_refetch; - the refetch rate limit, per provider, and one fetch for concurrent refetches:
api_004_key_set_refetch_is_rate_limited_and_keeps_good_keys,api_004_concurrent_refetches_collapse_into_one; - a failed refetch keeps the cached keys:
api_004_a_failed_key_set_refetch_keeps_the_cached_keys; - one positive test per signing family, RS256 through EdDSA:
api_004_each_signing_family_verifies(all nine),api_004_es256_and_eddsa_providers_sign_in(end to end), and the RS256 sign-ins in the existing flow tests; - a public client without a secret signs in:
api_004_public_client_signs_in_without_a_secret; a provider that lists onlyclient_secret_post:api_004_client_secret_post_when_it_is_the_only_method; - MCP (AGT-008): another provider's key,
alg=none, HS256 with the public key, an unknownkidwith the rate limit, and the MCP provider's own token still working:agt_008_mcp_token_negatives. The existingagt_008_mcp_oauth_access_tokenscovers the expiry, audience and forged-signature cases.
Parity checklist (review finding 9). These behave as before, and the tests named stay in place:
- groups: a dotted claim path (
realm_access.roles), a string or an array, a leading/dropped, a string split on commas and spaces:api_004_claims_to_identity_and_role(body unchanged); require_verified_email:email_verifiedtrue or"true":roleinoidc.rs, unchanged;rolesanddefault_role: the highest mapped role, else the default:role_for, unchanged;mcp.providerandmcp.audience, and the RFC 9728 metadata:agt_008_mcp_oauth_access_tokens(body unchanged);- the
disable_local_loginbreak-glass for admins fromallowed_admin_networks(auth/mod.rs:745):api_004_disable_local_login_keeps_a_break_glass_admin(body unchanged); - per-provider caches for discovery and the key set, and multiple providers:
four_providerscovers four in one app; - single-use state, the browser binding, safe return paths, the flow TTL and the flow cap, username collision (
name@provider), JIT creation and the role audit, RP-initiated logout:api_004_oidc_sign_in_end_to_end(body unchanged),api_004_return_paths_stay_inside_the_ui.
The existing flow tests keep their bodies. What changed in flow_tests.rs is the fake identity provider (it now signs with ring, serves each provider by host, and can rotate keys, advertise algorithms, require client_secret_post, or downgrade a URL), the signing helper behind access_token and sign_in, and the chrono call in agt_008 (now std::time).
Fixtures
test-key.pem (a 2048-bit PKCS#1 RSA key, the only RSA key ring can read here, since ring can't generate RSA keys) signs the RS* and PS* tokens. EC and Ed25519 keys are generated at test time with ring. The sub-2048-bit RSA case uses a synthetic 1024-bit JWK, which is refused when read, so it needs no key file. No new fixture is committed.
Dependency footprint
ring 0.17.14 becomes a direct edge of wrendns-api (already in the tree; no new crate). Removed: openidconnect (with its subtree: rsa, chrono, oauth2, num-bigint-dig), chrono (the dev-dependency), and the [profile.release.package] entries for openidconnect, oauth2, chrono, rsa and num-bigint-dig. Cargo.lock goes from 458 to 389 packages. cargo tree -i chrono, -i rsa, -i openidconnect and -i oauth2 print nothing, and cargo deny check passes with no ignore (ADR-952).
Verification
cargo test -p wrendns-api (every test passes; 38 of them are OIDC); cargo clippy -D warnings; cargo deny check; 3-oidc against Keycloak and Authentik (OIDC_E2E); the image delta (deploy/image/size.py --oci). The image delta and the 3-oidc result are recorded in the T24.23 Done note.
Consequences
RUSTSEC-2026-0543 and RUSTSEC-2023-0071 leave deny.toml together (ADR-952). The verifier is ours to audit (about 540 lines in oidc/jose.rs, claims.rs and metadata.rs, plus the flow in oidc.rs), so the reviewer (Opus) should read jose.rs against the rules above. Tokens that the old code accepted and the new rules refuse: an ID token with an extra audience or a missing iat, a key under 2048 bits, an ambiguous key with no kid, typ at+jwt on an ID token, and a non-HTTPS endpoint under an HTTPS issuer. docs/running.md lists them.
Review revisions (the review of docs/oidc-without-chrono, 2026-11-17): HIGH 1, implemented (T24.23 steps 3 to 7). HIGH 2, the audience must be exactly client_id, with api_004_extra_untrusted_audience_rejected. HIGH 3, jsonwebtoken rejected and (b-ring) chosen, with the 9.x and 12.x facts above. MEDIUM 4, the algorithm check happens before key choice, with the one-key-per-family test. MEDIUM 5, clock skew and client authentication decided as above. MEDIUM 6, key and header rules added, with tests. MEDIUM 7, transport, size, concurrency and refetch-failure rules added, with tests. MEDIUM 8, the negative list is implemented. MEDIUM 9, the parity checklist above. LOW 10, the footprint is ring only, with no pem, simple_asn1 or base64 duplicate. LOW 11, the existing warning is referenced, with no new one. LOW 12, step 5 cites the right lines (Cargo.toml: openidconnect at :26, chrono as a dev-dependency at :47; oauth2 was never a direct dependency of wrendns-api). LOW 13, fixtures as above.
Requirements AGT-008 API-004
Builds on ADR-952
Referenced by ADR-034 ADR-1049 ADR-1067 ADR-952 ADR-966
Link to this decision · In the specification
ADR-952 The chrono and rsa advisories under the OIDC changedeny.toml ignored RUSTSEC-2026-0543 (chrono, unmaintained) and RUSTSEC-2023-0071 (rsa, timing side channel).
Context
deny.toml ignored RUSTSEC-2026-0543 (chrono, unmaintained) and RUSTSEC-2023-0071 (rsa, timing side channel). Both arrived only through openidconnect (ADR-951 Context).
Decision
ADR-951 chose (b-ring), so neither crate is in the tree. Both ignores are removed in the same change: deny.toml now has ignore = [] with a comment saying why. cargo tree -i chrono, -i rsa and -i openidconnect print nothing, and cargo deny check passes (advisories, bans, licenses and sources).
Builds on ADR-951
Referenced by ADR-951
Link to this decision · In the specification
ADR-954 A replica reports how long it has been without its primary; primary_unreachable alerts on ita replica that can't reach its primary keeps answering DNS from its last copy (CLU-004), but nothing said so: node_down only sees a node that's disconnected from the primary's view, and a replica that still reaches other members (after falling back to one of them) looks healthy while it is split off.
Context
a replica that can't reach its primary keeps answering DNS from its last copy (CLU-004), but nothing said so: node_down only sees a node that's disconnected from the primary's view, and a replica that still reaches other members (after falling back to one of them) looks healthy while it is split off. Alerts are evaluated on the primary, so the primary has to learn the replica's view from the heartbeats it already receives (fork #2, T24.5).
Decision
- A replica's heartbeat carries
primary_silent_s(optionaluint64, tag 40; tag 39 is the primary flag of ADR-947): how long it has gone without a heartbeat from its primary, when that is more than theupwindow (three heartbeats, 15 s); absent when it reaches the primary, is the primary, or is an older node. It is computed from the heartbeats already exchanged, on the cluster task, never on the DNS path. Older nodes ignore the tag (CLU-010). - The cluster view carries it as
primarySilentSecondson each replica (its own value, or the peer's while the peer isup). - The alert condition
primary_unreachablefires for a replica whose silence is at least its rule'sthresholdin seconds (default 60; 15 to 86400), afterfor_secsas for every rule. One alert per replica; it clears when the replica reaches the primary again. Witnesses, resolver pods and nodes that aren'tupare left out; so are nodes in maintenance. - The health level adds a degraded reason
primary_unreachable(link#/cluster) for a replica silent for 60 s. The health icon uses the fixed 60 s, as ADR-104 fixes its thresholds; the alert'sthresholddoesn't change the icon. (Conservative choice: the health path has no access to the alert rules; making it follow the rule is a follow-up if the defaults don't fit.) - A replica that is disconnected from every member is
node_down, not this condition; a replica that reaches another member is the silent split this condition exists for. - Counting. The silence counts from the newest heartbeat this node has heard from any primary, kept after that primary leaves the member list, so a removed or replaced primary doesn't make a replica look silent since boot. Before any primary has been heard, it counts from this process's start: a replica that has never linked to a primary reports its uptime as the silence once that uptime passes 60 s. The alert and the health reason show this case as a plain
N swith no separate label; it is kept so that a replica that never linked is surfaced rather than hidden. (Conservative choice.) - Scope. The alert engine runs only on the primary, so a replica's silence reaches the alert through the heartbeats that replica sends to the primary or to a member that relays them. A replica's own silence is in its own view (health) and is not evaluated on the replica itself. A primary's own silence is not reported (it is the primary).
- Maintenance. Health and the alert both leave out a replica in a maintenance window (the health filter checks the node's maintenance field directly;
exclude_maintenancealso drops its reasons).
Consequences
one optional heartbeat field and one ClusterNode field; no new configuration key (the threshold is the rule's own). The UI shows the condition in the Alerts form (threshold, in seconds, is the field's help), the replica flag on the Cluster page with the primary-unreachable help topic, and the health reason. The timing is unit-tested at the boundary (obs_010_t24_5_*), and clu_004 is the Playwright test.
Requirements CLU-004 CLU-010
Link to this decision · In the specification
ADR-955 The Home Assistant source test: a throwaway Home Assistant in its own Compose project, seeded by a test fixtureT24.21 (fork #12).
Context
T24.21 (fork #12). The owner chose a test container, never the owner's Home Assistant. The bundle's test-ha profile (deploy/docker-desktop/compose.yaml) brings up its homeassistant service with depends_on: wrendns, so starting it from the bundle's project would also drive the running wrendns-dev container. Home Assistant's device registry has no REST or websocket call that gives a device a MAC connection, which is what WrenDNS reads (/api/template, device_attr(d, 'connections')).
Decision
- The container.
deploy/ha-test/compose.yamlis its own Compose project (wrendns-hatest), with the integration under test and a fixture mounted. It publishes on127.0.0.1only. The bundle'stest-haprofile stays as it is for manual use. - Onboarding and the token. The script onboards the owner over
/api/onboarding/*, exchanges the code, and makes a long-lived token over the websocket API (auth/long_lived_access_token) from inside the container. The token and the generated password go only to a file in a temporary directory that the trap removes; neither is printed. - Fake devices. A test-only fixture integration (
deploy/ha-test/fixtures/wrendns_seed, never shipped) creates devices with MAC connections and an entity each, through its config flow. Addresses come fromdevice_trackerstates set over REST, the states WrenDNS matches on. - The node. A WrenDNS build runs in a throwaway
ubuntu:24.04container on the same network. Its binary comes from a bind mount (CI) or from another container's volumes (the dev container). The integration's token is an agent token withanalytics:readandconfig:read. - Checks. The names, MACs and addresses the node reports (a device with no address is absent), the names over DNS, and the integration's sensors (
known_devices,health,problem,queries_24_h,version).
Alternatives rejected
- Starting the bundle's
test-haprofile. It would startwrendnsthroughdepends_on, which touches the running dev container. - Writing the device registry as a file before first start. It is undocumented for this purpose, and it breaks when the storage format changes.
- Using Home Assistant's demo integration. Its devices carry no MAC connections, so the template can't name them.
Consequences
the test needs a pulled Home Assistant image (about a few minutes on first run) and runs in CI as its own job (.github/workflows/home-assistant.yml, ha-test, 20 minutes). The fixture is a test-only integration that will need updating when Home Assistant changes its device or entity registry API.
Link to this decision · In the specification
ADR-956 Guarded changes: one framework for the settings that can lock an admin outADR-914 (Accepted) puts the security gates and bootstrap settings in a guarded tier with a dry run, a typed phrase, an audit record and, for addresses, a confirm-or-roll-back window.
Context
ADR-914 (Accepted) puts the security gates and bootstrap settings in a guarded tier with a dry run, a typed phrase, an audit record and, for addresses, a confirm-or-roll-back window. It names the pieces but not how they fit: where a guarded value is stored, how a restart interacts with a pending change, what a cluster does, or how the server proves a confirmation came through the new address. T27.14 to T27.17 each need the same machinery, so it is fixed once here, before any of them is built. The existing pieces it builds on: managed kinds and files-win (ADR-040, ADR-069, ADR-918), node_managed entries (T23.10, ADR-903 §6), agents' plans (ADR-070, in memory, replayed through REST), the live listener swap in server.rs reload (Listeners::apply), and the sign-in recency rule (T23.9, 10 minutes). Today there is no self-restart: a supervisor (systemd, Compose, Kubernetes) restarts the process, as for the watchdog (exit 70). The owner's decision of 2026-11-17 adds an explicit, supervised "Restart now" (section 4a); nothing restarts the node implicitly.
Decision
1. Which settings are guarded, and the mode of each. A registry in wrendns-config/src/guarded.rs lists every guarded setting once: id, the config paths it covers, scope (always node; see 5), mode, a pure weakens(old, new) -> bool, and the checks its dry run runs. A test fails if a path ADR-914 calls guarded is missing from it. The mode is how a change takes effect:
| Mode | Settings (id) | How it applies |
|---|---|---|
window | listen, api-address, api-tls, trusted-proxies | Applied live as pending, kept only if confirmed through the new address (section 3). |
immediate | secret-file-dirs, allow-secrets-over-http, allow-insecure-basic, watchdog, file-paths (trust_anchors_file, signatures_file, hosts_files, [[zone]] file) | Written, then applied by the same reload the API uses (a failed reload keeps the previous configuration, CLU-004). No window, because none of them can cut the admin off. Undone by the same form; the audit record holds the previous value. |
staged | secrets-key, node-identity (node.id), data-dir (node.data_dir) | Written as staged, applied at the next start (section 4). The server restarts only on the admin's explicit "Restart now" (section 4a), never by itself. |
action | cluster-init, cluster-join, cluster-leave, cluster-git, restart-now | An operation, not a value. Each has its own transactional steps (T27.16; restart-now is section 4a) but the same preview, phrase, audit and agent rules. |
Data directory (data-dir, staged) and the settings that stay file-only. (a) node.data_dir has a guarded control (owner decision 2026-11-17, which overrules the earlier "file-only" proposal; ADR-914's staged data directory stands, and ADR-914's sentence "never moves data" is reworded below: it moves data only when the admin opts into Copy state, and never cluster/). The danger is real: a new directory means an empty state.db, so every admin account and session is gone (setup_required reopens first-run setup, which anyone who can reach the API could complete), the cluster identity under <data_dir>/cluster/ is lost (a member returns as a fresh standalone node) and the default <data_dir>/secrets.key is regenerated with the stored secrets unreadable. So the control is conservative:
- Preview (checks on the node, nothing written; the same checks run again at apply and again at start, before anything is copied or opened, so a path swapped for a symlink between preview and start is caught:
api_902_data_dir_path_checks_rerun_at_apply): the new path is absolute, not a symlink (no component), not a path T23.2 denies, not equal to or inside the current directory (and the current one is not inside it), exists or can be created, and is writable by the node's user. Persistence: the node compares the target's mount with the current data directory's (/proc/self/mountinfoon Linux). A target on the container's writable layer, or on anemptyDir, while the current directory is on a separate volume, is a warning that the state is lost on recreate or reschedule;WRENDNS_DATA_EPHEMERALset is a refusal (409data_dir_not_persistent). A directory that already holds files shows which of the known files it has. The preview states in words: "Admin accounts, sessions, settings, the audit log, the cluster identity and the defaultsecrets.keystay in <old path>. They do not carry over unless you copy them. With nothing copied, the node starts with no admin accounts and reopens first-run setup." What does not carry over is generated from one const,DATA_DIR_FILESinwrendns-config(name, what it holds, whether Copy state copies it, whether it is safe to lose), which the preview, the help topic anddocs/recovery.mdall use, and a test fails if a file the node writes under<data_dir>is missing from it (api_902_data_dir_file_list_is_complete). It covers at least:state.db(accounts, sessions, settings, audit; copied),secrets.key(default key only; copied),rollups.db(history up to 400 days; not copied, starts empty),maintenance.json(an active maintenance window ends),cluster/includingapplied.json(identity; never copied, so the node starts without its cached cluster snapshot),watchdog/restarts(the restart-rate limit resets),runs.json,anomaly.json,devices.json,annotations.jsonl,sinks/*.spill(undelivered telemetry is dropped),snapshots/,logs/,setup-tokenandguarded-probation. It lists the commands to copy the rest by hand for the install (systemd, Compose volume, Kubernetes PVC;state.dbwith the node stopped or by the offlinewrendns state backup) and names what is not under the data directory (asecrets_key_fileelsewhere, certificates) as unaffected. - Optional copy (a checkbox, off by default,
copyState): when on, the copy is made at the start that applies the pointer, before any state is opened (the oldstate.dbis then closed, so a plain consistent copy, or SQLite's backup API, is exact). It therefore includes every write up to the restart (the change's ownsettings.guardedandsettings.guarded_restartrows, admins and sessions created in between, secret rows re-encrypted in between); nothing taken at apply time is used. It copies onlystate.dband, when the default<data_dir>/secrets.keyis in use, that key file (same mode, 0600, same owner, created withO_EXCL). It refuses (409target_not_emptyat preview and apply; at start the pointer is dropped) if the new directory already holds either, so it never overwrites. It never copiescluster/(a copy would duplicate the node's identity), the sidecar, logs or the query log. Copying a key file is a server-side file operation between two paths the preview named: no key material is in any request, response, log or audit row (API-014); the audit row, written after the copy into the old directory'sstate.db, lists file names only. If the copy fails part-way, the partial files are removed, the pointer is dropped and the node starts in the file's directory with auditsettings.guarded_rolled_back(failed_start). - Consent: the phrase as usual, plus, when the preview says the new directory will have no admin accounts (nothing copied, no
state.dbthere and no bootstrap admin, below), a second explicit acknowledgement (acknowledgeNoAdmins, 409acknowledgement_requiredwithout it). That case is weakening (first-run setup reopens), so the 10-minute sign-in applies. Bootstrap environment: whenWRENDNS_BOOTSTRAP_ADMIN_USERwith a password or hash is set (the "First admin" rule, applied only while no user exists), the new empty directory will get that admin at the first start, so the preview says "an admin named <name> will be created from the environment" (the name only, never the credential), the case is not "no admins" and is not weakening, and probation counts that account as the promised admin. - Where the pointer lives: the
data-direntry is local to the node and never replicated. It is written to, and read only from, thestate.dbof the directory the file names (or the default). Start-up reads it first, follows it one hop only, then opens the target for everything else; adata-direntry found inside the target is ignored with a warning. The sidecarguarded-probationalso stays in the file-named directory. The node holds the lock on both directories while it runs. Every other guarded entry lives in the active (target) directory'sstate.db. The old directory must therefore stay while the pointer is in use; the preview recommends making the move permanent by settingnode.data_dirin the file (and, for a Kubernetes install, mounting the volume there), and once the file names the new directory the pointer is ignored. A seconddata-dirchange is written to the file-named directory, where start-up reads it. - Target missing later: when the pointer is first applied the node records, in the pointer, an identifier of the target's
state.db(a random state id stored inside it at creation) at the first healthy start. After that the target must exist and hold astate.dbwith that id. If it is missing, empty or a different database (an unmounted USB disk on a Pi, a volume not mounted, a freshemptyDir), the node starts in the file-named directory with the health reasondata_dir_missingand an audit row, and never creates the target after the first start. Only the probation start (before the first healthy start) may create it (api_902_data_dir_missing_target_never_starts_fresh). - Probation:
data-diris healthy only when the newstate.dbopens, the API listener is bound, the DNS probe answers and, if the preview promised admin accounts (copied, already present, or from the bootstrap environment), at least one admin account exists (setup_requiredfalse). Otherwise two failed starts drop the pointer. An empty new directory the admin explicitly accepted is healthy. - One change at a time: a
stagedentry is refused (409guarded_change_pending) while another staged entry or a window change is pending on the node, sodata-diris never staged together withsecrets-keyornode-identity;data-diris refused whilesecrets_rotation_incompleteholds (409rotation_incomplete), because a copiedstate.dbwithoutsecrets_previous_key_filewould leave rows unreadable. Everycluster-*action is refused whiledata-diris staged or on probation. - Cluster: refused outright while the node is a cluster member (409
clustered_node); the supported path is to leave the cluster, move the data directory, then re-join (cluster-leave, T27.16). Nothing movescluster/, so a pointer can never strand or lose the cluster identity on rollback. - Weakening: only the no-admins case above.
(b) [auth.oidc] disable_local_login and allowed_admin_networks: each can lock every admin out, the case ADR-911's break-glass exists for, and a guarded change would need its own would_lock_out_admins dry run and recovery story; they stay in the file, shown read-only with this reason. A test (api_902_lockout_settings_are_file_only) fails if either appears in the registry; api_902_data_dir_is_guarded_and_staged fails if node.data_dir is missing from it or is not staged. Revisit (b) by a later ADR if the owner wants controls.
Why guarded at all: each is a setting that can lock every admin out (listeners, API address, TLS, proxies), put credentials on the wire or widen what a secret reference may read (the three allow/dirs settings), re-encrypt or lose the secret store (the key), or replace a node's configuration (cluster, identity, storage). watchdog and file-paths stay immediate (owner decision 2026-11-17). watchdog and file-paths are guarded because turning the watchdog off hides a hang, and a path lets the server read a file an admin names (T23.2's rules apply). config_version has no control (ADR-914).
2. Where a guarded value lives. In node_managed under the reserved kind guarded, one entry per node and setting (node/<node-id>/guarded/<id>), after T23.10. The generic managed-kind routes refuse that kind (409 guarded_only), so the only writer is the guarded module, after every check below. The file wins (ADR-040): a field the files set shows "set by file" with the path and an API write of it is 409 set_by_file. An entry is written only when the change is final (confirmed, applied, or staged), never while pending. The data-dir entry is the exception: it is local to the node and never replicated (see the data directory block). A backup restore brings the entries back and starts the node with them on probation (section 4).
3. The two-request flow and the confirmation window.
- Preview
POST /api/v1/guarded/{id}/previewwithnodeandvalue. It changes nothing and returnspreviewId, thephrase(<node-id> <id>, ADR-914), the effect in words, the nodes it reaches (always one),weakening,restartRequired,wouldDisconnect, the warnings (for example "the container's published ports are not changed", when the node sees it runs in Docker or Kubernetes) and the checks that failed. A preview is bound to the admin, node, setting, a hash of the value and the config version, and lives 5 minutes. A request with a changed value or version is 409preview_stale. - Apply
POST /api/v1/guarded/{id}withpreviewId,confirm(the phrase, compared by the server) and areason. The answer depends on the mode: 200applied(immediate), 202stagedwithpendingRestart(staged), 202pending(window) or the action's own (restart-now: 202restarting). - Window changes. One pending change per node (409
guarded_change_pendingotherwise). Until it is confirmed, a pendingtrusted-proxieslist applies only to the confirm route's own address evaluation; every other use (break-glassallowed_admin_networks, loopback-only checks, rate limits, the audit source address) keeps the old list, so a newly trusted host cannot spoofX-Forwarded-Forinto those checks during the window. The node validates, binds the new sockets next to the old ones (a failed bind changes nothing and reports why), starts the window ([api] confirm_window_secs, default 120, 30 to 600, file-only) and answers 202 withdeadlineSecs(the time left, measured on the node's monotonic clock, never a wall-clock time),confirmTokenand the new address. The token is single-use, bound to the admin, node and change, and valid for the window. The UI puts it in the URL fragment of the new address (never sent to a server or a log) so the admin need not sign in again on a new origin. - Confirm
POST /api/v1/guarded/pending/{id}/confirm, with the token or a session of the same admin. Each registry row has a proof hook that returns the kind of proof the confirming request must carry:new_socket(listen: the request or the node's own probe arrived on the new socket, and the node's probe of the new DNS listener answers;api-address: the request arrived on the new socket),new_cert(api-tls: the handshake used the new certificate) orproxy_list(trusted-proxies: the request passes under the new list and the confirm step shows the client address the server now sees; no socket changes). A TLS-only change on the same address and port has no new socket, so the preview names a temporary parallel listener port (proofPort) that serves the new certificate for the window only; confirm arrives there. A row with no proof hook is not awindowrow. On success the node writes theguardedentry (through the primary on a replica, see 5), closes the old sockets and audits. A failed write rolls back. - Roll back happens at expiry, on
POST .../cancel, when the commit fails, or when a bind fails: the new sockets close, the old ones were never touched, nothing was written, andsettings.guarded_rolled_backrecords the reason (expired,cancelled,commit_failed,bind_failed,failed_start). A wrong confirming request does not roll back (it is refused and counted); the window simply runs on. would_disconnect_you(409): a preview or apply that would leave the node with no API listener or no DNS listener once confirmed, or that removes the API listener the apply request itself came in on. Checked at preview and again at apply.- Recent sign-in and sessions. All guarded routes need an interactive admin session. An agent token (any scopes) gets 403
agent_not_allowed; any other API token gets 403reauth_requiredwith a hint naming the file or CLI step (ADR-914). A weakening change also needs a sign-in within 10 minutes (reauth_required; for OIDC the sign-in is repeated at the provider withmax_age=0), checked at apply. Failed confirmations (wrong phrase, wrong token) count: 5 in 10 minutes block guarded requests from that session (429). - Secrets in a request (
cluster-join's bootstrap secret) follow the API-015 rule: HTTPS or loopback, write-only, never stored, never in the audit record, never in a preview.
4. A change that needs a restart. A staged entry is written to state.db immediately (it survives the restart that applies it) and listed by GET /api/v1/guarded as pendingRestart, shown "pending restart" with the way to restart for the install (systemd, Compose, Kubernetes) and, where section 4a allows it, a "Restart now" button. The server never restarts on its own; an admin, a supervisor or the explicit action does. Start-up reads staged entries from the state.db in the data directory that the file names (or the default); the data-dir pointer is followed one hop and nothing else is read from the target before that. One staged change at a time per node (409 guarded_change_pending, also while a window change is pending). A staged value that the file also sets is refused at preview ("set by file"). Probation: a node that starts with a staged or restored guarded entry marks it on probation. Counter: a small sidecar file <data_dir>/guarded-probation (mode 0600), not state.db (the failure may be that state.db will not open). Before any guarded value is applied at start-up the node writes the attempt count and the entry ids to it with an fsync and a rename; it deletes the file when the node is healthy. A start that finds the count at 2 drops the listed entries (written as dropped to state.db when it opens, and audited settings.guarded_rolled_back, failed_start) and starts from the file. A power loss counts as a failed start. Healthy is: the state opens, the API listener is bound, the node's own DNS probe answers, and (when the entry is secrets-key) the store is unlocked (!secrets_locked), within max(confirm_window_secs, 180) seconds (a constant floor, so a slow Pi compiling a large filter is not rolled back; a window setting of 30 does not shorten it). If the process exits or the watchdog fires first, twice in a row, the entries are dropped. Re-encryption: once any row has been re-encrypted under a new secrets key, dropping the entry must not return the node to the old key alone: the fallback keeps both paths (the new key as secrets_previous_key_file, so every row opens) and reports secrets_rotation_incomplete. Confirmed entries: a confirmed window entry (a listen or api-address on an interface that is not up yet at boot, a DHCP or VLAN address) also gets start-up protection: a bind failure for a guarded listener falls back, for that start only, to the file or previous value, with the health reason guarded_bind_fallback and audit failed_start, so the node never crash-loops on a missing address. The entry stays and is tried again on the next start. A restart inside a window change starts with the previous values: the pending change was in memory only (which is why restart-now is refused while one is pending, 4a).
4a. Restart now (restart-now, action). Owner decision 2026-11-17: a guarded change that needs a restart may offer "Restart now", but only where something will start the process again. The node never guesses: it exits only when it has a supervisor and the admin asks.
- Detection. At start the node computes
supervisoronce, from the environment only (no new config field), and only from a declaration:WRENDNS_SUPERVISOR=systemd|docker|kubernetes|none, set by the shipped systemd unit, Compose bundles and Helm chart (nonealways turns the action off). Nothing is guessed fromINVOCATION_ID,JOURNAL_STREAM,NOTIFY_SOCKETorKUBERNETES_SERVICE_HOST: those are inherited by every child of a service (a terminal on a desktop, tmux undersystemd --user, a CI runner), so detection would offer a button that exits a node nobody restarts (review 2026-11-17). A baredocker run, a hand-made unit or a pod without the variable has no supervisor. In every case the node cannot see the unit'sRestart=line or the pod's owner, so a custom unit withRestart=no, a bare pod or a Job would stay down: the preview and the confirmation say "the node cannot check that your <supervisor> will start it again; if it does not, start it by hand", and the shipped unit, bundles and chart are the supported case. No supervisor means no button: the UI shows the manual steps, and the route answers 409no_supervisor.GET /api/v1/guardedlistssupervisor(kind and how it was found, ornone) for each node. - Flow.
restart-nowis a registry row of modeactionwith no config path, using the same two requests: preview (POST /api/v1/guarded/restart-now/previewwithnode; it lists the staged entries the restart will apply, the dropped-if-unhealthy rule, the expected outage in seconds, and for a cluster node what else it affects) and apply with its own phrase<node-id> restartand a reason. It needs an interactive admin session with a sign-in in the last 10 minutes (a restart is an outage, not a weakening, but a stolen session should not be able to bounce DNS); operator, viewer and every token get the refusals of section 3. Agents and MCP are refused (403agent_not_allowed, no tool, no plan, no scope; the registry-against-catalog test covers it). It is rate-limited with the guarded limiter, and 5 failed phrases block the session as in section 3. - Mechanism. Acceptance takes the node's guarded-operation lock atomically with the pending check and the audit write; while it is held every guarded route (preview, apply, confirm, cancel,
cluster-*) answers 409restarting, and a restart is refused (409guarded_change_pending) while a window change, acluster-joinor another guarded operation holds it (api_902_restart_excludes_other_guarded_operations). After the checks the node audits, then drains (stops accepting new work, finishes in-flight queries up to a 5-second cap, flushes the state) and exits with code 75. A non-zero code is deliberate: systemdRestart=on-failureand Dockeron-failurerestart on it, andalwaysand Kubernetes do either way. It is a normal shutdown path, not a crash: the watchdog's exit 70 andfailed_startcounting are separate, and the probation counter is incremented by the start that follows (section 4), not by the exit. - Audit and alert.
settings.guarded_restart(node, supervisor kind, the staged entry ids waiting, reason, actor, session, source address) is written before the exit, and the alert conditionguarded_setting_changedfires with outcomerestarting. A refusal (no_supervisor, a bad phrase, a pending window) issettings.guarded_refused. If the audit row cannot be written the restart is refused. - Interaction with the rollback window. Refused while a
windowchange is pending on the node (409guarded_change_pending): a restart inside the window would drop the pending change from memory and, for an admin watching the countdown, look like a failure. Confirm or cancel it first. The restart has no countdown of its own; what protects astagedchange is probation (above). The UI shows "restarting", waits for the node (polling the unauthenticated health endpoint, listing the staged entries) and, once it answers, showsappliedorrolled back (failed_start)with the reason. If the node does not answer withinmax(confirm_window_secs, 180)seconds for each of the two start attempts, the UI says so and linksguarded-recovery(the file, the CLI,WRENDNS_IGNORE_GUARDED). The session survives the restart because sessions live instate.db, unlessdata-dirmoved to an empty directory, in which case the admin lands on setup. - Cluster. Node-local like every guarded action: a restart of node X is previewed and confirmed for X only; there is no "restart all" and no rolling restart. Only the primary forwards it, with the same signed single-use assertion as section 5 (the assertion names the action; a replica's signature is refused;
api_902_forwarded_restart_from_replica_refused), and X checks its own supervisor, phrase and recency. The preview warns when X is the primary (writes and config changes pause until it is back; replicas keep answering DNS from their snapshot, CLU-004) and when X is the only healthy resolver in its site by the cluster health view. A replica whose primary is unreachable may still be restarted: the staged entries are already in itsstate.db. - Failure. If the drain does not finish within the cap the process exits anyway. DNS answers until the drain begins (CLU-004); nothing on the query path changes.
5. Clusters. (Owner decision 2026-11-17: only the primary forwards, accepted as written.) Every guarded setting is node-local: a change to one node never reaches another, and there is no "all nodes" apply (each node needs its own preview and phrase). cluster-git is the one cluster-wide setting; it is held by the primary and replicated like the other authority settings. Only the primary forwards a request for node X (ADR-914: "the primary forwards"; a replica that receives one answers 421 with the primary's URL and the UI sends it there). The request travels over the existing cluster channel (the ADR-946 pattern) with an assertion of the admin's identity, role and sign-in time, signed by the primary's cluster key, short-lived and single-use (it carries a nonce bound to the previewId, the node and the action; X keeps the used nonces for the assertion's lifetime and refuses a replay, api_902_forwarded_restart_assertion_single_use), which X checks itself; the forwarding node's own checks do not stand in for X's. X cannot see the admin's session, so it accepts the assertion only from the primary (the one member that already signs everything X trusts, ADR-005); a replica's signature on one is refused (test api_902_forwarded_immediate_change_from_replica_refused), so a compromised replica (other than a CA-holding one, see ADR-977 point 5) cannot turn on allow-secrets-over-http or widen secret-file-dirs on another node. A compromised primary can, as it can already replace that node's configuration. The pending change is held on X, and the confirmation must reach X's new address directly (the admin's browser, not the primary, so a primary can't confirm for the admin). Writing the entry goes through the primary (single writer, ADR-005): if X cannot reach the primary when the admin confirms, the confirmation is refused (409 primary_unreachable) and the window runs out and rolls back, so a node never runs a guarded value that no one will replicate. A standalone node or the primary writes locally. A target below the version that supports the kind ignores it (clu_010) and the preview says so. DNS keeps answering throughout (CLU-004): a forwarding or replication failure only fails the change.
6. Audit and alerts. settings.guarded once when a change is final (setting, node, mode, before and after with credentials redacted, reason, actor, session or break-glass, source address). settings.guarded_rolled_back with the reason code above. settings.guarded_refused (new) for a refused attempt past the role check: bad phrase, stale preview, would_disconnect_you, reauth_required, no_supervisor; it carries no values. settings.guarded_restart (new) for an accepted "Restart now" (4a). The alert condition guarded_setting_changed fires when a change is applied or staged and again on its outcome (confirmed, rolled_back), so a second channel sees a change an attacker with an admin session makes. Previews are not audited, but are rate-limited with the same limiter as writes.
7. Agents and MCP. Refused, not plan-only. Agent tokens get 403 agent_not_allowed on preview, apply, confirm and cancel; no plan_* tool exists, no config:write:* scope reaches a guarded setting, and ADR-070's plan store refuses guarded paths, so apply_plan can't replay one. get_config shows the settings redacted as before; GET /api/v1/guarded (what is set by file, what is pending) needs only config:read, and never returns a previewId, confirmToken or a pending value (only that a change is pending, its setting and its deadline); api_902_listing_has_no_secrets_or_pending_values checks it with an agent token. A test walks the registry against the MCP catalog and the plan tools and fails if one is reachable. This follows spec/13 §3.
8. Failure and recovery. The file always wins, and ADR-957 adds the CLI and environment escape hatches. Inside the framework: a failed bind, validation or reload changes nothing; an expired window restores the previous values; a restart inside the window starts with the previous values; a bad staged value is dropped after two failed starts.
9. UI. One GuardedChange component takes the setting's form and the registry entry and shows, in order: the preview (effect, nodes, warnings, a red "weakens security" mark), the phrase to type (paste is allowed; the server checks it), and then by mode the result: applied, "pending restart" with the restart steps (and a "Restart now" button when the node reports a supervisor, with its own preview, phrase and a plain note that the node cannot check that the supervisor restarts it), or the countdown (a bar driven by deadlineSecs from the server, not the browser clock; Confirm, Cancel, and the link to the new address that carries the token). On the new address the page opens on the confirm step, and a rolled-back change shows its reason on the old address. A weakening change shows the sign-in prompt first. ? topic guarded-settings.
10. Test plan.
- Unit: the registry covers every guarded path;
weakensis table-driven for every case in ADR-914; the phrase and preview binding; the window state machine undertokio::time::pause(expiry, cancel, double confirm, token reuse, wrong admin); the probation counter. - Integration (in-process node): binds before release and keeps the old sockets until confirm; a bad bind and a bad reload change nothing; DNS answers all through (a UDP query in a loop); restart inside the window; every guarded route rejects an agent token, any other token, a viewer and an operator (table-driven over the registry); the generic kind routes refuse
guarded; the plan store and MCP catalog hold no guarded path; audit rows and the alert event. - Cluster (two nodes): forwarding with the signed assertion (a forged or stale assertion is refused), confirm directly at the target,
primary_unreachable, N−1 ignores the entry. - Playwright (e2e server on two ports, T24.19's offsets): phrase required, countdown and rollback, move the API port and confirm from the new address, a weakening change asks for sign-in, set-by-file lock, operator and viewer see no controls.
- Review additions:
api_902_forwarded_immediate_change_from_replica_refused;api_902_probation_after_partial_reencrypt_keeps_both_keys;api_902_probation_counter_survives_unopenable_state(the sidecar);api_902_confirmed_listener_bind_failure_falls_back_at_start;api_902_pending_proxy_list_not_used_for_break_glass;api_902_lockout_settings_are_file_only;api_902_listing_has_no_secrets_or_pending_values;api_902_test_row_absent_in_release(the test-only rows compile only under the cargo featuree2e, never behind an environment variable alone). - Restart now:
api_902_restart_now_needs_a_supervisor(the detection table over environment combinations, thenoneoverride, Docker declared),api_902_restart_now_refuses_agents_and_tokens,api_902_restart_now_own_phrase_and_audit(the audit row is written before the exit; no audit, no restart),api_902_restart_refused_while_window_pending,api_902_forwarded_restart_from_replica_refused,api_902_restart_exits_75_after_drain(a test hook replaces the exit). - Data directory:
api_902_data_dir_preview_lists_what_does_not_carry_over,api_902_data_dir_copy_is_optional_and_never_overwrites,api_902_data_dir_copy_never_copies_cluster_identity,api_902_data_dir_no_admins_needs_acknowledgement_and_sign_in,api_902_data_dir_pointer_read_before_state_opens,api_902_data_dir_probation_needs_admins_when_promised. - Not tested here: real systemd, Docker or Kubernetes restarts (documented, covered by the deploy checks).
Alternatives rejected
- One window for every guarded setting: the
immediateones cannot cut the admin off, and a countdown on them trains people to click through. - Staging address changes for a restart: the same lockout without the rollback, and a restart outside the window.
- A dead-man timer that needs only time to pass (apply, then keep unless an admin cancels): a locked-out admin cannot cancel.
- An implicit or automatic server-side restart: a crash loop on a bad value would have no way back. (An explicit, confirmed, audited "Restart now" only under a supervisor is accepted, 4a.)
- Detecting Docker's restart policy from inside: not visible, so the bundle declares it (
WRENDNS_SUPERVISOR). - Copying
cluster/with the data directory: it duplicates a member's identity. - Always copying state to a new data directory: it copies a live database and a key by default; it is opt-in.
- Reusing agents' plans: plans replay REST writes with the agent's credentials and keep the diff in the approval inbox and transcript, which is what ADR-914 keeps away from agents.
- Letting the primary confirm for a remote node: the check exists to prove the admin can reach that node.
Consequences
- T27.14 to T27.17 only add a registry row, a dry-run check and an apply step each; the routes, state machine, audit and UI shell are T27.13.
- Needs T23.9 (recency) and T23.10 (
node_managed) first; T27.13 records this and does not build either. - Adds problem codes
guarded_only,guarded_change_pending,preview_staleandprimary_unreachable(with ADR-914'swould_disconnect_you,would_lock_out_admins,agent_not_allowedandreauth_required), the audit actionsettings.guarded_refused, and routes under/api/v1/guarded(in the OpenAPI, none in MCP). Listenersgains stage, commit and abort (T27.14); the API server needs the same for its own sockets. Both arewrendns-netandwrendnscode and needmake bench-smoke.- A guarded request on a node that is itself failing may be refused; the CLI and file remain.
- Amends ADR-914 in one place (only the primary forwards), recorded here because ADR-914 is Accepted; the owner accepted it 2026-11-17. The data directory stays staged, as ADR-914 says, and ADR-914's "never moves data" is reworded (ADR-914 section on
node.*): the opt-in Copy state movesstate.dband the defaultsecrets.key, nevercluster/. - Adds problem codes
no_supervisor,target_not_empty,acknowledgement_required,clustered_node,restarting,rotation_incompleteanddata_dir_not_persistent, the health reasondata_dir_missing, the audit actionsettings.guarded_restart, the environment variableWRENDNS_SUPERVISOR(set by the shipped bundles, unit and chart) and the exit code 75. watchdogandfile-pathsareimmediate(owner decision); a later ADR could move them towindow.
Requirements API-014 API-015 CLU-004
Builds on ADR-005 ADR-040 ADR-069 ADR-070 ADR-903 ADR-911 ADR-914 ADR-918 ADR-946 ADR-957 ADR-977
Referenced by ADR-1006 ADR-1053 ADR-914 ADR-957 ADR-977 ADR-978 ADR-993
Link to this decision · In the specification
ADR-957 Lockout recovery for guarded settings: the file, an offline CLI and a start-up switchADR-956's window protects an admin who is still at the UI.
Context
ADR-956's window protects an admin who is still at the UI. It does not help when a confirmed value is wrong in a way found later (a certificate that expires, a proxy list that hides every client), when the primary is gone, or when no admin can sign in. ADR-914 says only "a node can always be recovered by editing its file and restarting". In a container the file is often a read-only ConfigMap, and a guarded entry lives in state.db, which the file cannot override unless it sets the same field.
Decision
- The file wins, always. A guarded entry never overrides a field a file sets (ADR-040). Setting the field in the file and restarting is the first recovery, and the UI says so on every guarded form.
- Offline CLI (no UI: it is inherently offline, and the owner of the data directory runs it).
wrendns guarded list -c <file>prints each guarded entry on the node (staged, probation, active, including thedata-dirpointer),wrendns guarded clear <id>|--all -c <file>removes entries, and both openstate.dbdirectly, so the node must be stopped: thedata-dirpointer is read and cleared in the file-named directory'sstate.db, every other entry in the active (target) directory's, and the command refuses if the node holds the lock on either. A clear is audited instate.dbwith the actorcli:<os user>, and the command prints what the node will use afterward (the file's values or the defaults), then says to restart. In a cluster it clears only that node's entries. A replica cannot publish a removal (ADR-005: the primary is the single writer, and it still holdsnode/<id>/guarded/<setting>and replicates it back), so a clear is also recorded locally as suppressed until the primary's copy changes: the node ignores that entry's replicated value while the primary's copy is the same one (compared by hash), logs the suppression at warn level and shows it in the UI andguarded list. On reconnect the node sends the primary a removal request authenticated by an offline-CLI token the clear wrote tostate.db(single-use, bound to the node and entry, signed with the node's cluster key); the primary deletes the entry, and the suppression ends when the primary's copy is gone or changed. If the primary refuses, the suppression stays and the node says so. - Start-up switch.
WRENDNS_IGNORE_GUARDED=1makes the node start with every guarded entry ignored (not deleted), for places where running the CLI offline is awkward (Kubernetes: set the variable, let the pod restart). The node logs it at warn level, reports the health reasonguarded_ignoredand shows it in the UI until the variable is removed. It never ignores the file. It ignores adata-dirpointer too, so the node starts in the directory the file names. - Probation (ADR-956 §4) is the automatic form: two failed starts drop the staged or restored entries.
- Docs.
docs/recovery.mdlists each symptom (cannot reach the UI after an address change, no DNS after a listener change, cannot sign in behind a proxy, store locked after a key change, a node that will not join, no admin accounts after a data directory move, a "Restart now" that did not bring the node back because nothing restarts it) with its fix, for systemd, Compose and Kubernetes, and every guarded form links to it. Help topicguarded-recovery. - Tests:
api_902_cli_clear_removes_entries_and_audits,api_902_cli_refuses_while_node_runs,api_902_ignore_env_starts_from_file,api_902_staged_entry_probation_drops_after_two_failed_starts,api_902_cli_clear_survives_resync,api_902_cli_clear_data_dir_pointer,api_902_ignore_env_ignores_data_dir_pointer, and a docs check that every guarded id appears indocs/recovery.md.
Alternatives rejected
an API or UI "reset guarded settings" (the UI may be the thing that is unreachable); an unauthenticated local socket (a second attack surface for the same goal); deleting entries on WRENDNS_IGNORE_GUARDED (a typo in the variable would destroy the state it was meant to protect).
Consequences
A new guarded subcommand and one environment variable, both documented in docs/recovery.md; a health reason guarded_ignored (with a UI link); the CLI/env tests join T27.13.
Builds on ADR-005 ADR-040 ADR-914 ADR-956
Referenced by ADR-914 ADR-956 ADR-977 ADR-978
Link to this decision · In the specification
ADR-958 The live network map: a sampled, bounded window on the aggregator thread, SVG drawn from a rate snapshotM26 (fork #14, OBS-901, OBS-902).
Context
M26 (fork #14, OBS-901, OBS-902). The owner wants an animated map of the network (gateway, networks and VLANs, devices, WrenDNS nodes, upstreams) and of where answers point, coloured green, yellow or red, built on existing data, with nothing added to the DNS path (02 §3, CLU-004), the UI inside its 400 KiB budget, and every control in the UI. This ADR fixes the design the M26 tasks build. The GeoIP database is ADR-959. Facts checked in the code: the aggregator thread already drains the worker rings and fans out to subscribers (live tail, sinks) through bounded queues, after the exclusions and the privacy level have been applied (ADR-102); QueryEvent carries client, group, status, rcode, upstream, t_total_us and answers (a count), but no answer address; ADR-132's flow counters are per minute and have no per-device joint; the health level (ADR-104) and the SLO ([slo] latency_ms) exist; GET /api/v1/networks and the device identities give the networks and names; M25's switch and port data is not built yet.
Decision
- Data model. A snapshot is
nodesandedges, all derived, none stored.- Node kinds:
gateway(one; the router integration's status),network(a VLAN or subnet from/api/v1/networks, else the groups' networks, else oneother),device(a client address with its inventory name, ADR-901/910),resolver(one per WrenDNS node, including resolver pods),answer(three terminal kinds per resolver:cache,local,blocked),upstream, and in the world viewregion(a country, ADR-959) plus an optional marker per geolocatable upstream. - An edge
from → tohasqps(a 60 s window),count,slowPct,errPct,blockedPctand ahealth. Edges: device → resolver, resolver → upstream, resolver → each answer kind; network and gateway edges are structural (no rate). A node carrieshealth,reasons[](stablecode,summary, as ADR-104) andqps. - Bounds: at most 200 device nodes drawn per snapshot (the busiest; the rest fold into one
+N morenode per network), 2,048 edges, 64 regions.truncated: truesays so.
- Node kinds:
- Where it is computed. A map sampler is one more subscriber of the aggregator thread's fan-out, but fed from the post-privacy stage next to the in-memory analytics, not from the tail: ADR-102 has the aggregator apply the privacy level once (
Hub::set_privacy) before the analytics see an event, while the tail and sinks apply the level themselves, so they are pre-privacy paths. The sampler therefore never sees a client key the level hides and has no filter of its own to get wrong. It costs the DNS path nothing: no new ring, no new counter, no lock a worker takes.- Sampling. Every ~250 ms it takes the events queued for it and keeps at most
event_rate / 4of them. The selector is counter-based (every Nth event, N from the previous tick's rate, with a carried remainder), so it is deterministic and testable, and each kept event is weighted by N. A snapshot'ssampleRatesays how thin the counters are. - Drops. The subscriber queue is bounded. Events it cannot accept are counted (a plain counter on the aggregator side) and added to the tick's total before N is computed and to the weights, so an overflow thins the sample but does not bias it down; a snapshot with drops reports
droppedand the UI shows "sampled" with it. A rare failure can still be missed under overload; that is the stated limit of an estimate. min_samplecounts real events. Theidleand confidence checks (section 4) use the unweighted sampled count (events actually kept), never the weighted one, so one kept SERVFAIL at N = 50 is one event, not fifty.- Window and memory. 12 slots of 5 s (60 s) of counters keyed by (device, resolver, answer kind, upstream). One entry is a 16-byte client key, two
u16ids, a kind byte, and fiveu32fields (sampled count, weighted count, slow, error, blocked): about 48 bytes, about 80 bytes with hash-map overhead. A slot holds at most 1,024 keys (the rest count underother), so the counters are at most 12 x 1,024 x 80 B, about 960 KiB in the worst case, capped explicitly at 1 MiB in total (a flood stops adding entries at the cap). A ring of the last 20 sampled lookups for each of the 64 busiest edges adds about 40 KiB. T26.2 measures the RSS delta under the Pi profile (one run at idle, one after the key cap is hit by a flood of distinct devices, steady for 5 minutes) and the Done note records both; the gate is a delta of at most 1.5 MiB at the cap, and a result above it changes the key cap, not the gate.event_ratedefaults to 200 per second per node (10 to 2,000). With[map] enabled = falsethe sampler isn't subscribed and the routes answer404 map_disabled.
- Sampling. Every ~250 ms it takes the events queued for it and keeps at most
- Nothing on the hot path. The only worker-side change allowed is the answer address for the world view (OBS-902): a 17-byte
answer: Option<Addr>the worker copies from the cache entry (computed when the entry is inserted, on the miss path, never parsed on a hit) into the event. It ships only if the ring record does not grow andmake bench-smokeis within its noise band (see the test plan). The record isRecord, aQueryEventor anUpstreamEventby value with an inline name of up to 255 bytes in the query variant, so the slot is set by the larger variant: T26.2 step 1 recordssize_of::<Record>()andsize_of::<QueryEvent>()before and after in its Done note (asize_ofassertion test pins them), and the keep-or-drop decision is made on those numbers. Otherwise T26.5 ships with upstream markers only, labelled as the upstreams' location and not where answers point (step 1 of T26.2). Blocked and local answers carry no address (they are synthesized). - Health classification (one pure function, table-tested; thresholds in
[map], defaults from ADR-104 and[slo]):- A device, edge or upstream with fewer than
min_sample(default 20) sampled (unweighted) answers in the window isidle(grey; not a health state). - Red: SERVFAIL or timeout share ≥
error_pct(25, ADR-104's severe line); an upstream whose breaker is open; a resolver that is unreachable (a cluster peer missing from the read) or not serving. - Yellow: SERVFAIL share ≥
warn_error_pct(5); slow share (answers overwarn_latency_ms, default[slo] latency_ms) ≥warn_slow_pct(10); a breaker half-open; any rate-limited query from a device; a device's blocked share ≥warn_blocked_pct(60, devices only); a device with an open unacknowledged anomaly finding (only when the privacy level is 0 and the engine is on, ADR-102); the gateway when its router integration reports an error. - Green: none of those. A network or resolver node takes the worst of its children, plus its own ADR-104 level for a resolver (severe → red, degraded → yellow); it shows "n red, m yellow".
- Structural nodes. The gateway is green when its router integration is healthy, yellow on an error (above), and grey (
idle, reasonnot_configured) when there is no integration; it is never red, because the DNS path does not depend on it. Anetworknode takes the worst of its devices (grey when none has enough samples). Ananswernode (cache,local,blocked) takes the slow share of its edge and is never red from the blocked share (blocking is the intended outcome). The classification table and its tests cover each of these. - Colour is never alone: the shape and the words change too (circle ✓, triangle !, octagon ×, as ADR-104).
- Settings are the shared section
[map](enabled,event_rate,min_sample,warn_latency_ms,warn_slow_pct,warn_error_pct,error_pct,warn_blocked_pct;[map.geoip]is ADR-959), a one-of kind like[exclusions]:GET/PUT/DELETE /api/v1/map-settings/default, scopeconfig:write:map, MCPplan_set_map, Settings → Monitoring. Operators change thresholds and the rate; the GeoIP controls are admin-only. A GitOps authority refuses the write and shows the TOML (ADR-914). Out-of-range values are422with the field named.
- A device, edge or upstream with fewer than
- API (viewer reads; all in OpenAPI; errors as problem+json):
GET /api/v1/map: the snapshot above, withgeneratedAt,windowSecs,sampleRate,privacy(the strictest level in force),truncated,partial,missingNodes. Optional filtersnetwork,group,device,nodenarrow it on the server.GET /api/v1/map/stream: SSE, onesnapshotevent every 2 s (the same body) and apingevery 15 s. One shared ticker builds one unfiltered snapshot for all subscribers and stops when none remain; thenetwork,group,deviceandnodefilters apply toGET /api/v1/maponly, and the UI filters the stream's snapshot client-side (a view keeps its URL filters either way); at most 8 subscribers per node (429 map_streams_busy). The UI closes the stream when the tab is hidden. Pulses are not per-event: the UI derives them from each edge's rate (below), so the stream stays small and a peer node's flows animate like local ones.GET /api/v1/map/world:{available, reason?, updatedAt, regions[{cc, name, qps, count, slowPct, health}], markers[], unlocated{count, reason}};available: falsewithreasongeoip_off,geoip_missingoraddress_not_recordedwhen it cannot be drawn.- MCP read tool
network_health(scoperead:stats): counts by health, the red and yellow nodes with their reasons (at most 50), and the five busiest flows; no device names at privacy level 2 or above.
- Cluster. Every node samples its own events. The answering node gathers each full member's local map by the federated read (ADR-104's 2 s deadline, run through
blocking()as ADR-946 requires). A ticker never waits on a peer: a separate gather task polls each peer on its own schedule with that deadline and keeps a per-peer last-good result with its age; the snapshot builder only reads those, and a peer whose last-good result is older than 3 intervals (6 s) counts as missing and setspartial. One dead peer costs at most one blocked pool thread per interval and never stalls the stream, sums the weighted counts of the same edge, merges a device that asked several nodes by its client key, and lists each node as its ownresolver; a node that does not answer is a redresolverwith reasonunreachableand appears inmissingNodes. Resolver pods are included. For the world view a node returns its top 256 answer prefixes (/24 for IPv4, /48 for IPv6) with counts, and the answering node resolves countries, so only nodes that serve the UI need the database. - Privacy (ADR-102). The privacy level is one global setting (
telemetry.qlog.privacy_level), applied once by the aggregator before the sampler sees an event (section 2). The map follows the same rule as the discovery feature, which refuses to enable at level 2 and above, and the rest is simple. Level 0 and 1: devices are shown by address and inventory name (clients are not hidden at 1); no domain name appears anywhere in the map, and the click-through to queries follows the level's own rules (hashed at 1). Level 2: devices are not shown; the sampler receives no client key (a test asserts it, not only that the output hides it), so each network has onedevicenode named "devices hidden by privacy", with no click-through, and flows are per resolver, upstream and answer kind. Level 3: no per-event data, so the map shows network and resolver totals from the counters only, and the world view counts everything as unlocated, reasonprivacy. Anomaly-based yellow is off at level 1 and above. The snapshot'sprivacyfield (the level in force) lets the UI say why a part is missing. The MCPnetwork_healthtool (scoperead:stats) returns device names at levels 0 and 1, as ADR-102 allows; the tool's description says so and the tool is in theobs_901_rolestest. - Rendering. Inline SVG, no graph or map library, a deterministic layered layout in TypeScript (columns: gateway and networks, devices, resolvers and answer kinds, upstreams; devices ordered by network then rate; no force simulation). Canvas was rejected: the DOM is what Playwright and screen readers can read. World view: an equirectangular dot grid from a 1-bit land mask (about 2 KB) with country centroids (about 6 KB), no remote tiles, fonts or scripts (CSP
connect-src 'self'); a remote tile source is not offered. The 400 KiB budget (ui/scripts/postbuild.mjs) is for every file indist/together, lazy chunks included, and that is also what lands in the image (ADR-916). So the rule is: the map chunk, with its data, is at most 30 KiB gzipped and the build's total stays at most 400 KiB. T26.3 records thedistgzip total (the postbuild summary) before and after in its Done note, and the world data (land mask, centroids, country names) is a separate file whose own gzip size is recorded (target at most 12 KiB) and counts in the chunk. At most 150 edges animate (the busiest), and on a small host (the Pi profile, ornavigator.hardwareConcurrencyof 4 or fewer) at most 60; the rest are drawn static. A Playwright check animates 150 edges and asserts a median frame time under 33 ms in the e2e browser (a documented noise band, not a Pi measurement). - Animation and accessibility. A pulse is a CSS-animated dash along an edge: density from the edge's
qps(1 dash per ~0.5 qps, at most 6 per edge), width fromlog(qps), colour and shape fromhealth, with a seed per edge so a refresh does not restart it. It runs onanimation-play-state, set topausedwhendocument.hiddenand when the user pauses it. Withprefers-reduced-motion: reducenothing moves: the dashes are static, the rate is a label on the edge, and no control turns motion back on. An always-available table view (<table>: from, to, qps, share slow, share failing, health in words) is the accessible equivalent; the SVG sits in arole="group"(afigure) with anaria-labeland a text summary, notrole="img"(that makes its children presentational, so the node buttons would not be exposed); each node is a focusablerole="button"with anaria-labelthat gives its state in words, Tab reaches it and Enter opens its panel, and a Playwright keyboard test covers it. Colours pass WCAG AA in both themes (NFR-008). - Interaction. A node click opens a side panel with its numbers and links: a device → Queries filtered to it, Explain, Anomalies for it, its device page; an upstream → Upstreams; a resolver → Cluster; a network → Networks. Filters (network, group, device search, node, health) are in the URL so a view can be linked; they narrow the server read (
network,group,device,node) as well as the drawing. - Choices made where the issue left room (the most conservative; the owner can overrule): a fixed 60 s window and 2 s refresh; the world view places upstreams (markers) as well as answers, as a toggleable layer (answering the issue's open question); arcs start at a marker "Your network" below the map unless
[map.geoip] home_countryis set; errors have no address, so a region's colour comes from the slow share, and failed lookups are counted as "no location" rather than drawn; M25's switch and port data is drawn as a device's parent only when the inventory already carries it (a conditional step of T26.3, not a blocker).
Test plan. Unit: the classification, table-driven at every boundary (min_sample, each threshold, half-open, rate-limited, anomaly, rollup, privacy collapse); the sampler is unbiased (a synthetic stream at 5x the cap, with the counter-based selector, so the run is deterministic; each edge's estimate is within 5%), unbiased under overload (a queue forced to drop a share of the stream still estimates within 5% because drops are counted), bounded (a flood of distinct devices stays at the 1 MiB entry cap and counts other), idle with no events, and a single sampled SERVFAIL with N >= 20 is not red (min_sample on real events); obs_901_privacy_levels asserts that no client key reaches sampler state at levels 2 and 3; the cluster merge (same edge on two nodes, a device on both, a missing node). API: OpenAPI, MCP and schema snapshots regenerated; the federated read with a dead peer; roles (viewer reads, operator thresholds, admin GeoIP); the 429 on a ninth stream; the ticker stops at zero subscribers; a dead peer does not delay a tick (the interval stays 2 s with partial set). Performance: make bench-smoke shows no regression; the aggregator-throughput check is an A/B of 7 alternating runs (sampler on, off) compared by their medians, passing when the on-median is within 5% of the off-median (the noise band of this harness; the measured run-to-run spread is recorded with the result, and the gate does not claim a 2% resolution the harness lacks); the RSS delta is measured as in section 2 (at most 1.5 MiB at the key cap, Pi profile); the animation frame-time check of section 8. Playwright (the e2e server has no real traffic, so snapshot answers are mocked with page.route, plus one run on the node's own queries): layout, keyboard (Tab to a node, Enter opens the panel), each colour state with its shape and words, filters, click-through, the table view, reducedMotion: 'reduce' (no running animation), a hidden tab (animations paused, the stream closed), the "off" and "needs database" states of the world view, and the settings tests of T26.6.
Alternatives rejected
counting per device on the workers (a hot-path cost); a force-directed layout or a graph library (bundle size, and moving nodes are hard to read and to test); canvas (no DOM for tests or screen readers); per-event pulses over the stream (bandwidth, and a peer's events would not arrive); remote map tiles (CSP, privacy, an outside dependency); a stored history (the existing heatmaps and flow already keep it).
Consequences
the map is an estimate under load (the sample rate is shown) and shows at most the 200 busiest devices; a quiet device is grey, not green; the world view depends on the answer-address field and a downloaded database and degrades to a clear message without either. Where a choice is between memory and disk (the owner's note on the footprint: more disk cache is fine, RAM is the budget), the map keeps its window small in memory and puts anything large on disk (ADR-959).
Requirements CLU-004 NFR-008 OBS-901 OBS-902
Builds on ADR-102 ADR-104 ADR-132 ADR-901 ADR-914 ADR-916 ADR-946 ADR-959
Referenced by ADR-1009 ADR-1010 ADR-970 ADR-979
Link to this decision · In the specification
ADR-959 The GeoIP database: DB-IP Country Lite, downloaded on an admin's opt-in, verified, kept on disk, never on the query pathOBS-902 needs the country of an answer address.
Context
OBS-902 needs the country of an answer address. NFR-001 and the owner's rule forbid shipping a database in the image; ADR-916's gate is for the image, and RSS is the hard budget on small hosts. The owner's note (2026-11-17) is that where it matters the footprint can use more disk cache rather than RAM.
Decision
- Source and licence. DB-IP "IP to Country Lite", CSV (
start,end,country), published monthly under CC BY 4.0: using it needs attribution, and we don't redistribute it (each install downloads it from the publisher). The world view's footer,docs/third-party-notices.mdand the site page carry "IP geolocation by DB-IP.com" with the licence link. Default URLhttps://download.db-ip.com/free/dbip-country-lite-YYYY-MM.csv.gz(this month, else last month: on the 1st the new file may not be published, so a 404 for this month makes one more request for the previous month before the attempt counts as failed). DB-IP's terms are re-checked at each release (a line in the release checklist). The URL is a setting an admin can change to their own HTTPS mirror. Rejected: MaxMind GeoLite2 (an account and key, an EULA that forces deletion on update), IP2Location Lite (an account), a bundled copy (NFR-001), an online lookup API (it would send answer addresses to a third party), an ASN database (a later addition if wanted). - Opt-in, admin-only, UI-controlled.
[map.geoip] enabled = falseby default: nothing is fetched until an admin turns it on in Settings → Monitoring (source_url, optional pinnedsha256,home_country). Status and last update are shown to every role; the toggle, the URL, Update now and Delete database are admin-only (not agent-writable; ADR-914's guard, audited asmap.geoip.*). The setting is shared; each full member that serves the UI fetches its own copy, started at a per-node jitter of up to 6 h so a cluster doesn't hit the publisher at once. Resolver pods never fetch. - Download. A background task (never a worker, never on the query path) with the list downloader's rules: HTTPS only, at most 3 redirects, each to HTTPS, the same address restrictions as list sources, a 30 s connect and 120 s total limit, at most 32 MiB compressed and 96 MiB uncompressed, one attempt at a time. It checks at most once a day and fetches only when the stored month is older than the current one. A failure backs off 1 h doubling to 24 h and shows its code, never a response body.
- Verification. The publisher gives no signature, so: TLS to the configured host; the gzip CRC; every line parses as
start,end,CCwith a two-letter code; after sorting, no overlaps; at least 100,000 rows, at least 150 distinct countries, both address families present; the row count within 30% of the database it would replace; and the pinnedsha256when set. The monthly file changes digest every month, so a pin is only useful with a fixed mirror URL whose content the admin controls; with the default URL the field should stay empty, and the UI and docs say so. A failure keeps the current database, reportsverification_failedwith the reason code, and retries the next day. These checks guard against a truncated or tampered-with file rather than prove authenticity, and the docs say so. - Storage and lookup.
<data_dir>/geoip/country.ttgeo, a compact file the node builds from the CSV: a header (magic, version, source month, row counts, a checksum), a sorted IPv4 table (startu32, countryu16) and a sorted IPv6 table (the first 64 bits, countryu16; ranges are cut to /64, which is conservative). The tables have no end column, so the builder stores an explicit gap row (country0, "unassigned") wherever one range ends before the next begins; without it an address in a gap would resolve to the previous country. The golden gap test stays. Written to a temporary file, fsynced, then renamed; the previous file is kept as.prevuntil the next success. About 1 to 5 MiB; at most 16 MiB or it is refused. Nothing is held on the heap: a lookup is a binary search with positional reads (pread, viastd::os::unix::fs::FileExtorseek_readon Windows) through the OS page cache, not a memory map, which would needunsafeoutsidewrendns-net(AGENTS rule 7). It is done only when the API builds a world answer (at most 256 prefixes), insideblocking()when called from an async handler, and never for a query, so the resident set is untouched and the disk cache does the work. A file that fails its checksum is ignored (geoip_missing) and fetched again. - Status and states.
GET /api/v1/map/geoip:enabled,state(off,downloading,ready,failed),sourceMonth,updatedAt,rows,sizeBytes,nextCheckAt,lastError(a code). A database older than 90 days still works and is flagged "old". Turning the toggle off stops fetching and leaves the file; the world view then says "GeoIP is off"; Delete database removes it. - No new heavy dependency. Decompression uses a gzip decoder already linked, or
miniz_oxideaftercargo-deny; the image delta is reported and must be near zero (T26.4 AC). - Test plan. A local fake HTTPS source (with a test-only loopback allowance, off in release builds and set only by the test harness, as the lists tests have, because the real address restrictions block 127.0.0.1) serves good, truncated, overlapping, too-small, wrong-checksum and redirecting files (
obs_902_*); the off state makes no request; the database is rewritten atomically after a crash during write; lookups match a golden table at range edges, gaps, IPv4, IPv6 and a v4-mapped address; the lookup holds no table in memory (the heap does not grow with the file); Playwright covers the toggle, the status, the read-only view for operators and viewers, the admin actions (Update now runs a fetch against the fake source and shows the new status; Delete database asks for confirmation, removes the file and showsgeoip_missing; both absent or disabled for operators and viewers), and the world view in both states.
Consequences
a fresh install shows the world view as unavailable until an admin opts in; country accuracy is DB-IP Lite's (country level, good for a picture, not for compliance); a mirror lets an air-gapped site use the feature.
Requirements NFR-001 OBS-902
Referenced by ADR-1008 ADR-958
Link to this decision · In the specification
ADR-960 Turning on automatic failover under a running cluster: the primary adopts it live, a replica stands only after a lease it saw lapses, replicas relay each other's healthT21.5's three-node run found that set-failover auto on a running cluster was unsafe (T21.5 open (a)): the replicas adopt auto from the signed records, while the primary kept running in manual mode and renewed no lease, so a replica could be elected and depose a healthy primary.
Context
T21.5's three-node run found that set-failover auto on a running cluster was unsafe (T21.5 open (a)): the replicas adopt auto from the signed records, while the primary kept running in manual mode and renewed no lease, so a replica could be elected and depose a healthy primary. The CLI warned and docs/running.md said to turn it on before the replicas join. The owner decided on 2026-11-17 that the running primary adopts the mode with no restart and that a replica never stands against a primary that has not yet held a lease (T21.7). The same run showed that replicas in manual mode report each other as not heard from (T21.5 open (1)), because a replica has a stream only to its primary until automatic failover starts the replica mesh.
Decision
- The primary adopts
autolive. The election task reloadscluster.jsonas soon as its modification time changes (astatper 250 ms tick on the cluster task, never on the DNS path), and at least every 5 s as before. When automatic failover becomes active on a node that is the primary (PrimaryorEmergency, epoch above 0, holding the cluster key), its elector starts asLeaderof the epoch it already has (Elector::resume), with no election and no new epoch, and renews with every voter at its next tick (renew_now), not after a full interval. The lease starts at zero: publishing pauses until a majority grants the first renewal (about one round trip;Cluster::begin_lease, which pauses without the "lease lapsed" warning that is for a lease that was held and lost). The same applies whenever the elector is rebuilt on a primary (a voter joins or leaves, a restart): it resumes its epoch rather than standing again. Safety is unchanged: a voter refuses a renewal at an epoch older than its ballot or at an epoch it gave to another candidate, and the primary then steps down as in any election; the grant of a renewal at the primary's own epoch is the existingBallot::deciderule. - A replica stands only after a lease it saw lapses. A server node calls
Elector::stand_only_after_a_lease: it may start a pre-vote only if it has seen a lease from another primary, that is, its stored ballot names another candidate with a lease, or it has granted a non-pre vote or renewal to another candidate since the elector was made (lease_seen), or its stored ballot is for itself (it was the primary) and it has learned of a newer epoch (an election needs a lease, and a deposed primary's own old lease refuses its successor's renewals for a lease period; found bydeploy/cluster/failover-e2e.shstep 4). The lapse itself is the existing check that the lease it granted is no longer running (lease_held_by_other), and the first-try wait of one lease period (ADR-947 addendum) stays. So a primary that never held a lease underautois never deposed, and a cluster whose primary is already down whenautois turned on elects nobody (conservative choice: promote by hand, asdocs/running.mdsays).Elector::newkeeps standing allowed (lease_seentrue), so the protocol simulator and a first election from nothing are unchanged. - Replicas relay each other's health. The heartbeat carries
peers(tag 41, repeatedPeerHealth { node_id, age_ms, ready, applied_seq }, at most 64): the members the sender heard within theupwindow and how long ago. A receiver keeps, for each named member other than itself and the sender, the newest report asheard_mson its own clock. A member it has no fresh stream to is shown up with linkrelayedwhile a report is within theupwindow; a member it hears directly is never taken on a relay's word. Older nodes ignore the tag and send none. The registry-only "down" rows (ADR-155) skip a relayed member. No new connection and no new protocol version (CLU-010). - Docs and CLI. The
set-failoverwarning and the ordering note indocs/running.mdare removed; the command says that no restart is needed.
Alternatives rejected
- A replica reading the primary's mode from the records and refusing to stand while the primary is manual. The primary's
autoand the replicas' arrive in the same record, so there is no moment a replica can tell the two apart. - Making the replica mesh run in manual mode too. It adds streams to clusters that chose manual failover; the relay costs a few bytes in a heartbeat.
- Taking a fresh lease for granted at adoption. A ballot a voter still holds for another candidate may run; the first round is the proof, and the pause is one round trip.
Review fixes (2026-11-17): (a) a node with no running election (manual mode) refuses real votes for a new epoch (it still grants a renewal to the primary it follows in its current epoch, which lets a primary that just adopted auto get its lease and publish the record that turns the replicas to auto) and answers pre-votes, so a primary that has just left auto and writes freely cannot be raced by a replica that a manual-mode voter would otherwise grant; (b) each rebuilt elector numbers its rounds from a process-wide generation, and a leader counts a grant only if it carries the led epoch, so a delayed reply to a predecessor never counts; (c) the standing rule is looser than "a lease from the current primary": any stored ballot for another candidate with a lease counts, however old. This is safe because votes still decide, and is the conservative reading; (d) a primary that cannot lead under auto (not eligible or no cluster key) logs a warning and stops publishing, as no replica has seen a lease; (e) relayed rows can come from any member's heartbeat and affect only the view and peers_up, never elections, so they are not limited to voters.
Consequences
set-failover auto is safe at any time. A primary pauses publishing for about one round trip when it adopts the mode. A replica that joins or restarts takes over only after its first renewal from the primary (at most 5 s later; the older scripts deploy/cluster/failover-e2e.sh and gitops-failover-e2e.sh wait for it before they kill the primary). A replica that has never seen a lease (a cluster that has only just turned auto on, with its primary down) waits for one. A heartbeat grows by about 40 bytes per member heard. Tests: clu_005_t21_7_a_running_primary_adopts_auto_and_is_not_deposed, clu_005_t21_7_a_replica_stands_only_after_a_lease_it_saw_lapses, clu_005_t21_7_a_stored_ballot_counts_as_a_lease_seen, clu_001_a_replica_learns_that_another_replica_is_up_from_the_primarys_heartbeats, the Playwright test clu_005 the failover mode changes on the Cluster page without a restart, and deploy/cluster3/e2e.sh check a2.
Requirements CLU-010
Referenced by ADR-971
Link to this decision · In the specification
ADR-961 The Pi-hole compatible API: v6 and v5, read plus blocking on/off, one token, off by defaultT24.10 (fork #7, API-002, API-005, AGT-001).
Context
T24.10 (fork #7, API-002, API-005, AGT-001). The owner wants dashboards, phone apps and the Home Assistant Pi-hole integration to work against WrenDNS unchanged, with read and enable/disable only (owner decision 2026-11-17), behind a token, off by default. Clean room: this ADR is written from Pi-hole's public API documentation and from what the Home Assistant pi_hole integration and its hole library (MIT) actually request, read from the ghcr.io/home-assistant/home-assistant:stable image on 2026-11-17. No Pi-hole code was read or copied.
What the Home Assistant integration calls. It probes v6 first (POST {base}/api/auth with {"password": ...}), and falls back to v5 (GET {base}/{location}/api.php?summaryRaw&auth=<token>; location is admin by default) when v6 fails with anything but a 401. v6 then reads /api/stats/summary, /api/stats/top_domains?blocked=true|false&count=10, /api/stats/top_clients?count=10, /api/stats/upstreams, /api/dns/blocking and /api/info/version, each with the session in X-FTL-SID (and X-FTL-CSRF); it switches blocking with POST /api/dns/blocking {"blocking": bool, "timer": seconds|null}; it signs out with DELETE /api/auth. v5 reads summaryRaw, versions (no token), and switches with enable=True and disable=<seconds|True>. A v5 probe with a wrong token must get [].
Decision
- Both dialects, one token. v6 is primary (current Pi-hole, tried first by Home Assistant); v5
admin/api.phpis served too, because phone apps and older dashboards still use it and Home Assistant falls back to it. The same token is the v6passwordand the v5authvalue, so one credential works for either. - Endpoint set (nothing else exists; every other path stays the problem+json 404 of the API):
- v6:
POST /api/auth(sign in),GET /api/auth(the session's state),DELETE /api/auth(sign out);GET /api/stats/summary,GET /api/stats/top_domains,GET /api/stats/top_clients,GET /api/stats/upstreams,GET /api/info/version,GET /api/dns/blocking,POST /api/dns/blocking. - v5 at
/admin/api.php:summaryRaw,summary,status,topItems,enable,disable[=seconds](token), andversions/version(no token, as in Pi-hole v5, because the Home Assistant integration asks for them without one; they return only our version string). - Of these only
POST /api/dns/blocking,enableanddisablewrite, and they only start or end a pause of everyone's blocking. Lists, rules, groups, settings and the other pause options stay on/api/v1.
- v6:
- Auth mapping.
- The token is
random_secret()(32 random bytes, URL-safe base64), shown once when an admin issues or rotates it, and stored as its BLAKE3 hash (the same scheme as API tokens: the secret has 256 bits, so a fast hash is safe). Comparison is constant time (crypto::ct_eq). - v6:
POST /api/authwith the token aspasswordopens a session held in memory: a randomsid, acsrfvalue,validity300 s that every use renews, at most 32 sessions (the oldest is dropped). Thesidcomes inX-FTL-SIDor thesidquery parameter, never a cookie. Rotating the token, turning the API off, or a restart ends every session. - v5:
auth=<token>on each request. Without a valid token the answer is[](as Pi-hole), HTTP 401 for a write. - Failed attempts (a wrong password, token or sid) count against the client address in the same lockout as sign-in (5 free, then 30 s doubling to 15 minutes; the first lock is audited as
auth.lockout), answered 429rate_limiting. A success clears the count. - A correct credential is never locked out. The presented credential is tested first and a correct one goes through even from a locked address, so a stale client behind the same address (NAT, a proxy, the Docker bridge) cannot lock out the right one; the lock applies to failures only. A session ends 24 hours after sign-in however often it is used (a sid in the query string is as exposed as v5's
auth; the docs say so). - Off, or no token set:
/api/...paths answer the API's normal 404 and/admin/api.phpanswers as any unknown page does (the web UI), so a scanner learns nothing, and nothing is audited.
- The token is
- Which of our numbers back each field (a 24 hour window, summed from the same buckets as
GET /api/v1/stats/summary, cluster-wide when clustered):queries.total/dns_queries_today: all queries.queries.blocked/ads_blocked_todayandpercent_blocked: theblockedstatus.queries.cached:cached+stale+refreshed.queries.forwarded:forwarded.queries.types: the query-type counts.queries.status:GRAVITY= blocked,FORWARDED,CACHE;queries.replies: by response code (NXDOMAIN,SERVFAIL,REFUSED;NOERRORisIP; the restOTHER).gravity.domains_being_blocked: the active snapshot's blocked names (filter_names).clients.active: the busiest clients of the window (top_range, at most 1,000);clients.total/clients_ever_seen: the same count over 30 days (at most 10,000), refreshed every 10 minutes.queries.unique_domains: the distinct names among the 1,000 most queried (a floor on busy networks; the real count is not kept).top_domains,top_clients,upstreamscome fromtop_range(domains, blocked, clients) and the upstream list (requestsascount, the smoothed latency asstatistics.response). The statistics (not the blocking status) are cached for 10 s, so Home Assistant's several reads cost one aggregation.dns/blocking:disabledwhile any node has an everyone-pause (the longestsecondsLeftastimer), elseenabled;unknownwhen no node answers. A pause of one group does not make itdisabled.versions: our version ascore,webandftlcurrent; the latest versions are empty and no update is ever offered.
- Pause is the same pause. The handlers call the same function as
POST /api/v1/blocking/pause/resume(one shared core, so the validation, the cluster fan-out, the change marker and the audit entry are identical), with the actortoken:pihole-apiand the client address.timerseconds become whole minutes, rounded up. Pi-hole's "disable with no timer" (forever) is not offered: it pauses for the settingmaxPauseMinutes(default 60, 1 to 1,440, an admin may raise it in Settings), like an agent's cap (spec/13 §3.2): a credential in a URL or a phone must not be able to leave filtering off for good. A longertimeris cut to it. The answer reports the realtimer. - Listener, networks, CSRF, sessions, audit.
- Same API listener, no new socket. The paths above are added next to
/api/v1;[access] allowed_networks(the listener'sonly_allowedlayer) applies to them first, as to every API path. The compatibility paths are outside the sign-in session machinery: they accept no cookie, so a browser's ambient credentials never apply, and there is no CSRF surface (a forged cross-site request cannot carry the token or sid). WhenX-FTL-CSRFis sent it must match the session'scsrf, else 401; it is never required, because a header-bearer client holds no cookie. - v5 puts the token in a URL, which a proxy or access log may keep. v5 is the legacy dialect; the docs say to prefer v6 and to rotate the token if it was logged. The token is the only credential in it and it can do nothing but read the statistics and pause blocking up to
maxPauseMinutes. - Audit (
GET /api/v1/audit):pihole_api.enable,.disable,.token_rotate,.token_revoke,.settings; every pause or resume made through it is the ordinaryblocking.pause/blocking.resumeentry withvia: pihole-api; a write attempt refused for no or a wrong token or session (not while the API is off: that is a plain 404 and no audit, so a node that never turned it on has no new write path) ispihole_api.denied(at most one per client network per minute, an IPv6 client by its /64, and at most 10 in all per minute, written off the async threads, so a scanner cannot fill the log).resumeends every pause, group pauses included (that only restores blocking). The token is a static credential, not a user sign-in: it keeps working withdisable_local_login = true(ADR-944) and outsideallowed_admin_networks(onlyallowed_networksapplies), and it can only read and pause. Reads and sign-ins are not audited one by one (Home Assistant reads every five minutes); the lockout is.
- Same API listener, no new socket. The paths above are added next to
- Admin surface (admins only; agents never write it):
GET /api/v1/pihole-api(enabled,tokenSet,tokenCreatedUnixSeconds,lastUsedUnixSeconds,maxPauseMinutes; agents withconfig:readand the MCP toolpihole_api_statusmay read it, it holds no secret),PUT /api/v1/pihole-api(enabled,maxPauseMinutes),POST /api/v1/pihole-api/token(issue or rotate; the response is the only time the token is shown;Cache-Control: no-store),DELETE /api/v1/pihole-api/token(revoke). Settings → Pi-hole has the control, a copy button for the token and the two example addresses. No agent scope writes it (the token is a credential, as with secrets). - Storage. One row in the node's
state.db(migration 14):enabled(default 0), the token's hash, when it was made, when it was last used,max_pause_minutes. It is per node and not replicated (a conservative choice, recorded as a gap: replicating a credential needs ADR-903's secret rules): in a cluster an admin turns it on where Home Assistant should look, and the pause it makes still reaches every node. Nothing on the DNS path reads it (CLU-004).
Test plan. Unit (wrendns-api): off, no token, and a wrong token refuse every path and the write is audited once; the token is shown once and stored only as a hash; v6 sign-in, sid renewal, expiry, rotation ending sessions; lockout after repeated wrong passwords; summary fields from a fixed backend; disable and POST /api/dns/blocking call the same backend pause as /api/v1/blocking/pause (the same audit action and arguments), timer rounding and the maxPauseMinutes cap; v5 [] for a wrong token and versions without one. Playwright: Settings → Pi-hole turns it on, shows the token once, the compatible endpoint answers with it, rotation invalidates the old one. Integration: deploy/ha-test/e2e.sh configures the real Home Assistant Pi-hole integration against a throwaway node, reads its summary sensors, and switches blocking off and on.
Alternatives rejected
serving only v6 (phone apps and Home Assistant's fallback need v5); a separate listener (a second port to firewall and a second allowed-networks story); accepting the signed-in session or an agent token on these paths (a different credential model than what the clients can send); "disable forever" (see 5); an unauthenticated status (Pi-hole v5 has one; here every read except versions needs the token); replicating the token across a cluster now (needs the secrets rules).
Consequences
one more credential to rotate, off until an admin asks for it; statistics shown to a Pi-hole client are the same ones a viewer sees (domains and client addresses at the node's privacy level); unique_domains and clients_ever_seen are bounded counts and say so in the docs.
Requirements AGT-001 API-002 API-005 CLU-004
Link to this decision · In the specification
ADR-965 Backups with stored secrets: the archive format, the restore's key and re-stamping, the bounds the spec left openT23.9 (API-007; ADR-903 §8, which amends ADR-063) puts the stored secrets into a backup under a passphrase.
Context
T23.9 (API-007; ADR-903 §8, which amends ADR-063) puts the stored secrets into a backup under a passphrase. ADR-903 §8 fixes the cipher, the key derivation and its recorded parameters, the manifest block, version 2, the refusals and the CLI flags. It leaves open a few details; each is the most conservative reading, recorded here for the owner.
Decision
- Cost bounds. Restore refuses a recorded cost over m = 256 MiB, t = 10 (ADR-903) and p = 8 (new: the spec bounds two of the three parameters, and lanes multiply the time and the threads), an algorithm other than Argon2id v1.3, a zero cost, and a salt outside 8 to 64 bytes. The check runs before any derivation and before anything moves;
--skip-secretsandbackup showdon't need it (a hostile manifest can still be skipped or listed). - Plaintext. The JSON list holds
updatedas Unix seconds (the store's own unit; the API's RFC 3339 is a presentation). Restore keepsupdatedandupdated_by, stores the rows aslocaland unorphaned, and stamps them from the start of epoch 0 with the database's own counter (next_secret_stamp(0): never a stamp the database holds). A restored node is standalone (the cluster identity isn't in a backup), so epoch 0 is its current epoch; a node that joins a cluster later goes through T23.5's adoption as any standalone node with local secrets does. - What goes in. Every live row this node can read, cluster rows included (a replica's backup carries what it holds). A row stored under another key, damaged, or orphaned by a failover is left out and warned about ("N stored secret(s) couldn't be read"), not an error: the backup of everything else still has to be makeable. A locked store, though, refuses a backup with a passphrase (the CLI and
503 secrets_lockedon the API): it would silently drop every secret. - No secrets, no
secrets.enc. A passphrase with nothing readable to put in makes no file and stays version 1 (older builds restore it); the manifest'ssecretsblock is written in every backup from this build (included: false,count= how many the node stored,omittedReason:no passphrase,none stored, or none readable). Archives from before this build have no block and read as none. - Version and block must agree. A manifest whose version,
secrets.includedandsecrets.encentry don't match is refused as damaged. - Restore's key. The key comes from the key settings (
secrets_key_file,secrets_previous_key_file), the process environment and, when neither names one,<data-dir>/secrets.key(made if absent, as the server does for an empty store). The settings are those of-cwhen it is given and otherwise those of the archive's own configuration files (staged, and loaded the way the server will load them once they are restored): ADR-903 §8 resolves the key "from the same configuration as the server", and asudodropsWRENDNS_NODE_SECRETS_KEY, so the restored files are the only place the unit's settings are. Staged files that don't load stop the restore (give-c, or--skip-secrets). A configured key that can't be read (or isn't valid) is an error before anything moves: nothing is generated in its place.-cstays optional: a fresh machine has no configuration yet, and the archive's files stand in for it. A key the restore makes is given the data directory's owner (restore usually runs as root for thewrendnsservice user, which couldn't read a root-owned key and would come up locked), and a key made for a restore that then fails before any file moves is removed again. The restore prints the key's source andkey_id, never the key. The stagedstate.dbreceives the rows and its WAL is truncated before it is moved, so no ciphertext or plaintext stays in a sidecar file. - Passphrase sources (CLI).
--secrets-passphrase-file(the first line),--secrets-passphrase-stdin(the first line; a terminal is refused) and--secrets-passphrase-prompt(the terminal, echo turned off withstty, twice when creating). Never an argument or an environment variable. No terminal-handling crate is added (unsafeis only forwrendns-net, and nothing in the lock file does it): a platform wheresttycan't turn echo off refuses the prompt and says to use a file. Restore asks only when the backup needs one. - One derivation at a time. A process-wide slot (a flag, not a queue): a backup or a restore that finds it taken fails at once (the API:
429 rate_limited,Retry-After: 2). The slot is held for the derivation only, not the whole backup. A request checks the flag first, before it reads and decrypts the secrets or copies the databases, so a burst is refused cheaply; the slot itself is still taken at the derivation (a race loses there, with the same answer). - Warnings. The inline-credential warning counts entries of the configuration files (upstreams, lists and alert destinations by their credential paths, and the routers, OIDC providers, sinks, OTLP headers and Git credentials the settings pages hold) and the
managedrows of the backed-upstate.db, counting only a credential held in the entry itself (not a*_refor*_file). It names counts, never a value. - The rest of the archive is bound to the passphrase (amends ADR-903 §8). The associated data is
"wrendns-backup-secrets v2" ‖ backup_id ‖ binding, wherebindingis a BLAKE3 hash (derive-key mode, contextwrendns-backup-binding v1) over the manifest'sformat,versionandnodeand the(path, size, blake3)of every entry butsecrets.enc, sorted by path, each field length-prefixed. The manifest's own hashes are held in the same file and anyone can recompute them, so without this someone who can edit a stored.ttbkbut doesn't know the passphrase could point a configuration file'srouter[].urlat their own host while keeping itsapi_key_ref, and a restore would then hand them the secret: the redirect ADR-903 §4 guards against on the API. Now any change to the configuration, the databases or the entry list, or to the node's name, makes the cipher fail as "wrong passphrase or damaged archive" (--skip-secretsstill restores an edited archive: it holds no secret). Thev1of the prefix was never released (this task's branch only), so no archive with the old prefix exists; the format stays version 2. - Terminal prompt. A drop guard turns the echo back on when the prompt returns, errors or unwinds; a process killed by a signal mid-prompt can't (no signal handling without a new crate, §7), so the docs say to run
stty echo.
Verification
the AC tests in crates/wrendns/src/backup/secret_tests.rs and backup_api_tests.rs; Playwright api_007 passphrase backup from settings.
Not changed, noted: the request body holding the passphrase (hyper's buffers, then the parsed Bytes) isn't wiped: the copy in the parser's hands is out of this code's reach, and the passphrase is wiped everywhere this code owns it. The creation cost is ADR-903's modest one (17 to 29 ms a guess on x86) for a file that can be attacked offline, with a 12-character minimum and no strength check; restore already accepts up to 256 MiB, so the cost can be raised for new backups (for example m = 64 MiB, t = 3) once the Pi 4 figure below is measured, with no format change.
Open
the Pi 4 derivation time and peak memory aren't measured (no Pi on the build host). On the x86 build host (one core, release build) the derivation takes 17 to 29 ms and the process peaks at 21.6 MiB, so the Pi 4 figure is still to be recorded (wrendns backup create --secrets-passphrase-file with time -v); the parameters stay ADR-903's (m = 19,456 KiB, t = 2, p = 1) until it is measured.
Requirements API-007
Link to this decision · In the specification
ADR-966 The backup endpoint's recent sign-in, transport and alertADR-903 §8 names the API's rules (admin, HTTPS, a session signed in within 10 minutes for a passphrase backup, header, audit, alert event) without saying how "signed in within 10 minutes" is known, what an OIDC session does, how the UI recovers from the refusal, or where the alert event comes from.
Context
ADR-903 §8 names the API's rules (admin, HTTPS, a session signed in within 10 minutes for a passphrase backup, header, audit, alert event) without saying how "signed in within 10 minutes" is known, what an OIDC session does, how the UI recovers from the refusal, or where the alert event comes from. T27.13's guarded changes reuse the recency rule, so it is one helper.
Decision
- The helper.
Auth::recent_sign_in(principal, now)(RECENT_SIGN_IN_SECS = 600): the session'screatedtime, read fromstate.db, is within 10 minutes. A session's activity doesn't extend it (last_seenis not used), a display session never qualifies, and an API token, an agent token or HTTP Basic never has one:403 reauth_required(a new problem code) with a hint namingwrendns backup createfor those. An OIDC session counts from the creation of its local session, which is the callback that followed the provider's sign-in: a silent provider round trip (the provider's own session still valid) makes a fresh local session without the user typing anything, so the rule is weaker for single sign-on than for a password. The provider'sauth_timeisn't checked and nomax_ageis sent; doing that is a follow-up with the OIDC verifier (ADR-951), recorded here rather than silently assumed. The 403 comes before the backup is made, so nothing is audited for a refusal. - Which requests. The recent sign-in is for a passphrase backup only (what leaves the node is the secrets); without a passphrase an admin token or any admin session is enough, as
GETalways was. Agents are refused for everyPOST /api/v1/backup(agent_not_allowed, by the agent route policy and again in the handler);GETwas never in their scopes either. - Transport. The HTTPS-or-loopback rule of ADR-903 §4 (
transport_ok) applies to everyPOST(the passphrase is in the body), not toGET.[api] allow_secrets_over_httplifts it as for secrets. - The body.
{includeQlog?, passphrase?}, unknown fields refused; the parser's error never quotes the input (a mistyped passphrase could be in it). An empty body is{}. A passphrase under 12 characters is400.includeQlogis400when the query log is over 256 MiB (the API builds the archive in memory; the CLI has no limit). - The answer. The file,
Cache-Control: no-store,X-Wrendns-Backup-Secrets: included|omitted; count=N(onGETtoo: alwaysomitted) and, when there are some,X-Wrendns-Backup-Warnings(items joined by|, ASCII). NoIdempotency-Key: it changes no state. - The audit record
backup.create {bytes, secretsIncluded, count, includeQlog}is written forGETas well. It never holds the passphrase, a value or a name. - The alert.
AlertWhen::SecretsExported(secrets_exported), a one-off condition likecredential_redirected: it reads the applying node's last hour ofbackup.createrecords withsecretsIncludedtrue, once per record, naming who and how many, never which. Alerts are evaluated on the primary (or a standalone node) from that node's own audit log, so a replica refuses a passphrasePOST /api/v1/backupwith409 conflictand a hint to use the primary (the secrets are replicated, the content is the same); a backup without a passphrase is made anywhere, as before. As with any new condition, an N-1 replica refuses a configuration version whose rule uses it. A backup made by the CLI isn't audited (it runs outside the server) and raises nothing. - The UI. Settings → System → Backup (admins): a passphrase and a confirmation (12 characters, typed twice), an option for the query history, the omitted-secrets notice after a download, and, on
reauth_required, a password prompt (and the authenticator code when two-factor sign-in asks) that signs in again, which replaces the session with a fresh one, then makes the backup that was waiting. Nothing typed is kept: the fields are cleared when the request goes. A single-sign-on account has no password: the page says to sign out and in again.
Link to this decision · In the specification
ADR-967 OIDC providers in the UI: an admin-only node-managed kind with its own routes, applied by one task, never on the answering pathT23.10 makes [[auth.oidc.provider]] editable in the UI (API-016, ADR-903 §6-7).
Context
T23.10 makes [[auth.oidc.provider]] editable in the UI (API-016, ADR-903 §6-7). ADR-903 fixes the broad shape: an oidc_provider kind, admin-only, the file's ID wins, the client secret by name (client_secret_ref), Auth.oidc an ArcSwapOption, flows and the discovery cache kept across a rebuild, one rebuild at a time with a generation counter, a provider whose discovery fails keeps its previous settings or is left out with a reason, sessions and the break-glass admin untouched. It leaves open where a UI provider lives in the configuration (the whole auth section is node-local, and public_url must stay so), how a node without public_url behaves, how the read surface looks, what happens to the sessions of a removed provider, and when a rebuild runs.
Decision
- The kind.
ManagedKind::OidcProvider, stored inmanagedby ID.PUTandDELETE /api/v1/oidc-providers/{id}and one read,GET /api/v1/oidc-providers, all admin-only: an operator is 403, an agent is refused (the read and the writes have no scope, so the agent default,Need::Forbidden, applies), and a forwarded write without a role (an older node) is 409upgrade_required, as for routers (ADR-921). There is no MCP tool: the read is admin-only and the kind is configuration of a security gate (ADR-903 §5). - Bodies are references only. The body is
[[auth.oidc.provider]]withoutclient_secretandclient_secret_file(422 if either is set: a path the API can set is a path an admin can point at any readable file, ADR-921's reason; an inline secret would sit in the audit log and the blob).client_secret_refnames a stored secret (422secret_missing), and redirecting it at another kind's secret is audited ascredential.redirectlike the other kinds. The provider's own rules (ID, issuer, client ID,openidscope) are the file validator's, shared throughwrendns_config::oidc_provider_errors. - Merged apart from
[auth.oidc] provider. The UI's providers land inOidcConfig.managed_provider, a field that is never serialized (#[serde(skip)],#[schemars(skip)], so the schema,shared_partand the config reference are unchanged). They are not inproviderbecausevalidate_configdemands apublic_urlfor any provider: a node without one would otherwise reject the whole merged configuration and fall back to the files, losing every UI change (CLU-004). The files win by ID; a bad stored entry is dropped alone with a warning.references()and sousedByandsecret_in_usecount both lists. - A node without
public_urlshows the provider as inactive.public_urlstays in each node's file (it is how that node is reached, ADR-045).GET /api/v1/oidc-providerssaysactive: falsewith the reason, and the UI shows a banner; nothing is registered with the service on that node.mcp_provider(OAuth for MCP, AGT-008) can still name only a file provider. - One applier task.
auth_setup::runwaits forSources.oidc_changed(fired after every configuration reload, every stored-secret write or delete, and every pull of replicated secrets), waits 250 ms for the rest of a burst, resolves each provider's secret on a blocking thread (inline, its file, or the store) and callsAuth::reload_oidc. A provider whose secret can't be read is left out alone with the reason; the rest are served. It never runs on a request path, a reload or the DNS path. A provider whose discovery couldn't be read is tried again after 60 s, doubling to 10 minutes, until it can be (or the configuration moves on). - Discovery is read only when needed. A provider that is new or has a new issuer is read when it is applied; one whose issuer is unchanged reuses the cache (keyed by ID and issuer), so a role-rule or secret change never reaches the provider. If the read fails, an unchanged issuer keeps the previous settings of that ID (reported
activewith the reason, say after a restart while the provider is down); a changed issuer fails closed: the old issuer is not trusted on, and the provider is left out (inactive, the reason, tried again later), as is a new ID. At start the service is built from the configuration without waiting for a provider (as before); the first applier pass reads discovery in the background. - Sessions, users and tokens. A provider the configuration no longer names (neither served nor skipped) has its sessions deleted (
delete_provider_sessions,sessions.oidc_provider), on every node when its removal arrives. The users it created stay and can sign in again if the provider returns. A provider that is only inactive here (nopublic_url, an unreadable secret) keeps its sessions. A removal that happens while a node is down is not swept at the next start, so authentication itself refuses (active_user): a user whoseoidc_providerthis node's configuration does not name (an in-memory lookup kept by the rebuilds, off the DNS path) can use neither a session nor an API token, until the provider returns; this covers the tokens such a user minted for MCP clients. Issuers:users.oidc_issuerandsessions.oidc_issuer(migration 15) record the issuer a link or session was made at (users replicate it). A rebuild that repoints a provider to another issuer deletes that provider's sessions of the old issuer at once, even if the new one cannot be read; a user linked at another issuer than the provider has now is not mapped (403, an admin deletes the user so the person signs in as a new one), because asubis unique only within one issuer; a sign-in started before the change is refused at its callback (flows are kept by ID and issuer). Rows from before migration 15 have no issuer; every rebuild settles them (reconcile_provider_issuer) for each provider the configuration names, served or skipped (a skipped entry carries its issuer, so a provider whose new secret can't be read is still swept): with no earlier issuer known in this process (the first rebuild after the upgrade) they take the current issuer, which replicates, and when the rebuild sees the issuer change they belong to the old one (their sessions end, the users keep the old issuer). A repoint made while the node is down, before its first rebuild after the upgrade, can't be told apart from the current issuer: the rows adopt it (accepted; the window is one start-up). - Resolver pods. An ephemeral member holds no stored secrets and serves no sign-in: it skips UI providers that name a secret, with one info log (ADR-903 §6).
- UI. Settings → Sign-in (admins only; an operator sees no tab and the server refuses the reads and writes): cards with the provider's source (
Set by fileis read-only), status, reason, secret source and readability, roles and redirect URI; a form whose secret is aSecretField(namedoidc.<id>.client_secret, "Save the provider" waits for a typed secret); help topicsoidc-providers,oidc-role-rulesandoidc-public-url.
Consequences
a provider is added, changed or removed without a restart and without touching DNS; the file's provider can't be shadowed; a node with no public_url is safe; and a removed provider ends its sessions. The cost is one more field in OidcConfig that is not part of the file schema, and that mcp_provider and disable_local_login (guarded, T27.x) still follow the file only. Rejected: merging into provider and relaxing the public_url rule (the rule protects file configurations, and a per-provider rule would still reject the node), an inline client_secret in the body (it would travel in audit and blob), an agent read (nothing an agent needs, and the admin-only read keeps the kind consistent), and reading discovery at every reload (a provider outage would then block unrelated changes).
Requirements AGT-008 API-016 CLU-004
Builds on ADR-045 ADR-903 ADR-921
Referenced by ADR-1006 ADR-984
Link to this decision · In the specification
ADR-968 Node-managed entries replicate as one more blob of the signed version, seeded into a promoted primary's own rows onceADR-903 §6 says node-managed entries (oidc_provider now, sink and otlp with T23.11) are configuration, so they are versioned: ClusterManifest.node_managed holds references only, every member persists, validates and merges it apart from the shared part under its own files, a failure drops only those entries, and a promoted primary publishes the inherited blob overlaid with its own rows and seeds its managed rows from it.
Context
ADR-903 §6 says node-managed entries (oidc_provider now, sink and otlp with T23.11) are configuration, so they are versioned: ClusterManifest.node_managed holds references only, every member persists, validates and merges it apart from the shared part under its own files, a failure drops only those entries, and a promoted primary publishes the inherited blob overlaid with its own rows and seeds its managed rows from it. It leaves open the blob's format, when a promoted node's rows stop being overlaid by the stale blob, how a Git source and pins treat it, and what an older node does.
Decision
- The blob.
node-managed.json:{"version": 1, "entries": [{"kind", "name", "body"}]}, sorted by kind and name so equal rows give equal hashes, withclient_secretandclient_secret_fileremoved from every body on export (a stored value that predates the rule never leaves the node) and any entry that still carries one refused on import. A document of a newer version, or one that does not parse, drops all its entries with one log line (upgrade this node); an entry of a kind this build does not know is skipped; a provider that does not validate is dropped alone. The manifest field is#[serde(default, skip_serializing_if = "Option::is_none")], so an older replica ignores it and an older primary's manifest reads (CLU-010). - Publishing. The primary exports its
managedrows of the node-managed kinds and re-reads them only whenconfig_versionmoves (the loop runs twice a second). A change of the blob is a new version (Published.node_managed, history entries and pins carry the blob). An emergency primary passes on the blob it inherited, and a pinned one the pinned version's. - Applying. Nothing is stored on a replica: its last applied manifest names the blob, which is already in the blob store, so it survives a restart with the manifest.
merged()overlays it afterwith_shared, under the node's own files (the file's ID wins; a resolver pod skips entries that need a stored secret). A replica never writes these rows; writes are forwarded to the primary as every managed write. - Promotion. A primary that follows a version it inherited (
base) seeds its rows from the blob once: entries it has no row for become its rows (its own rows win, which is the "overlaid with its own rows" of ADR-903), and a markernode-managed-seededin the cluster directory keeps the blob's hash. While the marker matches, the inherited blob is not overlaid again, so an entry deleted after the promotion does not come back from the stale copy. If seeding fails, the blob stays overlaid (the safe default: nothing is lost) and the next pass tries again. A replica never writes these rows, so any it holds are left from an earlier time as primary: they are deleted when the node is a replica (node_managed::clear_stale, which also removes the marker), and a later promotion seeds from the blob it inherits alone (blob wins). A provider the cluster removed or repointed meanwhile therefore does not come back. - Git. A primary with a Git source carries the rows unchanged (writes of these kinds are 409
gitops_managedon every node, as all managed writes), and applies them itself on top of the commit's configuration. - Standalone nodes have no manifest; their rows are applied by the ordinary merge.
Consequences
the secret travels only by the existing secrets replication (ADR-903 §6), the provider list by the signed manifest (so pins, rollouts and history cover it), and a bad blob costs only its own entries. Rejected: a second channel for these rows (a new thing to authenticate and order), carrying the secret in the blob (a plaintext file on every disk), and re-seeding on every pass (it would resurrect deleted entries).
Requirements CLU-010
Builds on ADR-903
Referenced by ADR-1049 ADR-1050 ADR-1063 ADR-984
Link to this decision · In the specification
ADR-969 wrendns snmp walk before the agent list exists: the lookup is the only seam, an address is refused as a name, and ownership is tested by bindingT25.4 (DSC-003, ADR-908 "Diagnostic CLI") asks for wrendns snmp walk --agent <name>, which takes a configured agent name only.
Context
T25.4 (DSC-003, ADR-908 "Diagnostic CLI") asks for wrendns snmp walk --agent <name>, which takes a configured agent name only. [[discovery.snmp_agent]] and [[discovery.snmp_credential]] are T25.6 and T25.8 and ship with their own UI (standing rule), so the config has no agent to find yet. Adding the schema in T25.4 would add settings without their UI controls, help topics and Playwright tests.
Decision
- One seam.
snmp_cli::lookup(cfg, name)is the only place that turns a name into anAgentSpec(address, credential files). Until T25.6 it finds none and says so. Everything after it is built and tested: the destination check (ADR-907), the credential read from*_fileunder[node] secret_file_dirs, the table roots with their fallbacks, the bounded walk (rows, time, pacing) and the printing. T25.6 replaces the body oflookupand nothing else. - An address is not a name.
--agentvalues that parse as an IP address or a socket address are refused before the lookup. The command line has no other way to give a destination (--agent,--table,--configonly). - Table groups.
arp: ipNetToPhysicalTable, else ipNetToMediaTable.ifmib: ifTable, ifXTable, and ipAddressTable else ipAddrTable.bridge: dot1qTpFdbTable else dot1dTpFdbTable, and dot1dBasePortIfIndex.lldp: lldpRemTable. The first root of a group that answers a row wins; the others are not read. - The host's own address (a refused destination, ADR-907) is found by binding a UDP socket to it: a bind that succeeds means the address is local. No new dependency and no interface listing.
- Output. Rows print as
OID = TYPE: value; device strings are cut at 255 bytes with control characters replaced (ADR-908 "Untrusted strings"). No credential is read into the output path.
Alternatives rejected
adding [[discovery.snmp_agent]] to the schema now (settings without UI); accepting --address for a quick test (it would let the command reach any host, against ADR-907).
Consequences
the subcommand reports "no agent configured" until T25.6; wrendns links wrendns-snmp (binary +13,440 bytes, stripped release, measured below in T25.4's Done note).
Requirements DSC-003
Referenced by ADR-1001
Link to this decision · In the specification
ADR-970 The map's sampler as built: inline on the aggregator thread, a flat window, no answer address yetT26.2 (OBS-901) built ADR-958.
Context
T26.2 (OBS-901) built ADR-958. Measuring it on the real aggregator and a real node changed four details of how the design is realised and settled the question ADR-958 left open (the answer address). Nothing here changes what the map shows; it is recorded because the ADR said otherwise or said nothing.
Decision
- The answer address is not recorded;
/map/worldreturnsaddress_not_recorded. ADR-958 section 3 ships the field "only if the ring record does not grow". It does: the wire record's fixed part goes from 61 to 78 bytes (a typical record from about 85 to about 102 bytes, 20% more per event, so each worker ring holds about 17% fewer events), and the copy would run on every cache miss in the workers' own code.size_of::<QueryEvent>()is 64 andsize_of::<Record>()is 320 now (pinned byobs_901_record_sizes_are_pinned, withMAX_RECORD316 and the name's 256), so a field cannot hide in padding. The conservative reading (AGENTS rule 4: nothing on the hot path without a benchmark that proves it) is not to add it, so T26.5 ships with upstream markers labelled "upstream locations, not where answers point".GET /api/v1/map/worldanswersavailable: false, reason: address_not_recordedand counts every lookup as unlocated (geoip_offandgeoip_missingare T26.4's, and the response already has them). The owner can overrule by adding the field in a later task that measures it. - The sampler runs inline on the aggregator thread, with no queue between. ADR-958 section 2 describes a bounded subscriber queue whose overflow is counted. The aggregator already folds each event into the analytics in the same pass, and the counter-based selector is one increment for every event it skips, so a queue would add a copy per event and nothing that needs bounding. The "drops" that exist are the worker rings' own (
RingStats.dropped): the aggregator hands the sampler the rings' running total after each drain (Sampler::tick), and the delta joins the tick's total before N is computed and scales the weights of the next tick (Q16 fixed point, with the fraction carried, so the estimate stays unbiased:obs_901_sampler_overload, 20% of a stream lost, within 5%). A burst inside a tick doubles N at once (at most twice the per-tick cap is kept). The sampler lock is held for a drain by the aggregator and for a window read by the API; a worker never takes it. - A flat window, not a hash table. Each 5 s slot is a
Vecof at most 1,024 rows, grown through 64, 256 and 1,024, searched linearly: at mostevent_rate(2,000) lookups a second are kept, so a scan costs a few microseconds on the aggregator thread. The first build used aHashMapper slot and measured +4.9 MiB RSS at the cap (a table keeps a load factor, doubles, and left freed tables in the allocator), far over the gate; the flat window costs about 590 KiB at the cap and measured +0.6 MiB (below). The key adds a sixth counter,limited(rate-limited lookups), to the five of ADR-958, for the device rule "any rate-limited query". - Defaults and names.
[map] enabled = true(the sampler costs 0.1 MiB at idle and 0.6 MiB at its cap, and a map that needs turning on first is a map nobody sees; the owner can flip it).warn_latency_msis optional: unset follows[slo] latency_ms. ADR-958 calls the read scoperead:stats; the scope that exists isanalytics:read, soGET /api/v1/map*and the MCPnetwork_healthneed that (a token with onlyconfig:readis refused). The MCP tool reads a newGET /api/v1/map/health(counts, up to 50 red and yellow nodes with reasons, the five busiest flows), so the tool and the route are one thing. The write scope isconfig:write:mapand the MCP plan toolplan_set_map; operators write, viewers read, an agent needs the scope and gives a reason; a GitOps authority refuses the write and shows the TOML (the same path as[exclusions]). - What the colours cover (the pieces ADR-958 left to the table):
idleis decided after the facts (an open breaker or an unreachable node is red, a half-open breaker yellow, with no samples at all); a resolver takes its own ADR-104 level and the worst of what is downstream of it (its upstreams and answer kinds), not of its devices, so one failing device does not colour the resolver; a network takes the worst of all its devices, including the ones folded into+N more; the gateway is grey without a router integration, green when healthy, yellow on an error, never red. At privacy level 2 the sampler holds no client key, so the networks cannot be told apart per device: the map shows onedevices hidden by privacynode under an "All networks" node (not one per network, which would need the address ADR-102 hides). At level 3 the window keeps resolver totals only (no group, answer kind or upstream). The anomaly's yellow is level 0 only, as the ADR says; the open findings come from the node that found them and are those of the last 24 hours nobody acknowledged and no mute matched.
Measured (this host, 24 CPUs shared with other work; the host's UDP bind() takes 10 to 20 ms, which makes make bench-smoke print the host's numbers, see the Done note of T26.2):
- Aggregator throughput, 7 alternating runs, medians (
obs_901_sampler_throughput_ab, release): sampler on over off 1.018, 0.996 and 1.003 (spreads 2% to 15%), and 0.961 and 0.972 on busier runs; all inside the 5% band. - RSS, Pi profile (2 workers) (
bench/mapprobe.py): idle 19.3 to 19.4 MiB with the map off, 19.3 to 19.6 with it on; after 270,000 lookups from 14,000 distinct devices at 3,000 a second, steady for 2 to 5 minutes: 39.2 and 39.7 MiB off, 39.7 and 40.4 MiB on, so the delta at the key cap is +0.6 MiB (range 0.0 to 1.2), under the 1.5 MiB gate. - Cache-hit path A/B (
bench/ab_hot.py, 7 alternating rounds, 4 workers): median 666,752 qps without the change and 700,630 with it (1.05; the spread is 530,000 to 890,000 either way).
Consequences
the map's memory is at most about 0.6 MiB and bounded; a deployment that wants the world view's answer addresses needs the field, decided separately; a very high rate of distinct devices (more than 1,024 keys in 5 s) counts the rest under other, which the snapshot shows as resolver totals without a device.
Review amendments (2026-11-18):
- A rise in the privacy level purges the sampler.
Sampler::set_privacyto 2 or more empties every slot, its overflow count and the recent-lookup list, so no client key outlives the switch (the build also treats every key as hidden at 2 or more).Hub::set_privacyreaches the sampler at once; a sampler made later starts at the level in force. - A new sampler starts from the rings' drop total as it is then (
Sampler::new(settings, dropped_now)), so turning the map on after an overload does not count the whole history as one tick's drops. - Readers copy, then sum.
map_windowcopies the slots in the window under the lock (Sampler::freeze) and sums and sorts them outside it, so a reader never holds the aggregator back for more than a copy. The routes serve an unfilteredGET /mapand/map/healthfrom the ticker's last snapshot when it is younger than 2 s, run at most 4 other builds at a time, and a stream is toldmap_disabled(and ends) when the map goes off. One user or token holds at most 2 of the 8 streams. - Two deviations from ADR-958, kept on purpose. (a) The overload weight scale is the tick's total over its offered answerable lookups, where the total includes the rings' drops of every kind (upstream exchanges, probes and excluded queries too); under overload on miss-heavy load the weights can be a little high. The error is bounded by the 64x cap and by the share of non-lookup records, and the unbiased test (
obs_901_sampler_overload) holds for lookup-only load; the records' kinds are not known for events a ring dropped, so no better ratio exists. (b) The recent-lookup list is one ring of 1,280 lookups, not "the last 20 of each of the 64 busiest edges": the edges are only known when a snapshot is built, so a per-edge list would need a key and a list per device on the aggregator thread. Under a flood of distinct clients the busiest edges' lists can be short. - Measured again (
obs_901_sampler_throughput_ab_unique_clients, release: 60,000 distinct clients atevent_rate = 2000, the slots full): sampler on over off 0.983 (spreads 2.3% and 3.2%); the four-client run 0.996.
Requirements OBS-901
Builds on ADR-102 ADR-104 ADR-958
Referenced by ADR-1009 ADR-1012 ADR-979
Link to this decision · In the specification
ADR-971 Mixed versions: an older peer is a missing node, and [map] writes follow the settings-kinds guardthe map reads each peer's part over the cluster channel (Read::MapPart) and [map] is a shared section written through a new managed kind (ManagedKind::Map).
Context
the map reads each peer's part over the cluster channel (Read::MapPart) and [map] is a shared section written through a new managed kind (ManagedKind::Map). During a rolling upgrade some members will not know either (CLU-010).
Decision
- A peer that does not know
Read::MapPartanswers with an error, so its part never arrives and, after three intervals (6 s), it is a missing node: a redresolverwith reasonunreachable,partial: true,missingNodesnaming it. This is the honest reading for the map ("this node's flows are not in it") and it ends with the upgrade. The reason text says the node did not answer the read; it does not claim the node is down. A peer that does know the read and has its map off answersnull, which is also missing after 6 s. - A replica's
[map]write is forwarded to the primary only if the primary runs at least the version that knows the kind (SETTINGS_KINDS_SINCE, 0.8.0, the same guard as[special],[local]and[clients]): 409upgrade_requiredotherwise. Unlike[discovery], the first write is not refused while any member runs an older version:[map]is replicated as a shared section only when it differs from its default (shared::shared_part), and an older replica that cannot read it keeps its own sampler as it was, so the worst case is a replica that samples with its own settings until it is upgraded. (A replica that refuses an unknown shared section falls back to its own file, as for every shared section, CLU-010.) - The gather task that fills the per-peer cache starts on the first read of the map, polls every peer once per 2 s interval (one task per peer, never two at once, 2 s deadline) and stops after 10 s with no read, so a cluster nobody looks at pays nothing; the cache holds the last good part and its age, and the snapshot only reads it.
Consequences
during an upgrade the map shows the not-yet-upgraded nodes as red resolvers; the Cluster page's own version column says why. Tests: obs_901_dead_peer_keeps_tick, obs_901_peer_cache_rules, obs_901_map_part_read_round_trips.
Review amendments (2026-11-18):
- The grace of a peer not heard from starts with the gather task, not with the cache.
PeerCache::restartis called when a read starts the gather, so the first read after an idle spell shows every peer pending (left out, not red, and the snapshot is notpartial) for 6 s while the first round lands; an old part counts as pending in the same window. After it, a peer with no fresh part is missing, whether or not a poll is running (a connected peer that never answers must go red). - A member this node has no stream to but the cluster's health relay reports up (a replica in manual failover sees only the primary; ADR-960) is an
idleresolver with the reasonnot_reachable_from_here, not red:MapParts.unseen, notmissing, and the snapshot is notpartial. A member the relay does not report up stays a redunreachable. - A peer inside its grace is
pending, and the map ispartial. (Replaces the "notpartial" of amendment 4.)PeerCache::viewreturns peers that are connected but not heard from, inside the grace, inMapParts.pending; the snapshot shows each as anidleresolver with the reasonpendingand setspartial: true(missingNodesstays for the red ones only). A cold one-shot read (an agent'snetwork_healthcall after an idle spell) therefore never looks like a whole, healthy single-node network; asking again after a few seconds gets the peers. The federated backend also passesunseenthrough (it dropped it before). - A cached snapshot (under 2 s old) is no longer served once the map is off (
settingsis checked first), and a new stream's first frame skips the empty end-of-stream marker of an earlier map-off. Not changed: after a rise of the privacy level a cached snapshot can still be served for at most 2 s (the sampler purges at once, so the next build is clean); accepted as LOW.
Requirements CLU-010
Builds on ADR-960
Referenced by ADR-996
Link to this decision · In the specification
ADR-972 Offline password reset: the node stopped, the password from stdin or a terminal, sessions ended, auditedT24.7 (fork #4, API-003).
Context
T24.7 (fork #4, API-003). When no admin can sign in there is no way back in today: the setup token exists only before the first admin, and a bootstrap hash is read only while no user exists. The reset has to work with no running API, which is the one place where API-901's UI rule doesn't apply (an inherently offline command, the reason is "nobody can sign in").
Decision
wrendns auth reset-password <user> [-c config]opens<data_dir>/state.dbdirectly (the same open aswrendns run). It takes the data directory's lock (CLU-008) without waiting: a running node holds it, so the command refuses with the holder's pid and host and changes nothing. Stopping the node first is the only supported path (a container: stop it, run the command in a one-off container on the same volume).- A cluster replica refuses. Its users come from the primary (CLU-003), so a local change would be overwritten by the next sync. The message says to reset on the primary.
- The new password comes from stdin as one line (a pipe, a file, or a here-string), or, from a terminal, is typed twice with echo off through
stty. If echo can't be turned off (nostty, as in the image), the command refuses and shows the pipe form; it never echoes. The password is held in a zeroizing buffer and never logged. The same password rules as the UI apply (valid_password). - Effect: the password is replaced (Argon2id, as everywhere), the user's UI sessions end (
delete_user_sessions), and TOTP, roles, and other sessions of other users are untouched. API tokens and HTTP Basic are not revoked (they are a separate credential and an admin revokes them from the UI); the docs say so. - Audit:
user.passwordby the system actorauth reset-password, with{"by":"offline reset","sessionsEnded":n}, target the username. The audit log is the only trace, so it's written before the command returns. - No UI control. The command is inherently offline (the owner's API-901 exception), with this one-line reason; the help topic
password-resetsits on the sign-in page and points at the docs (docs/running.md, "Forgot the password").
Alternatives rejected
a default or printed temporary password (a secret printed to a log or a terminal history); a file option for the password (a file of a secret on disk, and a path the command has to trust); waiting for the lock (the reset would race the server, which keeps state.db open and caches sessions in memory); an in-place reset while the node runs (no API is reachable without a sign-in, which is the case being solved).
Consequences
a person with shell access to the node can always reset a password (they could already read state.db and the key files, so nothing new is granted); a running node must be stopped, which is the cost of the lock; the password never appears in shell history when it comes from a pipe of a variable, but a literal in the command line does: the docs show the variable form.
Test plan. api_003_reset_password_offline_ends_sessions_and_audits (sessions of that user end and only those, the old password fails, the new one verifies, the audit entry is written, an unknown user is refused) and api_003_reset_password_refuses_a_running_node (a held lock refuses and changes nothing).
Requirements API-003 API-901 CLU-003 CLU-008
Link to this decision · In the specification
ADR-973 Router names as device matches: hostname:<label> keys, a group's router_names, read off the query pathT24.9 (fork #6, API-010).
Context
T24.9 (fork #6, API-010). A router that hands out addresses (UniFi, OPNsense, and Home Assistant as a [[router]]) names each device by its DHCP host name, and that name survives an address change. Rules and groups can match only by IP, CIDR, MAC or client ID (FLT-006 deferred hostname matching in T2.5). The owner asked for the router's name to be a match, in the Clients, Groups, rules and query log.
Decision
- Key form. A match key
hostname:<label>in[[client]] match, a rule devicedevices = ["hostname:<label>"], and a group'srouter_names = ["<label>", …](GroupConfig). A label is 1–63 ofa-z,0-9,-, with no leading or trailing-, lowercased on parse;Kitchen Tabletiskitchen-tablet, the same rule device names in DNS use (device_label). The UI converts a name with the same rule. A label that isn't one is a validation error, so an IP, a CIDR, a MAC and anid:can't be confused with it. - Source. The leases the node reads from its routers (own, then peers, CLU-002). An offline entry gives no name (ADR-166), and a lease without a usable label gives none. mDNS names aren't used: the name a router gave is the one this matches. Home Assistant's name, as a
[[router]]answer, counts as a router's (API-012). - Precedence in
ClientTable::identify: client ID, EDNS MAC, neighbor MAC, Kubernetes workload, exact IP, router name (a[[client]]with the key; else the group whoserouter_nameshas it, taking the device as a network does), most specific CIDR,default. (Superseded by ADR-976: the router name now ranks below CIDR.) An exact address always wins over the name the router gave that address. - Off the query path. The device-name task (every 10 s, DNS-023) rebuilds the address → label map from the leases and stores it in one shared
RouterNames(anArcSwap), the same handle the client table and the quick rules read. A query reads it only when some client, group or rule uses a router name (oneArcSwapload and one or two hash lookups; nothing otherwise). A reload builds an empty map in the new table, so names come back within one tick (at most 10 s); the device task re-applies them to each new policy. This is stale by up to 10 s by design, like device names. - Rules with
hostname:<label>match when the device's current router name is that label (read at query time through the same handle, only when a rule uses one). A rule device by name or address is unchanged. - Query log.
client=hostname:<label>(APIGET /api/v1/queries, the UI's Client by → router name filter) resolves to the addresses the router gave that label now, through the same path as a workload's addresses (FLT-017), at most 64. No address → no row. History from before the name changed isn't recovered: a row keeps the address it was logged with (the name is read at read time, as ever). - UI. ClientChip gets "Also recognize it by its router name" (adds or removes that one key beside the device's other keys; other
hostname:keys are kept); the Groups editor gets Router names (in simple view); the quick rule form gets Device by: router name; the query log gets Client by. The help topicdevice-namesays so. - Conflicts. Two devices with one router name (two Androids) both match it, by design: the name is the key. A client key beats a group's router name for the same name, and a group's router name applies only to a device no client names.
Hot path. No allocation or lock on a query that doesn't use a router name: identify tests two HashMap::is_empty (one branch each) and QuickRules::decide tests an Option. A query that does use one reads one ArcSwap and hashes the label. make bench-smoke on this host (Docker Desktop, a 10–20 ms UDP bind) fails its loss gate on both the base commit and this change alike (cache-hot loss 32%); the 50% load points agree (p50 119 µs on both, p99 23–27 ms), so no regression is shown, and the verdict needs quiet hardware.
Alternatives rejected
a separate [[router_match]] table (a second place to keep the device's groups in step with its [[client]]); matching in the DNS device-name table (that table answers the names WrenDNS gives, which may differ from the router's); recovering names from history (a name the router no longer gives shouldn't match now); passing the name through the group API (groups are read as config entries, so the field is in the config schema and the editor reads it there).
Consequences
a router name is one more match that can change when a router's lease changes; that is the point, and the Clients page shows the name the router gave so people can see it. Two integrations' names for one device (UniFi's and Home Assistant's) are one name: the router order (own before peers) decides which address keeps it. Not done: history matching, and matching a Pi-hole import's device names (the importer doesn't read router names).
Review amendments (small-auth-names track, 2026-11-18; ADR-973 amended in place). (a) Spoofing. A host name is chosen by the device, so a device on the network can claim a router name; the docs (running.md "A router name can be claimed") and the device-name help topic say so and recommend MAC or address keys where it matters. (Superseded by ADR-976: the name now ranks below CIDR.) Precedence is unchanged: a router name still ranks above CIDR, so a device on a restricted network that names itself after a looser client takes that client's identity. Ranking the name below CIDR, or flagging name matches in the UI, is left to the owner as an Open question: it changes the precedence in point 3, which the owner has not set. The explain output already carries router_name. (b) Reload. The device-name task remembers the policy it gave the names to by a Weak handle, not by its address, so a freed policy's address can't be reused into a stale "already given". (c) Case. A group's router_names are lowercased on validation and on indexing, as the hostname: keys are. (d) Scope. Router names match IPv4 leases only (router_names() keys on IpAddr::V4); IPv6 clients are never matched by one.
Test plan. flt_006_router_names_match_clients_and_groups (precedence, group membership, the names' cleared state), flt_006_quick_rule_by_router_name, flt_006_router_names_are_labels (config), flt_006_router_names_from_leases (offline, label, own before peers), flt_006_identification_chain, Playwright api_010 match a client by router name (the client, the group, the rule and the query-log filter, with the server's filter checked).
Owner decision (2026-11-18). A router name ranks below CIDR: client ID, EDNS MAC, neighbor MAC, Kubernetes workload, exact IP, most specific CIDR (a [[client]] or a group's network), then router name, then default. A device on a restricted network can't take a looser client's identity by naming itself after it; the name decides only for a device no address, network or MAC names. This replaces point 3's order and closes amendment (a)'s open question. Built in T24.24 (ADR-976).
Requirements API-010 API-012 CLU-002 DNS-023 FLT-006 FLT-017
Referenced by ADR-1013 ADR-976 ADR-983 ADR-994 ADR-996
Link to this decision · In the specification
ADR-974 The parallel race test is judged by outcome; per-query UDP binds in Docker Desktop stay as they areFork #20.
Context
Fork #20. ups_005_parallel_races_and_first_answer_wins failed every time in the wrendns-dev container when the upstream test binary ran in parallel (the parallel group took 200 ms or more; the fast member answers in 5 ms), and passed alone and in CI. Measured in wrendns-dev: UdpSocket::bind sleeps about 10 ms (300 binds take 3.1 s of wall time with about 15 ms of CPU), one at a time across the kernel. Two processes each with seven threads both hit a worst case near 180 ms, so the queue is kernel-wide, not per process. Every test in the binary binds sockets (each fake server, each per-query client socket), so a parallel group's two member sockets queue behind the siblings' binds, and the test's 150 ms bound measured that queue. bench/README.md records the same cost for Docker Desktop, where the server also binds a fresh socket per UDP upstream query.
Decision
- The race test is judged by outcome and a bound the product itself sets: the first good answer is the fast member's, and the group returns before the slow member's own attempt could end (
attempt_timeout, 1 s). A group that waited for the slow member could not return before that cap. The slow member's timeout is set above the cap, so only the group can stop waiting. 2. The fast member's reply is stamped by the fake just before it is sent. The test also requires the group to return within 150 ms of that stamp. This gap has no socket bind in it, so it keeps the 150 ms check's sensitivity to the group's own latency without measuring the bind queue. It does not catch a fan-out delay shorter than the 1 s bound: a hedge of a few hundred ms before the second launch still passes both checks, and separating that from bind cost in this environment needs a quiet-hardware benchmark (open). ups_006_single_member_waits_for_a_slow_answerchecks its 150 ms budget against 500 ms, not 280 ms. Its slow answer arrives at 600 ms, so a group that ignored the budget still fails.
Checked: the correct group passes 20 of 20 parallel runs; a group that waits for every member fails at 1.00 s.
- The product is not changed. The group already returns on the first good answer and detaches the other attempts (ADR-013). Each UDP query keeps a fresh socket and a random source port (RFC 5452).
Consequences
In Docker Desktop each UDP upstream query still waits for its socket bind, so cache misses top out near 100 a second (bench/README.md). Removing the bind from the query path (for example, a stock of pre-bound sockets, each used once, so the source port stays random per query) changes the upstream hot path and needs the owner's decision and a benchmark on quiet hardware (T24.22). Open, not decided here.
Alternatives rejected
raising the 150 ms bound (it measures the environment, and the owner asked for the cause to be fixed); reusing a socket per upstream (weakens source-port randomness, RFC 5452); running the parallel test alone or with --test-threads=1 (hides the race and leaves the bind cost in the product's tests unexamined).
Evidence
wrendns-dev runs of target/.../upstream before and after (issue #20); the bench/README.md note on Docker's bind cost.
Owner decision (2026-11-18). Accepted as built (no product change). The pre-bound one-use socket stock is T24.25: built behind a benchmark on quiet hardware (with T24.22), and merged only if it beats the current path on Linux and in Docker.
Builds on ADR-013
Link to this decision · In the specification
ADR-975 Failover with a VIP: keepalived beside each node in its network namespace, a readiness and DNS health check, the wildcard listener, and a witness for two-node promotionT24.4 (fork #1; CLU-004, OPS-001).
Context
T24.4 (fork #1; CLU-004, OPS-001). A Pi-hole pair moves one VIP between its two hosts with keepalived, so devices keep one DNS address. WrenDNS needs the same behaviour, and its DNS must never depend on a discovery, cluster or API failure (CLU-004). The task asks for a Docker example with keepalived for a two-node pair, the listener on the wildcard address so the VIP answers, a runbook for moving a Pi-hole pair's VIP, and a witness package for two-node clusters. It has no UI. Where the text leaves room, the conservative choice is recorded below.
Decision
- No new WrenDNS mechanism. The VIP is held by keepalived, not by the node. The DNS listeners bind the wildcard address (the default
0.0.0.0and::; the example sets[[listen]]explicitly), so the node that holds the VIP answers on it, and each node also answers on its own address. A listener bound to a single address does not answer the VIP; the runbook says so. - Health check = readiness plus a DNS answer. keepalived keeps the VIP only while
/readyzanswers 200 and the node answers the probe nameprobe.wrendns.invalidon its own listener (the watchdog's probe, answered locally as NXDOMAIN)./readyzanswers 503 in maintenance (OPS-010), so a node in maintenance hands the VIP to its peer while it keeps answering the queries that still arrive. - keepalived shares the node's network namespace in a container (
network_mode: service:keepalived-*), so the VIP lands where the node listens. On a host install, keepalived runs on the host beside the node. The sidecar needsNET_ADMIN,NET_BROADCAST,NET_RAW,SETUIDandSETGID(keepalived runs its check as root). The node runs as its image user, withnet.ipv4.ip_unprivileged_port_start=0set on the shared namespace, as the Pi docs set it on the host. Restarting the sidecar restarts the pair (the runbook). - Node identity by NSID. Answers name the node in the NSID option (
[dns] nsid), which stays per node inside a cluster; a shared local record would be the same on both nodes once the primary's configuration applies. - Witness package. A
wrendns-witnessservice in the example's compose file, behind thewitnessprofile: a vote-onlycluster witnesswith its own address on the network and no DNS, API or VIP. It joins with a witness token from the primary (CLU-005). The VIP moves on health whatever the cluster decides. - Unicast VRRP on the Docker bridge (
unicast_src_ip,unicast_peer); the LAN runbook may use multicast. - Proof, not a claim:
deploy/keepalived/e2e.sh(CI jobkeepalived) builds the image, forms the cluster, checks each node and the VIP, kills the master, checks the takeover (within 15 s, every later query answered by the peer) and the promotion, restarts the master (the VIP back, a replica), and runs a maintenance hand-over through the API.
Gaps and conservative choices (for the owner):
- VRRP in the example is unauthenticated (keepalived's
auth_type PASSis deprecated). The runbook says to keep VRRP on the LAN interface and not to route it. Authenticated VRRP is an owner decision if the LAN is not trusted. The runbook offers a dedicated VLAN or aniptablesrule that drops VRRP from anyone but the peer, as the interim limit. - The example's subnet is
10.231.250.0/24: not a typical LAN, and not another compose project's network. The script stops if a Docker network already uses it. Changing it means changingcompose.yaml, both node files ande2e.sh. - The e2e makes an admin with the setup token and signs in with a session. The API refuses HTTP Basic unless
allowBasicApiis set, and the example does not set it. - The LAN variant of the example (keepalived and WrenDNS on a host or a macvlan, with the LAN VIP) is documented as a runbook and has not been run on a LAN.
Alternatives rejected
- A VRRP implementation inside WrenDNS: keepalived is the proven one, and a second VRRP speaker in the DNS process would add a privileged path beside the query path.
- Host networking in the example: it would touch the real network. The isolated bridge tests the same mechanism.
- A macvlan network in
compose.yaml: it ties the example to one LAN. The runbook covers the LAN. - Multicast VRRP in the example: Docker bridges don't reliably carry it, and unicast is what is tested.
Test plan
deploy/keepalived/e2e.sh on the isolated bridge, run locally (five complete local runs with the final checks, and the hosted runs, with the same checks: the takeover took 3.2 to 6.8 s, with 0 to 2 probes lost before the first answer; the promotion to epoch 2, the VIP back on the primary, and the maintenance hand-over all passed), and the keepalived CI workflow on every change to the example, the sources or the Dockerfile.
Consequences
an operator who wants a VIP runs keepalived beside WrenDNS (or in the example's sidecar), and restarts them together. No code, dependency or hot-path change, so no image delta. The example's keepalived image is a separate 33 MB image, used only by the example and its checks.
Requirements CLU-004 CLU-005 OPS-001 OPS-010
Link to this decision · In the specification
ADR-976 Router name ranks below CIDR in identify; a group's network also takes the device firstT24.24, ADR-973's owner decision (2026-11-18): a router name ranks below the most specific CIDR and above default.
Context
T24.24, ADR-973's owner decision (2026-11-18): a router name ranks below the most specific CIDR and above default.
Decision
ClientTable::identify tries the name after the exact IP and the most specific [[client]] CIDR. "CIDR" also covers a group's networks, which the owner paragraph names; when one holds the device (net is set) the name is not consulted, so a name can't move a device out of a network's group. The name still decides for a device in no network. Quick rules by router name are unchanged. This is the conservative reading of "a group's network".
Hot path
the same branches in a different order; one extra Option::is_none test before the name lookup, nothing allocated.
Consequence
a [[client]] keyed only by hostname: does not match a device inside a group network; key it by address or MAC there.
Owner decision (2026-11-18). Accepted as built: any network a [[client]] or a group names beats a router name, so a device inside a named network is never identified by its router name. Router names identify only devices outside every named network.
Builds on ADR-973
Referenced by ADR-1047 ADR-973 ADR-996
Link to this decision · In the specification
ADR-977 Guarded changes as built: the codes, the limits and the framework's seamsT27.13 (API-902; ADR-914, ADR-956, ADR-957).
Context
T27.13 (API-902; ADR-914, ADR-956, ADR-957). The task fixes the behaviour; a few details it left open were decided conservatively while building it.
Decision
- Problem codes. The framework adds 409
guarded_only,guarded_change_pending,preview_stale,primary_unreachable,would_disconnect_you,would_lock_out_admins,no_supervisor,target_not_empty,acknowledgement_required,clustered_node,restarting,rotation_incompleteanddata_dir_not_persistent, and 421not_primaryfor a request that names another node and arrives at a replica (the detail names the primary). 403reauth_requiredandagent_not_allowedare the existing codes. The last four are used by T27.14 to T27.17 rows; they exist now so the problem list does not change as rows are added. - Rate limits. Guarded previews and applies share one limiter of 30 requests a minute per session; failed confirmations are counted separately (5 in 10 minutes block the session, 429), as ADR-956 says.
- Framework hooks.
crates/wrendns/src/guardedcarries#![allow(dead_code)]for the hooks that only the T27.14 to T27.17 rows and the test rows use (a window row's sockets, the bind fallback,CheckCx). Remove the allow when those rows land. - Test rows and hooks (
e2e.rs, the test registry rows) compile only under the cargo featuree2e;TT_E2E_RESTART_HOOKandTT_E2E_CONFIRM_WINDOW_SECSare read only in that build, so no environment variable changes a release binary (api_902_test_row_absent_in_release). - Names in phrases (revised by the review of 2026-11-18). A node goes by its node ID in a phrase, a preview, a stored entry (
<node-id>/<setting>), a forwarded request and the sender check; a standalone node goes by its configured name (or hostname). The site label is a display label only: it is not unique (every pod of the Helm chart is in sitek8s), so keying on it would share an entry between nodes, let the primary change or restart itself when the admin picked another pod, and let a replica in the primary's site pass the sender check. A target accepts an assertion only when the connection's mTLS-authenticated node ID is the primary's node ID that it knows. (The assertion is still signed with the cluster key, as every manifest is; per-node signing keys are not added.) Residual (corrected 2026-11-18, owner to accept): the node ID in the mTLS certificate is a SAN signed by the cluster CA, and a replica that is eligible to become primary holdsca.key(node.rs), so such a replica can mint a certificate carrying the primary's node ID and then forge an assertion. The sender check therefore stops a replica that holds only the cluster signing key, a non-eligible replica, and a mistaken or stale sender; it does not stop a compromised CA-holding replica. The residual is the cluster's existing trust in a CA holder (which can already join, impersonate and sign manifests as the primary), not a new one. Closing it needs a per-node assertion key registered with the primary's manifest; that is deferred and listed for the owner. - The window's proof listener serves only the confirm route, the web UI's own files (
GET/HEADof paths outside/api,/mcp,/metrics,/admin,/auth,/.well-known) andGET /api/v1/auth/status(the page's first read, which signs nothing in), and speaks TLS exactly when the main API listener does (the new certificate for anew_certrow, throughHost::proof_socket_with), tagging requestsTlsConnection. It has no sign-in or session route, and never serves a page in the clear when the API is HTTPS-only (API-003, ADR-149). - The confirm route judges a request that carries a
confirmTokenby the token alone (a session cookie sent along is ignored, since cookies are not port-scoped and a stale one would fail a valid token); a bearer token or Basic credentials are still checked and an agent's is refused. Aproxy_listproof needs the request's peer to be one of the new proxies and the client address under the new list to differ from the peer. - A replica's staged entry is read from the node-managed blob the replica last applied (a replica has no row of its own); the probation state, the local clear and the dropped-after-two-failed-starts decision are node-local notes in
state.dbkeyed by the entry's value digest (guarded.replica_states,guarded.suppressed), so the primary's copy is never touched. An offlinewrendns guarded clearon a replica queues a removal (guarded.removals) that the node sends to the primary (KIND_ENTRY, audited there assettings.guarded_cleared) as soon as it is started and connected; the local suppression then ends. - A replica's
immediatechange is answeredappliedonly after the primary's version carrying the entry has reached the replica (up to 20 s,Host::wait_applied); otherwise 503unavailablesays the primary recorded it and it applies when it arrives. - The bind fallback at start is wired: a start that fails to bind a listener (
AddrNotAvailable,AddrInUse,PermissionDenied) while a confirmed (active)window/new_socketentry of the node exists sets those entries aside for that start, rebuilds the configuration and starts once more on a fresh runtime (guarded::serve_with_fallback). - The restart warning counts resolvers of the node's own site that are up and not witnesses ("a site's only healthy resolver"). A node that is running but unhealthy with a staged entry keeps it until someone restarts it: the server never restarts on its own (
docs/recovery.md). - Plans naming a config path (review item 11) are not extended: no REST route maps onto a dotted config path until T27.14 to T27.17 add the rows, and those tasks add the refusal with their route;
is_guarded_pathkeeps refusing/api/v1/guarded*.
Consequences
no new dependency; no hot-path change (wrendns-proto, -net, -cache, -filter, -policy, -telemetry are untouched); image delta not measured on this host (no image build; code only, no Cargo.lock change).
Owner decision (2026-11-18). The residual in point 5 is accepted: a compromised replica that holds ca.key can forge a guarded assertion, as it can already impersonate the primary in other ways. Per-node assertion keys, registered at join so that a certificate alone isn't enough, are T27.19.
Requirements API-003 API-902
Builds on ADR-149 ADR-914 ADR-956 ADR-957
Link to this decision · In the specification
ADR-978 A guarded entry is never part of the replicated shared part, and the sidecar stays in the file-named directoryADR-956 §2 and §6 say the entry is node_managed and that the probation counter must survive a state.db that will not open.
Context
ADR-956 §2 and §6 say the entry is node_managed and that the probation counter must survive a state.db that will not open.
Decision
The guarded kind is exported in the node-managed blob like the other node kinds, but a node reads only entries whose node part is its own name and ignores the rest. The probation sidecar guarded-probation is written beside the file-named data_dir (not a pointer target) and is fsynced before any guarded value applies. An entry the CLI cleared on a replica is suppressed locally until the primary's copy changes (ADR-957).
Consequences
an N-1 node that does not know the kind ignores it (clu_010_guarded_entry_ignored_by_n_minus_1). A replica reads its own entries from the blob it applied under its node ID (ADR-977 points 5 and 8).
Builds on ADR-956 ADR-957 ADR-977
Link to this decision · In the specification
ADR-979 The network map page as built: stream when unfiltered, poll when a server filter is set, no domain names so Explain opens with the device onlyT26.3 (OBS-901) built the map page on the T26.2 API (ADR-958, ADR-970).
Context
T26.3 (OBS-901) built the map page on the T26.2 API (ADR-958, ADR-970). Four points were left open by the ADRs or differ from them; each takes the most conservative reading and is recorded for the owner.
Decision
- Stream when unfiltered, poll when a server filter is set. ADR-958 section 5 says the stream is unfiltered and "the UI filters the stream's snapshot client-side", while the task text says the filters are "sent to the server". Both hold: with no
network,group,deviceornodefilter the page uses the stream (and filters thehealthchoice on its side); with any of the four set it pollsGET /api/v1/mapwith them every 2 s (paused while the tab is hidden), so the server's view (every device, not only the 200 busiest that the stream carries) is what is drawn. The page also polls when the stream is refused (429 map_streams_busy, or three failed reconnects) and tries the stream again when the tab comes back. A client-side filter (filterSnapshot) exists for the state filter and is tested as a pure function; it is not applied on top of a server-narrowed read, so the two can never disagree. - Explain opens with the device, not a name. The map never shows a domain name (ADR-958 section 7), so a click-through to Explain can only carry the device:
#/explain?client=<address>, which fills the device field and leaves the name for the person to type. Anomalies opens#/anomalies?client=<address>, a new device filter on that page (it shows one device's findings and a "Show all devices" link). Queries opens#/queries?client=<address>as before. At privacy level 2 and above a device has no address and no click-through. - A device's switch and port are drawn only when the snapshot carries them.
MapNodehas noviaorportfield today (M25's inventory data is not part of the map API), so nothing is drawn for them in a real snapshot. The page reads optionalviaandportstrings on a node and shows "Connected through <via>, port <port>" in the node's panel when present (a mocked test covers it). Adding the fields to the API is a change to T26.2's schema, left to a later task; step 9 of T26.3 is therefore met as the task words it ("only when the inventory carries it") and recorded as not exercised against a real node. - Colour, shape and words. The four states are a circle with a check (OK), a triangle (Warning), an octagon with a cross (Failing) and a dashed circle (Idle), each with its word on the node, in the node's accessible label, in the legend and in the table view. Node outlines, shapes and pulses take the existing
--ok,--warn,--bad,--mutedtokens and their-strongforms; a Playwright test measures the contrast of every one against the node's surface in both themes (3:1 for shapes, outlines and pulses; 4.5:1 for text).
Alternatives rejected
filtering the unfiltered stream for every filter (a device outside the 200 busiest could not be found); sending the stream's filters to the server (ADR-958 fixes the stream as one shared snapshot for all subscribers); a free-text domain box on the map's Explain link (the map holds no names); drawing via from /api/v1/clients (an extra read per refresh for a field the API does not yet join to the map's devices).
Consequences
while a server filter is set the page polls (a read every 2 s, served from the ticker's snapshot when unfiltered and built on demand, at most 4 at a time, otherwise), which the T26.2 route already bounds. The page's code is a lazy chunk of 10.8 KiB gzipped (script 9.8 and styles 1.2), the dist total moves from 341.9 to 353.5 KiB gzipped (+11.6 KiB), no new dependency and no image-size change beyond those bytes; no hot-path crate was touched, so make bench-smoke was not run.
Requirements OBS-901
Link to this decision · In the specification
ADR-980 SNMPv3: the HMAC key copy is not zeroized, passwords need 8 octets, rediscovery cannot move the clock backThe review of T25.5 (DSC-003, ADR-908, ADR-931) found three points the code did not settle.
Context
The review of T25.5 (DSC-003, ADR-908, ADR-931) found three points the code did not settle.
Decision
- HMAC key state.
ring::hmac::Keykeeps key-equivalent padded state and does not zeroize it on drop. The crate builds one per MAC and drops it at once. The localized keyKulandKustay inZeroizing. The ring copy is accepted: the process holds the plaintext password in aSecretValueanyway, ring offers no zeroizing key, and a hand-written HMAC would replace a reviewed implementation with ours. - Password minimum. Passwords under 8 octets are refused (RFC 3414 §11.2; net-snmp does the same):
Agent::new,UsmUser::deriveandusm::check_passwordreturn a refusal with the reasonRefused::ShortPassword, which the T25.8 credential form shows. - Rediscovery. The agent keeps the engine as last seen in an authenticated message (
trusted). A discovery Report (unauthenticated) for the same engine ID that is behind it (RFC 3414 §3.2.7b window) is refused (usm::discovery_allowed), so a spoofer cannot rewind the clock through rediscovery. A forward move (a reboot) is taken. A different engine ID drops the trusted copy. - Agent clock behind the estimate (fix a, 2026-11-18). The client's estimate of the agent clock runs ahead of an agent whose clock is slow or was paused, so an authenticated reply or Report could be more than 150 s behind the estimate for good, and rediscovery brought back the same trusted engine and estimate (a lock-out).
Enginenow keepslatest, the boots and time of the last authenticated message (RFC 3414 latestReceivedEngineTime; discovery never sets it). In the same-boots, behind-the-window caseEngine::windowreturnsResyncwhenlatestis set for those boots and the message time is later than it, as RFC 3414 §3.2.7b specifies, andStaleotherwise. A replay or a clock older than anything already received stays refused, so the clock never goes back past the last authenticated value.resyncand in-window messages updatelatest(note_receivedonly moves forward). Option (b), clearing the trusted engine after N stale results, was not chosen: it would let repeated unauthenticated noise erase the rewind protection. Remaining limit: an agent whose clock really is behind its last authenticated time stays refused until it catches up (indistinguishable from a replay).
Not done
counting unauthenticated Report OIDs as an operator hint (review item 13, optional). A wrong password and an unknown user both show as a timeout, deliberately: an unauthenticated Report must never drive behavior, and showing it risks an oracle for user names. Open for T25.8 if the owner wants it.
Test plan
dsc_003_rediscovery_cannot_move_the_clock_back, dsc_003_empty_password_has_no_key (short passwords), dsc_003_rfc3414_sha256_key_vector, dsc_003_slow_agent_clock_resyncs_but_never_below_the_latest_received (unit), dsc_003_agent_clock_behind_the_estimate_recovers and dsc_003_agent_clock_never_goes_back_past_the_last_authenticated_value (loopback; the estimate is aged 400 s through the hidden Agent::age_engine_estimate).
Consequences
passwords under 8 octets in existing credentials stop working. No dependency, no hot-path change, no image delta.
Note at merge (2026-11-18). Since review round 4, discovery_allowed reads latest through window: an unauthenticated same-ID discovery behind the estimate but later than the last authenticated time is accepted for one exchange (it never sets latest or trusted, and never goes below latest). Item 3's "behind it is refused" means behind the last authenticated time.
Requirements DSC-003
Link to this decision · In the specification
ADR-982 Group rewrites as lines, and the block-response fields shown in SimpleT27.4 (FLT-014, API-901) adds the rewrite[] editor and the group fields block_ips, block_ttl, ede, ede_text and rebinding_allow to the Groups form.
Context
T27.4 (FLT-014, API-901) adds the rewrite[] editor and the group fields block_ips, block_ttl, ede, ede_text and rebinding_allow to the Groups form. Two choices were not fixed by the spec: how a list of {domain, answer} pairs is edited, and whether the block-response fields sit under Advanced. The owner's rule that Simple "never hides something that changes behavior" (ADR-036, API-011) decides the second.
Decision
rewrite[]is edited as lines, one per line:name answer(two whitespace-separated words). The form checks each line with the server's rules (validate.rsrewrites): the name,*.for a wildcard, the answer as an address or a name, and no name rewritten twice in the group. A bad line stops Check and is named; the server's check stays authoritative.rebinding_allowandblock_ipsare plain line lists with the same kind of check.block_ttlis a number with the server's 0 to 86400 bounds (the form enforces them withmin/max).block_ips,block_ttl,edeandede_textare shown in Simple, not Advanced, because they change what a blocked name gets back.block_modemoves to Simple with them, so the block answer is in one place.rebinding_protectionkeeps its Advanced placement: moving it is the owner's call under the same rule (Open).- No server change: the config schema, the OpenAPI document and the MCP catalog already carry these fields, so nothing is regenerated.
Consequences
a rewrite is a short text line, easy to paste and to read in Git. The form and the server can disagree only on a rare edge the server reports on Check. The Groups page gets a longer form; the block fields are grouped with the block answer.
Alternatives rejected
a row editor with two inputs per rewrite (more code for the same data, with no gain for a list that is usually short); keeping the block fields under Advanced (it hides behavior from Simple users, against the rule above).
Test plan
Playwright flt_014 add a rewrite to a group (a malformed line, a duplicate, a valid rewrite answered by DNS and shown by Explain, then removed) and flt_014 group block ttl and ede (the TTL bound in the form, the TTL and EDE code in a blocked answer, the saved values read back).
Open
whether rebinding_protection, dns64 and filter_aaaa (Advanced today, and each changes behavior) should also move to Simple under the owner's rule.
Requirements API-011 API-901 FLT-014
Builds on ADR-036
Link to this decision · In the specification
ADR-983 IPv6 device names: addresses ride on the IPv4 lease, usable ones only, one device per addressT24.8 (fork #5; DNS-023).
Context
T24.8 (fork #5; DNS-023). Routers know devices by IPv4 address and MAC, and the device-name table (ADR-901) is keyed by IPv4 address. UniFi also reports each connected client's IPv6 addresses (ipv6_addresses in stat/sta). The owner wants AAAA and ip6.arpa PTR answers for those devices, with the IPv4 rules for names, offline clients and labels (ADR-166, ADR-901). ADR-973 keeps router-name matching IPv4-only.
Decision
- The addresses ride on the lease.
Lease.ipv6(up to 4, sorted, deduplicated; empty is not written, so the wire form to older peers is unchanged and an older peer's answer is a device with none) is filled inrouters::rebuildfrom every router's answer for the lease's MAC, so a Home Assistant name takes the addresses UniFi reports for the same MAC. A device with no IPv4 lease (an IPv6-only client) is not named: the key of the lease table, the label rules and the collision rule are all per IPv4 address, and changing that would change every consumer (identify, discovery, the API). The SNMPipNetToPhysicalTablesource waits for M25's poller. - Usable addresses only (
devices::usable_ipv6): link-local (fe80::/10, the same on every link), loopback, multicast, unspecified and IPv4-mapped addresses never name a device; global and unique-local addresses do. At most four per device (privacy extensions make a device carry several); the lowest four by value, so the same input gives the same table. That choice is arbitrary: UniFi does not mark temporary (privacy) addresses, so a device with more than four may publish rotating addresses and drop a stable one (accepted; a stability preference needs a source that reports it). A rotated address the router still lists can answer for a short time (TTL 60 s). - Same rules as IPv4. An offline client (ADR-166) has no addresses and no name. A name that loses a label collision (ADR-901) loses its addresses too (no half-registered name). One IPv6 address names one device: the device that wins the ranking keeps it, others get neither the AAAA nor the PTR for it.
- Built off the path.
device_dns::namesreturnsNamed { name, ip, v6 };LocalData::from_device_namestakesIpAddrs and adds A or AAAA and the PTR (in-addr.arpaorip6.arpa) for each. The query path is unchanged: the sameLocalDatalookup, behind the same single branch and lock-free load, with more entries. - API and UI.
GET /api/v1/dhcp/leaseslistsipv6(omitted when empty); the Clients Discovered table and the Networks device list show it; help topicdevice-ipv6.
Alternatives rejected
keying the table by MAC (a larger change to every consumer, and mDNS has no MAC); publishing link-local addresses (they answer the same on every link, so a name would point at the wrong device from another network); publishing every address a device reports (privacy addresses rotate, and a long AAAA list slows clients that try each one).
Consequences
a dual-stack device answers AAAA within about 10 s of a router read; an IPv6-only device is still unnamed (open until the SNMP source or an IPv6-keyed table); router names for hostname: matching stay IPv4-only (ADR-973).
Requirements DNS-023
Builds on ADR-166 ADR-901 ADR-973
Link to this decision · In the specification
ADR-984 Event sinks and the OTLP export as admin-only node-managed kinds, merged apart from their file sectionsT23.11 (API-016, OBS-010, OBS-006; ADR-903 §6-7, ADR-914) makes [[telemetry.sink]] and the OTLP destination changeable from the UI and API.
Context
T23.11 (API-016, OBS-010, OBS-006; ADR-903 §6-7, ADR-914) makes [[telemetry.sink]] and the OTLP destination changeable from the UI and API. ADR-903 fixes the broad shape (a sink and an otlp kind through node_managed, token_ref and header_refs, files win, resolver pods skip what needs a stored secret) and T23.10's ADR-967 and ADR-968 built the machinery for OIDC providers (rows in managed, one more blob in the signed manifest, a merge apart from the shared part). It leaves open how a sink or the export sits beside the file's [telemetry], which fields the API may set, how the files win for a one-entry kind, who reads, and what an agent sees.
Decision
- Two kinds.
ManagedKind::Sink(PUTandDELETE /api/v1/sinks/{name}; rowssinkby name) andManagedKind::Otlp(PUTandDELETE /api/v1/otlp/default; one row,otlp/default). Both are innode_managed::KINDS, so they replicate innode-managed.json(ADR-968), are seeded into a promoted primary once, validated entry by entry (a bad one is dropped alone, CLU-004) and ignored by a node that predates them (CLU-010). Writes are admin-only: an operator is 403, an agent is refused (no scope; the agent defaultNeed::Forbiddenfor writes), and a forwarded write without a role (an older node) is 409upgrade_required, as for routers and providers. - Reads are for every signed-in role.
GET /api/v1/sinksandGET /api/v1/otlpcarry names, settings, status and the dropped count, never a value (an operator sees telemetry read-only, the owner's AC). An agent withconfig:readmay read them, and the MCP toollist_event_sinksis the same two reads; no tool or scope writes them (ADR-903 §5).GET /api/v1/config/entries?kind=sinkalso lists the sinks (the files' asfile, the UI's asadded), so the generic entry editor (ConfigEditor, with the newfileReadOnlyand per-fieldshowIf) is the sinks' form; the OTLP card is its own component because its headers are a map. - Merged apart, never into the files' lists.
TelemetryConfig.managed_sinkandmanaged_otlp(both#[serde(skip)],#[schemars(skip)], so the schema,shared_partand the config reference are unchanged);all_sinks()andotlp_effective()are the readers (secret references, the credential table, the sinks applier, the OTLP exports,/metrics). A node-managed entry is never validated with the files' lists, so a bad one cannot make the merged configuration fall back to the files. The files win: a sink named in the files is read-only (409set_by_file; a blob entry of that name is left out); the OTLP export is the files' whenever they set anendpoint,headersorheader_refs(409set_by_file, the whole destination), otherwise the UI'sendpoint,interval_secsandheader_refsapply over the files' trace settings.interval_secsalone in a file does not count as setting a destination. - References only; no path the API can set. The body of a sink has the
[[telemetry.sink]]fields excepttoken_fileandtls_ca(422: a path the API can set is a path an admin can point at any readable file, ADR-921's reason), andtoken_refnames a stored secret (422secret_missing; a reference moved to a secret another kind uses is audited ascredential.redirect). The OTLP body hasendpoint,interval_secsandheader_refsonly: inlineheadersand the trace settings are 422 (an inline value would sit in the audit log and the blob; traces are read at start). No password in any URL (url,address,endpoint; 422), so nothing in a body or a blob needs redaction. The blob's secret check (SECRET_FIELDS) addstoken_file,tls_caandheaderstoclient_secretandclient_secret_file: exported without them, refused when found. Header names exclude those the export sets itself (content-type,content-length,host,user-agent,transfer-encoding,connection). - A file sink is a file name.
pathis 1-64 characters of letters, digits,.,_,-, not hidden, not ending.spill,.posor.tmp, and not ending.<digits>(a file rotates toa.1,a.2, so another sink's file can't be named like that); it is written under each node's<data_dir>/sinks/(resolved at merge, per node, so a replica never receives the primary's directory). The list and the entry editor show the bare name. - Bounds. At most 16 sinks made in the UI,
max_bufferat most 100,000 (a bounded channel allocates its capacity: 16 sinks at the limit are about 50 MiB of channel, not 0.5 GiB) andspill_max_bytesat most 1 GiB, so a body cannot make a node allocate without limit. The files' own values are not bounded by these. - Resolver pods. A sink that names a stored secret, and an OTLP export with
header_refs, are not started on an ephemeral member, with one info log; the lists say why (running: falseandreason; OTLPactive: false). The merge still carries the entry (so the UI shows it), and the applier is what skips it. - The restart-only list shrinks.
restart_only_changescompares[telemetry]without the sinks, the OTLP destination, interval and headers (which now apply on reload), so a reload no longer warns "takes effect after a restart" for them. The trace settings, dnstap, ring and query-log settings are still read at start.
Also
a sink that arrives by a replicated blob or a stored row meets the same limits as the API's (file name, sizes, no password in an address, at most 16), and is dropped alone when it doesn't (CLU-004). The Telemetry tab is shown from operator up, as the owner's acceptance criterion says ("an operator sees telemetry read-only"); the server lets a viewer read the two lists, and the tab stays operator-gated like the Integrations tab (a viewer sees no settings tabs); widening it is a one-line change if the owner wants it.
Consequences
sinks and the export follow every source of configuration (a file and SIGHUP, an API write, a replicated blob) without a restart; the schema is unchanged; the secrets never leave the store. Rejected: writing into telemetry.sink (a bad entry would fail the whole merge, as ADR-967 found for providers), letting the API set token_file or tls_ca (it would make the API a reader of any file; a private-CA syslog collector therefore stays a file setting), taking inline OTLP headers (the audit log and the blob would hold them), and a per-header file-versus-UI merge for OTLP (a half-file destination is harder to explain than "the file sets it").
Not done (Open, for the owner): trace settings (traces_sample_every, traces_slow_ms) are not editable in the UI and are read at start; a private CA for a syslog-over-TLS sink is file-only; a mixed-version cluster has no 409 for sink and OTLP writes sent to a primary that predates them (it refuses an unknown kind, as it does for OIDC providers today).
Requirements API-016 CLU-004 CLU-010 OBS-006 OBS-010
Builds on ADR-903 ADR-914 ADR-921 ADR-967 ADR-968
Referenced by ADR-1004 ADR-1007
Link to this decision · In the specification
ADR-985 Sinks are started and stopped by a manager off the query path; the aggregator takes the new list once per batchT23.11 asks for sinks that change while the node runs, with DNS never blocked or slowed (NFR-007, AGENTS rule 5, ADR-903 §7).
Context
T23.11 asks for sinks that change while the node runs, with DNS never blocked or slowed (NFR-007, AGENTS rule 5, ADR-903 §7). Before it, sinks::start built the sinks once, DROPS was a OnceLock, and a sink's spill file was keyed by name alone. The aggregator's sink list (EventSinks.outs) is touched only by the aggregator thread, which also feeds the query log.
Decision
- A manager, not a lock.
sinks::Managerowns the running sinks (each a thread and a bounded channel,max_buffer) and is driven by one applier task (sinks::run), woken by every configuration reload (a file, an API write, a replicated blob) and debounced by 250 ms.applyruns on a blocking thread, never on a request path, a reload or the aggregator. It diffs the wanted sinks against the running ones (settings, node name and data directory), keeps the unchanged, retires the removed and changed ones, starts the new ones, and sends the aggregator the newVec<Out>through a stdmpscchannel. - The aggregator reads it with
try_recv, once per batch, inSink::tick(the aggregator callstickafter every drain). No lock, no allocation per event, no wait:wrendns-telemetryand theSinktrait are unchanged, and anEventSinksalways exists (with no sinks it returns at once fromrecord). A sink that stays keeps what has been reported of its drops. - Retiring. A
Control(stop flag, remove flag) tells a thread to send what it holds and end: a file or syslog sink writes what is queued; a webhook sends everything queued in chunks ofbatch, one try each and no wait between tries, and what it cannot send is dropped and counted (for a removed sink) or kept on disk (for a sink being replaced that keeps its spill). The threads notice a stop within a second (every wait is at most 1 s).applywaits for them up to 2 s before it starts the new ones (so two threads never share one sink's kept batches); a thread still sending after that is left to end after its attempt (stragglers). Events the aggregator offers a stopping sink in that window are counted as dropped once its queue is gone. - Kept batches belong to a name and a URL.
<data_dir>/sinks/<name>-<12 hex of BLAKE3(url)>.spill. A sink whose key changes or that is removed has its files deleted when its thread ends (theremoveflag), so a name re-used for another collector never replays the old one's events (the AC). Files from before this change (<name>.spill) are renamed to the hashed name by the sink of that name when it starts. - Drops only grow. The manager keeps one counter per sink name for the life of the process, shared by every incarnation of the sink and kept while it is removed, so
wrendns_sink_dropped_total{sink}is monotonic across reloads, changes, removal and return.drops()(for/metrics) reads the manager's swappable list. - A sink that cannot be built is left out alone (a bad CA file, no path, an unusable address, no HTTP client), with its reason in
GET /api/v1/sinks, and the rest start. The building (TLS config, client) is done before the thread starts, so the reason is known to the API. - Credentials are read per batch (already so for
token_refandtoken_file; OTLP'sheader_refsper export): a rotated secret needs no reload. The OTLP metrics task re-reads the configuration every interval and on a wake-up (otlp_changed), so an endpoint added, changed or removed applies at once; it starts its interval over on a change. - Performance: nothing is added to the hot path. The per-event work in
EventSinks::recordis unchanged; the swap is onetry_recvper 25 ms batch.wrendns-telemetry,wrendns-proto,wrendns-net,wrendns-cache,wrendns-filterandwrendns-policyare unchanged. - A stopping writer has a deadline. A webhook told to stop has
RETIRE_WAIT(2 s) in all: past it, what is still queued goes to the kept batches (no network) or is counted dropped. When the manager gives up on a thread it setsabandoned: that thread never touches the kept batches again and never deletes them, so it can't corrupt or remove the files of the sink that replaced it. A request already in flight ends within its own timeout; the straggler holds at most the batch it is sending. - One configuration per export round. The metrics and trace loops read the address and the headers from the same configuration snapshot each round, so a collector that has just been changed never gets the old one's address with the new one's credentials, and an export turned off sends nothing.
Consequences
a sink or the export is added, changed or removed without a restart and without touching DNS; the aggregator never waits for a sink; the metric never resets. The cost is that a changed sink restarts (its in-memory buffer is flushed with one try and the rest is counted as dropped), and a stop takes up to 2 s to finish on a collector that is down. Rejected: a lock around outs (the aggregator would contend with the applier), swapping the whole sink list inside the telemetry crate (a hot-path crate for a cold change), joining without a limit (a dead collector would hold the applier for a webhook's 15 s timeout), and resetting the counter on a change (a Prometheus counter that falls is read as a restart).
Requirements NFR-007
Builds on ADR-903
Link to this decision · In the specification
ADR-986 Sync 2026-11-18: upstream's M24 and its T22.2 take the fork's numbering, M30 and T29.2the sync of upstream 095b77f brought a milestone "M24 — Query-log negation and a cluster-wide support package" (tasks T24.1, T24.2) and a task T22.2 (a second icon pack) under upstream's M22.
Context
the sync of upstream 095b77f brought a milestone "M24 — Query-log negation and a cluster-wide support package" (tasks T24.1, T24.2) and a task T22.2 (a second icon pack) under upstream's M22. The fork already has M24 (Replacing Pi-hole, T24.1 to T24.25, referenced in code, tests, ADRs, the README and by the wave-o tracks that are changing the fork now) and M22 (home integrations, with its own T22.2). The sync procedure says to rename on a collision. At the 2026-11-17 sync the upstream milestones that collided (M22, M23) took the fork's free numbers (M29, M28): the tree and spec/10 show that.
Decision
- Upstream's M24 is M30 here: T30.1 (the "not" filters, ADR-171) and T30.2 (the cluster support package, ADR-172). Upstream's T22.2 (Bootstrap Icons) is T29.2, under the icons milestone M29 (upstream's M22).
- Upstream ADR numbers are unchanged (ADR-170, 171, 172). Upstream's code comments and commit messages cite ADRs, not task IDs, so no code reference changes; the one prose mention (
site/dev-gates.html, "tasks like T24.1") is only an example and is left as upstream wrote it. - The ledger (
spec/upstream.md, milestone-renumbering) gains the new rows. M30 is the next free milestone number; the next upstream milestone that collides takes M31.
Alternatives rejected
renaming the fork's M24 (about 25 tasks cited by number across code, tests, ADRs, the README and open branches: a rename now would break every in-flight track's references and its merge into the spec).
Consequences
an upstream reader looking for T24.1 finds the fork's Pi-hole special names; the milestone line of M30 says "upstream M24".
Builds on ADR-170 ADR-171 ADR-172
Link to this decision · In the specification
ADR-987 Break-glass default stays loopback; upstream's #63 answer (document the private-network default) is not takenupstream's b334e0f (refs #63) keeps allowed_admin_networks defaulting to private networks and loopback, says so in the key's description, docs/running.md, the users guide and spec/08, and logs the open networks at start-up.
Context
upstream's b334e0f (refs #63) keeps allowed_admin_networks defaulting to private networks and loopback, says so in the key's description, docs/running.md, the users guide and spec/08, and logs the open networks at start-up. The fork's owner decided the other way (ADR-944): absent means loopback only, a proxied request is never break-glass, and a warning is logged while the list is unset. allowed_admin_networks is Option<Vec<Cidr>> here and Vec<Cidr> upstream.
Decision
- Keep ADR-944 whole. From b334e0f the fork takes the two-factor code box (already fixed here the same way,
pattern={"[0-9]{6}"}), the Playwright two-factor test and6-markup.spec.ts(kept beside the fork's6-totp.spec.ts), and the wording that disable_local_login is a way in for when the provider is down. - Not taken: the default-list wording (
schema.rs,docs/config-schema.json,docs/running.md, the users guide,spec/08), upstream's list-based start-upbreak_glass_noticeand its test (the fork has its ownbreak_glass_notice(bool, Option<&[Cidr]>): a warning when the list is unset, the loopback default, or empty, and an info line when it lists networks; tested byapi_004_break_glass_notice_covers_unset_empty_and_listed), and the ADR-944-contradicting prose in the key descriptions. Those stay or are rewritten to the loopback default.
Consequences
the fork's documentation and schema say loopback; a later upstream sync that touches these lines conflicts again, and break-glass-loopback in the ledger lists the paths. If upstream moves to loopback, drop this ADR.
Builds on ADR-944
Link to this decision · In the specification
ADR-988 Workers start with mimalloc's arena reservation off, so RLIMIT_DATA counts what a worker holdsthe Pi-hole import worker (ADR-939) answered {"ok":false,"error":"<path>: <path>"} in every musl build, and the discovery workers (ADR-908, ADR-933, ADR-934) ran under a limit that bounded nothing.
Context
the Pi-hole import worker (ADR-939) answered {"ok":false,"error":"<path>: <path>"} in every musl build, and the discovery workers (ADR-908, ADR-933, ADR-934) ran under a limit that bounded nothing. Cause, from strace: the binary's global allocator is mimalloc (main.rs). At its first allocation, before main, mimalloc reserves a 1 GiB arena with one mmap(PROT_READ|PROT_WRITE, MAP_NORESERVE). Linux counts a private writable mapping against RLIMIT_DATA (VmData) when it is made, touched or not. After harden set RLIMIT_DATA to 1 GiB, VmData was 1026 MiB: the next mmap that needed a new range failed (mprotect ... = -1 ENOMEM twice), SQLite's sqlite3_open_v2 returned a null handle, and rusqlite reported it as the bare path. The discovery worker (64 MiB) did not fail, for the opposite reason: every allocation fell inside the arena that was already mapped, which the limit never sees, so its limit allowed about 1 GiB. The glibc debug build maps the same arena (checked: VmData 1026 MiB), but its tests never opened a database after hardening.
Decision
wrendns_net::worker::prepare_spawnsetsMIMALLOC_ARENA_RESERVE=0(KiB) in the worker's environment, after the caller'senv_clear. mimalloc then makes no arena: each 32 MiB segment comes from the kernel on demand (mappedPROT_NONEand committed as used wherevm.overcommit_memoryis 0; mapped read-write at once where it is 1, as on wrendns-dev, where a new discovery worker shows 6.2 MiB ofVmDatabefore its handshake), soVmDatais what the worker holds andRLIMIT_DATAis a real bound, enforced in steps of one 32 MiB segment. This rests on mimalloc's internals and the overcommit setting. Every spawner of a worker already callsprepare_spawn(the discovery supervisor, the import preview); the integration tests ofdiscovery_workers.rsnow do too. The worker's environment is no longer empty but has exactly this one variable (dsc_002_worker_env_is_emptyexpectsenv_vars == 1).hardenrefuses to run, with a message naming the variable, whenVmDataplus 4 MiB is already above the limit it was asked for. A worker started withoutprepare_spawn(by hand, or by a spawner that forgot) says why; it no longer fails later inside a C library. The limit itself stays exactly the requested size (the supervisor checksdata_bytes == memory_mib << 20).- The limits do not change: the import worker keeps 1 GiB (ADR-939), the discovery workers
[discovery] worker_memory_mib(32 to 128, default 64).RLIMIT_ASstays unused (ADR-908). - The main process is not touched: its allocator keeps the arena (the hot path and the memory budget are unchanged; the change is in
wrendns-net's worker module, which the query path does not call).
Measured (musl bench-fast build, wrendns-dev): with the variable, a 9 MiB gravity.db of 300,000 domain rows is converted in 0.2 s at 238 MiB peak RSS, under the 1 GiB limit; the discovery worker passes its handshake and ping at 32 and 64 MiB; the debug-only alloc fault job still aborts the worker at its 32 MiB limit (dsc_002_worker_rlimit_aborts_alone), which shows the limit now bounds. Without the variable: VmData 1026 MiB and the import fails as reported.
Alternatives rejected
setting the limit to VmData now plus the budget (keeps the arena, so up to 1 GiB plus the budget is allowed: a hostile input is not bounded, and the reported limit stops matching the request); mi_option_set(arena_reserve) in the worker's main (too late, the arena exists before main); removing the limit (the owner's rule is to keep one); RLIMIT_AS with a larger value (the arena counts there too, and a measured value would depend on the thread count and the build); a second allocator for workers (a dependency and an image-size cost for one variable).
Consequences
a worker's real memory use is now bounded by its limit, so a worker that used up to 1 GiB of arena before may now abort at its limit: the defaults were chosen for the work (ADR-908), and a worker that aborts is restarted by the supervisor and reported. The worker's environment is MIMALLOC_ARENA_RESERVE=0 and nothing else. A future change of the global allocator must keep this property or replace the variable.
Test plan
api_007_import_worker_reads_gravity_db_under_its_limit and api_007_import_worker_unpacks_teleporter_in_its_scratch_dir (crates/wrendns/tests/pihole_import_worker.rs: they spawn the built binary under the real 1 GiB limit and fail on the old code in debug and release builds), dsc_002_worker_without_allocator_env_refuses_clearly, dsc_002_prepare_spawn_sets_allocator_env, dsc_002_vm_data_is_readable, and the CI job worker-image (the musl image: discovery handshake with a 64 MiB limit, import of a gravity.db and a Teleporter zip, read-only root).
Builds on ADR-908 ADR-933 ADR-934 ADR-939
Referenced by ADR-1001 ADR-1008 ADR-939
Link to this decision · In the specification
ADR-989 The import's scratch files live in a private directory under the data directorythe image is FROM scratch and has no /tmp.
Context
the image is FROM scratch and has no /tmp. The import wrote the upload with std::env::temp_dir() (the server) and the worker unpacked a Teleporter archive's gravity.db there too (SQLite reads files, not memory); with the worker's empty environment temp_dir() is /tmp. In the image the preview answered 500 "can't store the upload".
Decision
each preview makes <data_dir>/import-tmp/<pid>-<time>-<n> (the parent, import-tmp, and the directory at mode 0700), writes the upload there (mode 0600) and starts the worker with --scratch <that directory>, where it unpacks the database. The whole directory is removed when the preview ends (Drop). The parent is swept of directories older than an hour (left by a crash). The data directory is the one path every install can write (the image's volume, the unit's StateDirectory, the chart's PVC). If it cannot be written, the preview falls back to the system's temporary directory rather than failing. The worker's --scratch is optional; without it (the CLI wrendns import pihole, which runs in the operator's own shell) the system's temporary directory is used.
Alternatives rejected
adding /tmp to the image (a writable path outside the volume breaks the read-only-root rule of 08 §2); a tmpfs mount in the chart and the compose bundle (every deployment would need it, and the native unit would not); the worker choosing its own directory (it has an empty environment and no knowledge of the data directory).
Consequences
import-tmp appears under the data directory while a preview runs and is empty otherwise. wrendns import pihole of an archive still needs a temporary directory, which exists wherever a shell does.
Test plan
api_007_upload_scratch_is_private_and_removed, api_007_upload_scratch_falls_back_to_temp_dir, api_007_import_worker_unpacks_teleporter_in_its_scratch_dir, and the worker-image CI job (the previews run in the image with a read-only root and no /tmp).
Review amendments (2026-11-18): the fallback to the system temporary directory creates only a fresh wrendns-import-<random> directory (mode 0700, fails if it exists) and never changes the mode of, or sweeps, the temporary directory itself; the stale sweep runs only under <data_dir>/import-tmp and only on names up-<pid>-<time>-<n>-<random>. Scratch names carry a random suffix. An archive entry is capped at 256 MiB (was 512) so inflating (which doubles its buffer) stays under the 1 GiB limit and the user gets the clear refusal, not an abort. Previews are already limited to two at once (PREVIEWS). The upload's removal on drop is synchronous and accepted: the directory is one upload and one file.
Link to this decision · In the specification
ADR-990 A lease renewal is not stored; only a vote is
Notes
Context. A voter kept its lease in the ballot.json it fsyncs before answering. Every renewal (each 5 s, from the primary to every voter, and the primary's own grant) moved lease_until_ms, so each renewal cost an fsync on the election lock. On Pis with SD-card storage, a primary was seen losing its lease every 10 to 20 minutes. The cause is not established: a slow fsync is one candidate (a store of 2 s or more makes an answer miss the 2 s ask deadline, and two missed rounds in a row end the 13 s lease), and the model in tests/lapse.rs shows that this mechanism lapses the old policy and not the new one, but nothing yet shows such stores are that slow. Other candidates: the vote RPC queued behind large transfers on the primary's streams, and something the primary runs every 10 to 20 minutes. The stored lease_until_ms is on the process's election clock, and a restarted node does not use it: Ballot::adopt gives it a full lease from its own start. Decision. (1) A ballot is stored when its epoch, candidate or clock changes, or when a lease first appears (Ballot::must_persist_since); a renewal extends the lease in memory only. (2) A new elector takes the running elector's ballot when there is one; otherwise a stored ballot's lease is taken to run a full lease from now (Ballot::for_new_elector), never shorter than what was promised, because the stored value is older than the last renewal. (3) A node with no election (manual mode) still stores every renewal it grants: it has no memory to hold the lease, and only a transition window uses it. (4) Diagnostics: debug lines for renewal rounds and each answer's time, an info line and the lease_renewed event when a lapsed lease returns, a warning when a ballot store takes 500 ms or more.
Alternatives rejected
storing less often (every Nth renewal): still a stall, and a harder argument for safety; a longer lease or more rounds before a lapse: hides the stall and delays failover; moving the fsync to a blocking thread: the answer still waits for it, and the election lock would be held across an await.
Consequences
a voter's disk is written at votes, not every 5 s (less wear on SD cards). Safety is unchanged: a restart already gives a full lease, a rebuilt elector never shortens one, and one vote per epoch is still stored before it is answered. Not addressed: the vote RPC shares a stream with large transfers (an equally likely cause, not ruled out), and a lapse right after adopting auto. The change is justified by the model and by fewer writes, not by a measurement on Pis: the slow-store warning and the renewal-round debug lines are there to confirm or reject it.
Test plan
clu_005_t24_26_a_renewal_is_not_stored, clu_005_t24_26_the_primarys_own_renewal_is_not_stored, clu_005_t24_26_a_new_elector_never_shortens_a_lease; clu_005_t24_26_a_two_second_store_lapses_the_base_and_not_the_fix (tests/lapse.rs: the real Elector with a store taking 2 to 4 s; the base policy lapses, the fixed one does not; no hardware); the partition simulator; deploy/cluster3/e2e.sh; deploy/cluster3/lapse-soak.sh.
Link to this decision · In the specification
ADR-991 List failures are read from the error text and fixed with the existing list endpoints; the per-list limit offered is capped at 128 MiBthe first real import (40 lists) left lists failing for reasons a person can fix: one over max_list_bytes (64 MiB), one whose address returns 404, a GitHub page URL (an HTML page), and a regex list that is not an adlist.
Context
the first real import (40 lists) left lists failing for reasons a person can fix: one over max_list_bytes (64 MiB), one whose address returns 404, a GitHub page URL (an HTML page), and a regex list that is not an adlist. The error text said what happened but the Lists page offered no way to act on it. Pruning lists that add nothing was asked for with it.
Decision
(1) the importer rewrites GitHub blob/raw page URLs to raw.githubusercontent.com and skips regex-named lists, both with a preview note. (2) The Lists page reads the download error (larger than the N-byte limit, the server says it is M bytes, HTTP 404/410) and offers fixes through PUT/DELETE /api/v1/lists/{name} and POST /api/v1/lists/refresh, so no new API operation (and no new MCP tool: agents already have these) is added. (3) The limit offered is the announced size plus 25 percent, or double the old limit when the size is unknown, rounded up to whole MiB and never above 128 MiB. The ceiling is a judgment from the memory figures in ADR-020/ADR-023 (about 20 bytes a name running and about three times that while compiling): 128 MiB of hosts lines is millions of names, already past what a 512 MiB Pi compiles. max_list_bytes itself still allows up to 1 GiB for someone who sets it in the file. (4) A list is called redundant when its Unique count is 0 and its largest overlap holds all its names, in one other enabled, enforcing list of the same kind (identical lists: only the later-sorting one is offered); the offer is to turn it off or remove it, never an automatic change.
Alternatives rejected
a structured error field on ListInfo (an OpenAPI change, and replicas merging lists from an older primary would lose it; the text is stable and tested); raising [filter] max_list_bytes for everyone (one bad address could then fill memory on every list); pruning single rules from a list (a downloaded list is replaced at the next refresh, and the snapshot keeps overlap counts, not which names overlap).
Consequences
the error text is now an interface for the UI: too_big in wrendns-filter keeps its wording (flt_004_size_cap_keeps_last_good). Owner to confirm the 128 MiB ceiling.
Test plan
t24_27_* unit tests, the Playwright test t24_27 list failures offer a fix.
Link to this decision · In the specification
ADR-992 List overlap is counted while the lists are compiled, by name and by side, and the prune plan is computed from those countsthe owner asked (2026-11-18, through AskUserQuestion: "Overlap report + disable") for each list on the Lists page to show how many of its entries no other enabled list has and which lists cover the rest, and for a Prune action that previews the lists adding little or nothing at a threshold the admin sets (for example under 1 % unique) and turns them off after a confirmation, with undo.
Context
the owner asked (2026-11-18, through AskUserQuestion: "Overlap report + disable") for each list on the Lists page to show how many of its entries no other enabled list has and which lists cover the rest, and for a Prune action that previews the lists adding little or nothing at a threshold the admin sets (for example under 1 % unique) and turns them off after a confirmation, with undo. Much of the count existed already (OBS-009, T7.14: unique and a pair matrix in the compile's manifest, GET /api/v1/lists' overlap). Three gaps made it unsafe to act on: (1) a name a block list and an allow list both hold counted as shared, so an exception list made the block list it excepts look redundant; (2) regexes and modifier rules ($dnstype, $client, ...) are not in the name FSTs, so a list made of them showed 0 unique and was "redundant"; (3) nothing said which lists a group uses by name, or that a shadow list covers nothing because it never blocks.
Decision
- Where it is computed. In
merge_domains(wrendns-filter/src/compile/mod.rs), the pass that already walks every distinct name once, in sorted order, with that name's list set in hand. Never on a query, never from the FSTs afterwards (a snapshot is not re-read for this). It is recomputed on every compile, because it is a by-product of the compile; it is stored in the snapshot's manifest (stats.per_list[].unique,.rules,stats.overlap), so a node that starts from a snapshot has the numbers without compiling. A snapshot written before this change has norules(serde default 0) and the old, side-less counts until the next compile. - Sides. A name's holders are split into the block side (
Block,ImportantBlock) and the allow side (Allow,ImportantAllow).uniquecounts a name for a list when it is the only holder on a side; the pair counters count a name once per pair of holders on the same side. A block list is therefore compared with block lists only: an allow list (or an@@rule) never makes a block list look covered. A list that is the sole holder on both sides of one name counts it once. - Rules. Modifier rules and kept regexes are counted per list as
rulesand treated as unique by the plan (adds = (unique + rules) / entries). Overlap is by name, so a wildcard another list covers (||example.com^already blocksads.example.com) is not seen either; both only err toward keeping a list. - Cost, measured (
cargo run --profile bench-fast -p wrendns-filter --example compile_bench -- synthetic 2000000 1 40: 40 lists, 2.5 million entries, 1.57 million distinct names, one thread, shared 24-core host under other work, so run-to-run noise was about 0.3 s): peak RSS 146 MiB with the pair counting, 146 MiB without it, 146-147 MiB before this change. Merge phase 1.2 to 1.9 s in every variant (before: 1.13 to 1.89 s; after: 1.31 to 1.79 s; counting off: 1.21 to 1.71 s), so the cost is inside the noise. The counters are a triangle ofn(n-1)/2u64for up to 128 lists (40 lists: 6 KiB; at most 64 KiB), a map beyond that (one entry per pair that shares a name, so at mostn(n-1)/2entries); the previous per-pair hash map is gone, which removes a hash per pair of holders of every shared name. On a Pi 4 (about 4 to 5 times slower per core) the same per-name work stays a small share of the merge. Nothing is added to the query path: the matcher, the snapshot readers and the cache are unchanged, andmake bench-smokeis the check (see the task's Done note). - Which lists the plan may turn off. Enabled block lists in
enforcemode with entries in the snapshot, that no group names in its ownlists. Allow lists (an exception list adds nothing by design), shadow lists (they block nothing; the owner turns them off or enforces them), lists not compiled yet (no numbers), and lists a group names (that group may not use the list that covers them: the overlap is global, not per group) are always kept, with the reason in the answer. A group whoselistsis absent uses every enabled list and does not hold any list in place. Per-group overlap (what a list adds within the lists one group uses) is not built; if wanted it is a refinement of the same counts per list subset (Open). - The plan is a set, not a ranking. Lists whose own loss
unique + rules + names shared with shadow listsis at most the threshold percent of their entries are considered least-adding first; one is added only if, with it, every list in the set still loses at most the threshold counting the names it shares with the others in the set. Two lists that mirror each other are never both proposed.losesAtMostfor the plan is the sum of each list's own loss plus the names each pair of the set shares: an upper bound (a name whose every holder is turned off is shared by at least one pair of them), never an estimate. The threshold is 0 to 50 percent (default 1): above half, "adds little" stops meaning anything. - API (agent-ready, AGT-001/002; ADR-993 for the apply):
GET /api/v1/lists/overlap(rows),GET /api/v1/lists/prune-plan?thresholdPercent=(the plan; changes nothing), MCP toollist_overlap(both reads);POST /api/v1/lists/pruneis a person's. All three read the primary's numbers on a replica (the primary compiles).
Alternatives rejected
computing overlap from the FSTs on request (a full scan of millions of names per request, and per request on every replica); a per-list-pair name sample (a bound is needed for safety, a sample is not one); counting block against allow lists as shared (see context); treating regexes as covered when a list's other names are (unsound); a threshold above 50 (two near-identical lists could both look removable at 100); proposing lists a group names and warning instead (the warning is easy to miss and the harm is silent).
Consequences
GET /api/v1/lists changes meaning slightly: unique and overlap no longer count block/allow sharing, and rules is new. The Lists page shows "adds N %" and "N % also in X" per list. The compile's work grows by two small side lookups per distinct name (no allocation).
Test plan
flt_004_unique_counts_the_same_side_only, flt_004_pair_counts_dense_and_sparse_agree, the extended flt_003_compile_* overlap assertions (crates/wrendns-filter/src/compile/tests.rs), flt_004_prune_* and flt_004_overlap_rows_* (crates/wrendns-api/src/lists_overlap.rs), compile_bench synthetic 2000000 1 40.
Requirements AGT-001 OBS-009
Builds on ADR-993
Link to this decision · In the specification
ADR-993 Prune turns lists off through the list edit path and is never for agentsthe owner chose "Overlap report + disable": a Prune action previews, then disables after a confirmation, and undo is one click; disabled lists stay in the configuration.
Context
the owner chose "Overlap report + disable": a Prune action previews, then disables after a confirmation, and undo is one click; disabled lists stay in the configuration. Agents and the MCP may read and plan; applying needs a person (AGT rules).
Decision
- Apply.
POST /api/v1/lists/prune {thresholdPercent?, names, snapshotVersion, configVersion}(operator):namesand both versions are required, the ones the person previewed (the plan returnssnapshotVersionandconfigVersion). It recomputes the plan on the server and changes nothing (409, "preview again") if either version differs, a compile is pending, or a name is no longer in the plan. The plan itself treats a cover as a cover only while that list is currently enabled, enforcing and a block list (a list turned off by an earlier prune, or deleted, covers nothing even if the last compile's overlap still names it), and proposes nothing while the overlap names a list that is off or gone (compilePending). Each list is written back through the same managed-write path asPUT /api/v1/lists/{name}with its current definition andenabled = false, checked against the configuration version read before the definitions (then the version each write returned), so an edit in between fails the write and is never overwritten (so credentials read back as<redacted>keep their stored value, ADR-903; a list from the config files becomes an override withenabled = false; a GitOps cluster gets the usualkeepInGitguidance from the single-list write). The lists are written one after another; if one fails, the ones already off stay off and the error's hint names them. Audit: each list's write is recorded aslist.put(before and after, as the PUT route does) as it succeeds, and onelists.pruneentry (target: the lists, detail: the threshold, the lists, the loss bound) follows; a prune that stops part-way recordslists.prunewithpartial: trueand the lists already off. - Undo. No new endpoint: the UI's notice ("N lists turned off. Undo") rewrites each list with
enabled = truethrough the ordinary list edit (the same edit as turning one on in Manage lists), and an operator can do that any time. Undo has no version check (it is the ordinary last-write list edit), and a list defined in the config files stays an API override withenabled = trueafter Undo, so later edits to it in the files are masked until the override is removed in Manage lists (Open: remove the override when the only difference isenabled). Nothing is deleted, so nothing is lost: the list's source, rules and settings stay, and a list that was off is downloaded again when it is on (a disabled list is not fetched). - Agents. The plan is a read (
config:read; MCPlist_overlap).POST /api/v1/lists/pruneis innever_for_agents(agent_not_allowed), whatever the token's scopes: turning off a block list changes what every device is protected from, and the plan an agent would apply was computed from numbers it cannot judge (regexes, group intent). An agent proposes; a person applies in the UI or with a user token. - UI. Lists page, operators only: "Prune…" opens a panel with the threshold (0 to 50), a preview table (list, names, unique, adds, could lose, also in), the lists that stay with their reasons, and a two-step "Turn off N lists" with a confirmation. A panel in the page, not a modal: it stays beside the table the numbers come from.
Alternatives rejected
a plan object with an ID and an expiry like guarded changes (ADR-956: this changes no guarded setting; the names re-check against the live plan does the same job for a bound of one request); deleting lists (loses the source and cannot be undone); one atomic multi-list write (the write path is per entry; a half-finished prune leaves valid configuration and says which lists are off); letting agent tokens apply with config:write:lists (see 3).
Consequences
a prune on a cluster replica forwards each write to the primary like any list edit. Several lists turned off one after another can cost one recompile each if the writes are far apart; they coalesce when close together.
Test plan
flt_004_prune_lists_over_http (crates/wrendns-api/src/tests.rs: plan, stale names refused with nothing written, the apply writes enabled: false with the stored definition, audited, agent refused with agent_not_allowed, viewer refused); Playwright flt_004 prune lists that add little, then undo.
Referenced by ADR-992
Link to this decision · In the specification
ADR-994 Content categories and filter profiles are in scope; a profile is a groupthe owner asked (2026-11-18, with two screenshots of UniFi's content filtering) to organise blocking into categories (groups such as "Adult and Sensitive Content", "AI & Crypto", "Business & Professional", "Culture & Entertainment", "Networking Infrastructure", "New or Risky Domains", "Security & Threat Protection", each with checkboxes and an "n of m" count) and to manage them in named filter profiles (a list with Name, Source, Filter Scope, Safe Search and Schedule, and an editor with Source, Ad Block, Safe Search per engine, Filtering Off, Enhanced or Basic, and a category picker with Search, Select All and Deselect All).
Context
the owner asked (2026-11-18, with two screenshots of UniFi's content filtering) to organise blocking into categories (groups such as "Adult and Sensitive Content", "AI & Crypto", "Business & Professional", "Culture & Entertainment", "Networking Infrastructure", "New or Risky Domains", "Security & Threat Protection", each with checkboxes and an "n of m" count) and to manage them in named filter profiles (a list with Name, Source, Filter Scope, Safe Search and Schedule, and an editor with Source, Ad Block, Safe Search per engine, Filtering Off, Enhanced or Basic, and a category picker with Search, Select All and Deselect All). A later message added that adding devices from the profile is wanted too. The scope note in spec/10 (quick rules, around line 272) said "Not parental controls: no screen time, no content categories".
Decision
- Scope. Content categories are in scope as FLT-901; filter profiles as FLT-902. The note is amended: no screen time (per-device time budgets) stays out; no content categories is withdrawn. Schedules (FLT-010) stay time windows.
- A profile is a group. No parallel object. Source =
group.networksplus managed clients whosegroupsinclude the profile (ADR-973/976 keys); Schedule =group.schedules; safe search andyoutube_restrictas today, with newsafe_search_engines; services =blocked_services(FLT-012); filtering = newgroup.content = { level = off|basic|enhanced, categories, tiers, ads }. The Groups page becomes the profile list and editor; every existing advanced field stays under "Advanced". - A category is a named selection of catalog sources; a source becomes a managed list (ADR-040) named
cat-<source-id>, created only while a group uses it, fetched once and shared by every group that selects it, with a read-onlyownersset. Category lists are never part of a group's "every enabled list" default. - Only categories with a real maintained, openly licensed source are offered (ADR-995); the rest are listed as not offered, never as empty checkboxes.
- Cost is shown before it is paid. Sources above 500,000 entries are "heavy"; a running total of distinct sources uses the 12 bytes per domain target (
spec/05§2) against[filter] entry_budget(default 1,000,000, the NFR number; a Settings control). A source above 500,000 entries is heavy; several (NRD 7 days, full TIF) pass the default budget alone and are labelled heavy, over the default budget. A selection is refused when the node's baseline RSS plus the estimated snapshot plus the compile peak passes 50 % of the node's memory limit, the baseline RSS being 32 MiB provisional until step 2 measures it (Open: the 50 %), where the compile peak ismin(sum of source bytes x a measured factor, merge budget)and the merge budget ismin(128 MiB, 25 % of the memory limit). Heavy sources refresh at most every 24 hours and the fetch streams to disk. - Defaults are off. A new install downloads no category list and every group is
level = "off". - Failure isolation. Category lists and the catalog never affect answering: an unknown category id (version skew, ADR-059) is ignored and reported; a failed download leaves the last good snapshot (FLT-004).
- Roles and agents. Viewer reads the catalog; operator edits a group's
content; agents read and plan (config:write:groups).plan_set_group_contentis plan-only for agents whateverrequire_approvalis. Content plans are always createdpending(an exception to ADR-070, which has an approval state only when the setting is on;plan_pin_versionrefuses planning when it is off, a different rule, not copied): an agent'sapply_planon an unapproved content plan is 403agent_not_allowed, and an operator-approved plan applies. REST is gated the same way:PUT /groups/{id}/content, andPUT /groups/{id}whencontentchanges, answer 403agent_not_allowedto an agent token (testflt_901_agent_rest_put_content_403). A heavy or over-budget selection is also refused at planning time for agents. - Reserved names. The
cat-list-name prefix belongs to the server: a file- or API-defined list namedcat-*is a validation error. - Cluster. The primary fetches and compiles category lists; replicas receive the snapshot (
spec/12). A replica never downloads a category list.
Alternatives rejected
a separate "profile" object beside groups (two ways to say the same thing, and clients, schedules, safe search and rewrites already hang off groups); bundling lists in the binary (licences, image size ADR-916, stale data); a category as a regex or keyword classifier (no maintained open source, false positives, hot-path cost); one list per category written by hand (we would be the maintainer); offering Block List Project (archived 2026-10).
Consequences
a per-engine safe-search field is added; the Lists page shows category-owned lists read-only; the config schema, OpenAPI and MCP snapshot change; docs/third-party-notices.md gains the sources; no screen time. Design: docs/design/content-categories.md. Task: T24.29.
Test plan
docs/design/content-categories.md §9.
Owner decisions (2026-11-18). All ten recommendations in docs/design/content-categories.md §12 are accepted:
- Offer the seven UniFi-style groups plus Privacy and Ads.
- Basic is Adult, Malware, Phishing and Scam.
- Nothing is selected by default.
- UT1 comes later, through the mirror once its licence is read.
- No OISD.
- An authored AI-services bundle, and no crypto bundle.
- Ad Block is one checkbox, with the tier in Settings.
- Newly registered domains at 7 days only.
- A category over 50 % of a small node's limit is refused.
- A device's several profiles combine as a union. Bon-Appetit is an Extended Adult tier, off by default.
Measured the same day
UniFi's content filter is DNS-level. The gateway sinkholes filtered names and intercepts outbound port-53 queries, but queries to an internal resolver are not intercepted. So a device that uses WrenDNS is filtered only by WrenDNS's categories, or by the gateway when WrenDNS forwards to it from that device's VLAN (T24.31 source address, T24.32 direct way). The owner chose both.
Requirements FLT-004 FLT-010 FLT-012 FLT-901 FLT-902
Builds on ADR-040 ADR-059 ADR-070 ADR-916 ADR-973 ADR-995
Referenced by ADR-1004 ADR-1017 ADR-1057 ADR-1060 ADR-995
Link to this decision · In the specification
ADR-995 The category catalog: presets/categories/*.toml, sources with licence and cadence, downloaded at runtimeADR-994 needs a catalog that is data (like presets/services/*.toml, FLT-012), with sources checked for licence, maintenance and size.
Context
ADR-994 needs a catalog that is data (like presets/services/*.toml, FLT-012), with sources checked for licence, maintenance and size. Sources were checked on 2026-11-18 by fetching repository metadata, licences and file headers (docs/design/content-categories.md §2.1).
Decision
- Format. One TOML file per catalog group, compiled into the binary, with five tables:
[[group]](id, name, order);[[category]](id, name, group, one-line description for the info icon,sources, optionaltiersanddefault_tier,kind = "list" | "service");[[source]](id, name, maintainer, url,format = "domains" | "adblock" | "hosts", SPDX licence, licence_url, optional attribution, homepage, cadence, entries and bytes from the file header at catalog build, optionalmax_bytes,weight = "light" | "heavy"computed above 500,000 entries, optionalresolve = "meta-json"when the file name changes, and then a fixedurl_prefixper source: scheme, host, repository path and file-name pattern, e.g.https://raw.githubusercontent.com/Bon-Appetit/porn-domains/andblock.<hash>.txt; a resolved URL outside the prefix is refused and the source reportsresolve_refused;cadence = "daily" | "low";tiersof kindexclusiveoradditive; per-sourcecheckeddate andarchivedas recorded);[[preset]](id such asbasic,categories);[[not_offered]](name, group, reason, alternative). - Sources (first release): HaGeZi
dns-blocklistsandnrd(GPL-3.0; adult, gambling, piracy, social, fake stores, DoH/VPN/proxy bypass, dynamic DNS, URL shorteners, hosting, threat feeds, pop-up ads, ad tiers, native trackers, NRD 7 days, DGA 7 days, risky TLDs), StevenBlackhostsalternates (MIT; fake news), PerflystPiHoleBlocklist(MIT; smart-TV and app trackers), Bon-Appetitporn-domains(CC BY-SA 4.0; optional). Not in the catalog: Block List Project (archived); OISD (sjhgvr/oisd, GPL-3.0, pushed 2026-11-18; an earlier draft said "no licence terms found", which was wrong; a candidate Adult alternative, design Q4b); UT1 via theolbat/ut1-blacklistsmirror (CC BY-SA 4.0 per its README, 80 per-categorydomainsfiles, not archived, pushed 2026-11-11; the licence on the UT1 site is unread and the mirror is not the maintainer's host; Open, design Q4; no archive source type is needed).
2b. Ad tiers name HaGeZi's adblock/ files, so the default tier's URL equals the bundles' existing hagezi-pro list (dedup and adoption by URL, design section 6.3); T24.29 edits the two bundle files to drop that list and set content.ads.
- Admission rule. A source needs an SPDX licence read from the repository, a push within 90 days, a repository that is not archived, and a URL on the maintainer's host (raw GitHub or jsDelivr for the same repository). An upstream-run mirror is not admitted in the first release (Open, design Q4: admit it once its licence file is recorded and the UT1 site's licence is read). The cargo tests (
flt_901_catalog_*) check recorded metadata only: SPDX id,licence_url, a recordedcheckeddate within 90 days ofcatalog_version,archived = falseas recorded; they never use the network. The live check against the GitHub API isscripts/check-catalog.py, run by the weekly job, which opens an issue when a source goes stale. - Never bundled. Lists are downloaded at runtime by the primary (replicas receive the compiled snapshot,
spec/12). The binary carries the catalog (metadata), never list content. The domains-only format is preferred (smallest, cheapest to parse). - Licences and attribution. The UI shows maintainer, licence and a link for each source, and the CC BY-SA attribution line;
docs/third-party-notices.mdlists them. HaGeZi's GPL-3.0 covers the lists as data fetched by the user; no HaGeZi code is used (AGENTS.md rule 6). - Refresh and cadence. Each source's cadence sets the list's
refresh_secs(HaGeZi publishesExpires: 8 hours, so the catalog says 8 hours for light sources and 24 hours for heavy ones, which change daily and run to 40 MB); the conditional GET and stale-list rules (OBS-023) apply as to any list. - Versioning. The catalog carries
catalog_version. A new category in a newer binary is unknown to older nodes (ignored and reported, ADR-994 §7). Removing or renaming a category id needs an alias entry for one release.
Alternatives rejected
fetching the catalog at runtime (a second thing that can fail, and an injection path for URLs: the catalog is code-reviewed data); one big merged list (no per-category choice); bundling a snapshot (licence, size, staleness).
Consequences
counts in the catalog go stale between releases; the UI shows the live count after download and the catalog value before. A source URL that moves needs a release (or the user's own list). Risk for the owner: GPL-3.0 on a dataset is recorded here, not resolved by legal review.
Test plan
flt_901_catalog_* (design section 9), a fuzz target for the catalog parser, flt_901_meta_json_url_outside_prefix_refused, flt_901_cat_prefix_reserved, flt_901_catalog_recorded_metadata_fresh, and a weekly job running scripts/check-catalog.py (licence, recency and archived flag against the GitHub API; not a cargo test).
Owner decisions (2026-11-18). Accepted with ADR-994's decisions.
Requirements FLT-012 OBS-023
Builds on ADR-994
Referenced by ADR-1017 ADR-1059 ADR-1060 ADR-994
Link to this decision · In the specification
ADR-996 A device's effective policy: one identification, a section list the panel draws, and the same answer where traffic is watchedT24.30 (fork #21, #23, owner request 2026-11-18): click a device and see every filter and rule that applies to it, and why; and (owner addition, same day) the same answer where the owner looks at traffic: the network map, the Flow page and Explain.
Context
T24.30 (fork #21, #23, owner request 2026-11-18): click a device and see every filter and rule that applies to it, and why; and (owner addition, same day) the same answer where the owner looks at traffic: the network map, the Flow page and Explain. Facts checked in the code: ClientTable::identify is the only place a device is matched (client ID, EDNS MAC, neighbor MAC, workload, exact IP, most specific CIDR, router name, default: ADR-973, ADR-976); the group's settings live in the compiled Group (block policy, services, SafeSearch, rewrites, answer filter), the lists a device meets are the filter's ListMask for its identity, and schedules and quick rules are compiled from the same Config; Explain already calls identify, but named only the way a device was recognized (identifiedBy), not the key, and a group's origin (its own, its network, a router name) was not said anywhere.
Decision
- One identification, two readers.
explain::resolve_identityis the single call that runsClientTable::identifyfor a read (with a MAC standing in for the neighbor table when one is given) andClientTable::match_keyfor the key it matched. Explain and the policy read both call it; neither re-derives a group.match_key(policy crate, off the query path, it allocates) returns the key as a[[client]] matchis written (id:kids, a MAC, an address, a network,hostname:tv) and where the group came from (device,network,router_name,kubernetes,default) with the network or router name that gave it.identifyis not changed, so the query path is as it was; the testflt_006_policy_names_the_group_and_key_and_agrees_with_explaincompares the panel's answer with Explain's field by field for a device matched by network, MAC, client ID, CIDR, address and none. - The read.
GET /api/v1/clients/{id}/policy(id: a configured device's name, an address, or a workload) and the MCP toolget_client_policy;get_client_profilecarries it aspolicy. A configured device is read the way a query from it would be: at its address when it has one (an address key, else one the neighbor table or a router name gives), otherwise as a stand-in address with its MAC or client ID, and the answer says so innotes. When the device's keys also match a higher-ranked device, the answer is that device's and says so. The scope isconfig:read; a group-restricted agent reads its group's devices only (404 otherwise). Schedules and expiries are as of the time of the read (atUnixSeconds); the core function takesnow, so a boundary is testable. - Clusters. A replica asks the reachable primary (
Read::ClientPolicy), so every node gives the primary's answer from the primary's configuration; when the primary does not answer, or is an older version that does not know the read (ADR-971: an older peer is a missing node), the replica answers from its own copy, adds a note, and names the primary inmissingNodes. The replica sends its own observations of the device (its address, the MAC its neighbor table holds, a client ID:PolicyObservation) with the read, so the primary applies its configuration to them and the panel agrees with Explain run on that replica for the neighbor table; router names and workloads are still the answering node's (a stand-in device sends none). A primary that says the device is unknown (404) is answered as such and is not a missing node. - Extension point for categories and profiles (T24.29, design only). The answer is a list of
PolicySection { id, title, summary, items[], link }; an item is{ label, detail, state, from, untilUnixSeconds, link }. The panel, the MCP tool and the docs draw whatever sections arrive, in order, and know no section ids except to pick an icon. The sections built now areblock,lists,services,safe_search,answers,rewrites,schedules,rules,upstream. A content-category or filter-profile feature adds sections (for examplecategoriesandprofile) inpolicy_view::build, betweenblockandlists, each with items whosefromnames the profile or group that gave them and whoselinkopens the category or profile page; nothing else changes. If a profile replaces a group's lists, thelistssection is built from the profile's lists instead, withfrom: "profile <name>". The ladder (precedence) is also data (policy_api::PRECEDENCE), so a new rung is one line. - Where traffic is watched. (a) The network map's device node panel shows the policy compactly (group, where it came from, the key, the section summaries) with a link to the full Policy panel on the Clients page (
#/clients?device=<address>&view=policy). (b) The Flow page, with a device chosen, shows a "Policy" line naming the group and the key and linking to the same panel; the Flow's group node already links to the group. (c) Explain's Client card names the group, where it came from, and the key that matched, and links to the device's Policy panel. All three readGET /api/v1/clients/{id}/policy(or, for Explain, the newclient.group,groupFrom,groupKey,matchedKeyfields it already has in hand); no second implementation exists in the UI. - Not on the query path. No allocation, lock or I/O is added to a query:
identifyis untouched,match_key,applies_toandNeighbors::address_ofare called by the API only.wrendns-policychanged (new methods), somake bench-smokeran (see the task's Done note).
Alternatives rejected
a second matcher in the API that walks [[client]] keys itself (it would drift from identify: ADR-973 and ADR-976 each changed the order once); returning fixed fields per setting (every new kind of policy would change the schema, the UI and the MCP tool); putting the policy into GET /api/v1/clients rows (a read per device on every list); an at query parameter to read a policy as of another time (a UI control for it is a feature of its own; the backend function takes now for the tests).
Consequences
a device matched by MAC that no query has been seen from has no address, so a network group that would apply when it is seen is not shown (the note says so). A device with several groups shows its lists as the union the filter uses and the other settings from the first group, as Explain does. Rules inside a list ($client) are not part of the panel: they are rules of the list, shown by Explain for a name. The Groups, Lists and Quick rules pages take group, list and rule in their address to name what a line comes from; they open the page, and highlighting the row is a later refinement.
Test plan
flt_006_policy_names_the_group_and_key_and_agrees_with_explain, flt_006_policy_sections_show_the_groups_settings, flt_006_policy_schedule_flips_at_its_boundary, flt_006_policy_rules_apply_by_scope_and_expiry (explain/tests.rs); flt_006_policy_by_device_name_agrees_with_explain (api_backend.rs); flt_006_client_policy_over_http and flt_006_policy_route_needs_config_read (wrendns-api); Playwright flt_006 … in 8-policy.spec.ts (Clients panel, Explain and Flow) and 7-map.spec.ts (the map click, and no policy at privacy level 2); flt_006_replica_asks_the_primary, flt_006_older_primary_is_a_missing_node, flt_006_a_primarys_404_is_not_a_missing_node and flt_006_primary_answers_the_policy_read_locally (federated.rs).
Builds on ADR-971 ADR-973 ADR-976
Link to this decision · In the specification
ADR-997 An upstream's source address: source is an address or a network, resolved per nodeT24.31 (UPS-013).
Context
T24.31 (UPS-013). A group's queries (UPS-007) can already go to their own upstream group; some DNS filters key a policy on the address a query comes from, and a node on several networks may need to choose which one it uses. Addresses differ per node, but an upstream is shared configuration. (Owner correction 2026-11-18: a gateway's content filtering works on traffic, so this is not needed for that.)
Decision
[[upstream]] sourceis an address (198.51.100.252,198.51.100.252:0,[fd00::2]) or a network (198.51.100.0/24). A shared upstream names a network: each node uses the address it holds in it (up interfaces first, global before link-local, then the lowest). An address is for one node (single-node setups). Interface names were rejected: they are not stable across hosts and say nothing about the network a filter sees.- Applies to
udp://,tcp://,tls://andhttps://; refused with aproxy(the proxy opens the connection) and on other schemes. The port must be 0: a fixed port would give up RFC 5452 source-port randomness. - The socket is bound before connect (UDP: per query, as before; TCP:
TcpSocket::bindthen connect). Each upstream owns its connection pool, and the source is part of the upstream, so a pooled connection is never reused from another address. - The hard refusal is on the write only.
PUT /upstreams/{name}(anddryRun, and the MCP plan tools) resolvesourceagainst the node's interface addresses (getifaddrs, inwrendns-net, the onlyunsafe) and answer 422 before storing a source the node holds none of;wrendns config checkand Test it report it as a warning or error text. Start, reload and a replica's apply never refuse it (that would take DNS down for every upstream, on a restart or on a pod without the network: CLU-004, OPS-009): the upstream is built with its source unresolved, its queries fail fast withUpstreamInfo.sourceProblemand the degraded health reasonupstream_source_lost, and the others serve. An unresolved or lost source is looked up again at most every 5 seconds, so it recovers by itself (a VLAN that comes up after start, a DHCP address that changes). Agetifaddrsfailure is reported with its OS error. IPv6 link-local sources are refused (no scope id). A hostname upstream is reached over the first address of the source's IP version, and having none is the upstream's problem. - The API's
SystemInfo.addresseslists the node's addresses and networks for the UI's suggestions (node-local, read off the query path).
Consequences
in a cluster a network a node has no address in degrades that node's upstream only (its health shows upstream_source_lost); name a network, not one node's address. Binding an address doesn't choose the egress interface: the operator adds a source-based routing rule (docs/running.md runbook). Bootstrap lookups are not bound to the source. A pooled connection outlives a removed address until it closes. No cost on a query that sets no source.
Test plan
ups_013_* (wrendns-upstream/tests/source.rs: UDP and TCP leave from the bound address, a foreign stored source starts degraded while other upstreams serve, a lost one is a problem, family mismatch, an IPv6 source with a v4-only hostname; source.rs unit tests for the network choice); the Playwright upstream-source test.
Requirements CLU-004 OPS-009 UPS-007 UPS-013
Link to this decision · In the specification
ADR-998 UniFi device and group sync: explicit links, MAC identity, a three-way merge per link, and a definitive side chosen per linkThe owner asked (2026-11-18) that devices and policies sync between WrenDNS and UniFi in both directions: a device added to a group in UniFi joins the same group in WrenDNS, and the reverse.
Context
The owner asked (2026-11-18) that devices and policies sync between WrenDNS and UniFi in both directions: a device added to a group in UniFi joins the same group in WrenDNS, and the reverse. The owner's reading is that UniFi's content filtering acts on traffic and applies whatever DNS a client uses, so WrenDNS filters DNS and adds per-device visibility while UniFi enforces at the IP level, and the sync keeps the two consistent. What the repository does today (routers.rs, ADR-080, ADR-902, ADR-912, T25.10): WrenDNS reads UniFi (stat/sta, rest/user, rest/networkconf, the v2 clients/history, and with T25.10 stat/alluser and stat/device) with an API key (x-api-key on /proxy/network/api/s/<site>/...) or a session cookie, and never writes. A WrenDNS device is a [[client]] (name, match keys with the MAC among them, an ordered groups list); a group is a [[group]]. No UniFi object is linked to either.
What the research found (public sources only; no request was made to any gateway). Ubiquiti's own help pages (help.ui.com) refused this tool (HTTP 403), so each claim below says where it comes from.
- From third-party descriptions of the public API (a Go SDK status table and the unifly project's API notes): the Network Integration API v1 lives at
/proxy/network/integration/v1/sites/{siteId}/..., authenticates withX-API-KEY, and covers devices, clients, networks, WLANs, firewall zones, firewall policies, ACL rules, DNS records, traffic matching lists, hotspot vouchers, VPN, RADIUS, WAN, DPI categories and applications, with CRUD on several of them. The controller serves its own OpenAPI 3.1 document (reported at/proxy/network/api-docs/integration.json), which is the authoritative list. - Not found in v1: a client or device group object, a content-filter profile object, and any statement of which key role may write. Traffic matching lists hold IPs, ports and domains, not MACs.
- Classic (session) API, from memory of its long-standing shape and not re-confirmed here:
rest/userholds the known clients (MAC,name,note,usergroup_id,use_fixedip,fixed_ip,network_id) and acceptsPUT;rest/usergroupis the bandwidth-limit profile a client has exactly one of, not a general membership group;rest/firewallgroupholds address, port and IPv6 groups whose members are IP addresses, CIDRs and ports, not MACs;cmd/stamgrblocks, unblocks and forgets clients. Session writes on a UniFi OS console need a CSRF token (x-csrf-token) that the existing read code does not carry. - The newer "device groups": the Policy Engine (UniFi Network 9.4, August 2025) has Objects: devices, device groups and networks, usable as the source or destination of policies and traffic rules. Ubiquiti's article names them but this review could not read it, and no public API document for them was found. I recall a v2 endpoint family (
/proxy/network/v2/api/site/<site>/..., for examplenetwork-members-group,firewall-policies,trafficrules,content-filtering) behind the UI, but that is an unconfirmed recollection of an undocumented interface that Ubiquiti can change in any release. - Content filtering: the settings page is Settings → CyberSecure → Content Filter; a policy is scoped to networks or client devices; third-party write-ups (and, in a search snippet, Ubiquiti's own help article) describe it as a DNS-level feature that redirects DNS traffic to the gateway, with categories supplied by a partner (a later review found Ubiquiti's own article naming Cloudflare; the earlier partner was CleanBrowsing, so the name is not relied on). This contradicts the owner's premise that it filters traffic regardless of DNS. If it redirects DNS, the two filters do not simply stack: turning UniFi Content Filter on for a device group likely hijacks that group's port-53 traffic to the gateway, so those devices' queries may stop reaching WrenDNS and WrenDNS loses filtering, attribution and query logs for exactly the devices that were linked. A client using DoH bypasses both. Treat this as a likely conflict, to be disproved by the owner's test (Q4), not as stacking; see decision 15. The owner should confirm which it is on the gateway (the page's own help text, or its behaviour for a client with a hard-coded resolver) before product text claims "IP-level" enforcement.
- Key and role: keys are made under Settings → Control Plane → Integrations (the existing error text says so). Third-party guides say a key takes the permissions of the account that made it and has no read-only scope; one says writes need a full admin. Ubiquiti's own statement of the minimum role was not found, and UniFi has no role scoped to one object: any role that can edit a device group can most likely edit the whole firewall, and a Home Assistant issue (home-assistant/home-assistant.io#40330) reports that only a super admin or owner can create a Network API key, so a narrow-role key may not be possible at all. Say plainly: the write credential can probably change the whole Network application; the protection is on the WrenDNS side (two switches, one function, audit before the request, preview, admin-only), not in UniFi. If keys need a super admin, the fallback is a dedicated session-only local user (password through M23, CSRF handled, no MFA on that account, a long random password) and the owner must accept that exposure (decision Q11 of T25.18). The build verifies the real minimum with an operator's help (Q6).
- Not confirmed anywhere: which UniFi object holds a device group's members (MACs or client IDs) and whether any API exposes it with write access on the gateway's firmware version; whether member lists include offline clients; any change timestamp on membership; the API rate limits; whether UniFi's own audit log records an integration key's writes.
Decision (design; nothing is built until the owner accepts this ADR and ADR-999).
- A link, created by an admin, never matched by name. A
[[group_link]]joins one WrenDNS group to one UniFi object:id,group,router(a[[router]]of typeunifi),site,kind,unifi_id(the object's stable ID, with its name kept only for display),mode,create_missing_devices,include_private_macs,enabled. One WrenDNS group has at most one link per router, and a UniFi object is linked at most once. The admin picks the UniFi object from a list read from the gateway; a same-name object may be suggested, never linked. Unlinking deletes nothing on either side. A renamed UniFi object keeps its link (by ID); a deleted one puts the link inbrokenand changes nothing. - Object kinds behind one interface. The sync talks to a
GroupBackend(read the members of one object, add or remove one MAC). The first backend is the Policy Engine device group, if the build's capability check (T25.18 step 1) finds a way to read and write its members; it is the object a traffic rule or firewall policy uses, which is what the owner's wish points at. Other kinds are not in the first build:usergroup(a client has one, so a WrenDNS device in two groups cannot be mirrored, and it is a bandwidth profile) andfirewallgroup(IP members, so a device would have to hold a reservation). A kind may be added only by a later ADR. - Identity is the MAC, lower-case and colon-separated. WrenDNS side: a
[[client]]whosematchhas a MAC. A client with only an IP, a CIDR or anid:key is not syncable and is listed as skipped with that reason, never removed and never matched by its last IP. Editing a synced client so that it no longer has a MAC key makes it unsyncable, which reads as a removal from the group and is copied to the other side per mode; the client edit dialog and the preview say so, and a link in a write mode holds that round for the admin (the same hold as a first-run conflict, rule 6, not the mass-change guard) rather than applying it silently; the edit dialog shows the warning and a Playwright testdsc_016 edit to ip-only warns in client dialogplus the ACdsc_016_edit_to_ip_only_holds_write_mode_roundcover it. UniFi side: a member's MAC. A UniFi member with no WrenDNS client is unmatched: withcreate_missing_devices(default on, always shown in the preview) the sync creates a[[client]]named from the UniFi alias, else the hostname, else the MAC, withmatch = [mac]andgroups = [<group>]; for an existing client a synced add appends the group last in the orderedgroupslist (order is precedence, so the sync never reorders) and a synced removal removes only that entry (dsc_016_synced_group_appended_last_removal_only_that_entry); with it off the device is listed and skipped. The sync never deletes a[[client]]and never deletes or forgets a UniFi client. - Private (randomised) MACs. A MAC whose locally-administered bit is set is private (the same test DSC-012 already uses). Phones keep one private MAC per Wi-Fi network by default and change it when the network is forgotten or when the user picks a rotating mode; UniFi and WrenDNS see the same per-network MAC, so a stable one syncs like any other. A rotated MAC is a new device to both sides. Rules: an existing WrenDNS device that carries a private MAC syncs normally; the sync never auto-creates a WrenDNS device from a private MAC unless
include_private_macsis on (default off; the preview lists them as "private MAC, skipped"); a device that disappears is never read as a removal (rule 8); the preview marks private MACs so the admin sees that a membership may not follow the person's next MAC. A stale private MAC in a group is shown, not pruned, with a count. - Direction is set per link, and is the definitive side.
unifi_definitive(UniFi's membership is the truth: changes flow UniFi to WrenDNS, and a WrenDNS-side change to the group is overwritten at the next round, with the overwrite recorded),wrendns_definitive(the reverse; needs write access), ortwo_way. New links startunifi_definitive, the only mode that needs no write access, and in preview-only state until an admin applies the first preview. The applied state lives instate.db(per link: the applied preview id, the mode and thewrites_enabledvalue it was applied under), never in configuration. Therefore (a) a link that arrives through a TOML edit,[cluster.git], a restore or a peer starts preview-only andheldwhatever mode it names; and (b) entering a write mode (wrendns_definitive,two_way) or turningwrites_enabledfrom off to on puts every affected link intohelduntil an admin applies a fresh preview of the UniFi-side writes; the preview of the earlier mode does not carry over. Testsdsc_016_file_created_link_starts_preview_only,dsc_017_mode_change_to_write_needs_new_preview. - The merge is three-way, over sets of MACs. Each link keeps a baseline B, the membership both sides agreed at the last successful round. With U (UniFi now) and T (WrenDNS now), both restricted to syncable MACs: an addition is a MAC in a side but not in B; a removal is a MAC in B but missing from that side.
two_wayapplies each side's additions and removals to the other. A change on both sides to the same MAC in the same way is a no-op. Because B is a set, one MAC cannot be both added on one side and removed on the other, so last-writer-wins is not needed for membership and is not used: neither UniFi nor WrenDNS gives the sync a readable timestamp for a membership change (UniFi's was not found; WrenDNS's audit log has one, but the sync sees state, not events). Last-writer-wins applies only to a per-device attribute if one is ever synced (the display name; not in the first build). Conflicts are the cases B cannot settle: no baseline (first run, restore, failover to a node without it), a baseline older thanbaseline_max_age(default 30 days), the mass-change guard (rule 9), and a linked object that moved. Each is listed in a conflict view with per-row choices (take UniFi, take WrenDNS, keep both, skip); "keep both" (the union) is the default suggestion. - Echo and loop prevention. A round is read, diff, write, re-read, verify, and only then is B advanced. The sync's own writes appear on the next read as changes already in B, so they produce no diff. WrenDNS changes the sync makes carry
origin = sync:<link id>in the change record and the audit, and a change event with that origin never triggers a round. Rounds are timer-driven (interval_secs, default 60, minimum 30) plus one on a UI request; there is no event feedback path. If one MAC flips more than three times in an hour on a link, the link is paused withflappingand an alert (something else, such as another controller or a UniFi auto-assignment, is writing the same set). - Deletes and absence. A MAC removed from a group on one side is removed from the other (per mode). A device that is deleted (a UniFi client forgotten, a
[[client]]removed) counts as a removal from the group only. Absence from a connected-clients list is never a removal: UniFi members are read from the group object, not inferred fromstat/sta. If the read comes back unparseable, or cut off, the round is aborted, not applied. If it is parseable but empty when B was not (a legitimately emptied group), the round is held as an admin-confirmed preview (the admin may apply the emptying), not aborted for ever. - Mass-change guard. A round that would remove more than
max(5, 20%)of a link's members from either side, or change more thanmax_changes_per_round(default 50), is held: shown as a preview that an admin must apply. The first round of every link (no baseline) is additive only: removals are never applied without an explicit tick in the preview. - Outages. UniFi unreachable, a 401 or 403, or a refused write: the round does nothing, the link is
stalewith the reason (the router's status shows it too), WrenDNS keeps enforcing its current membership, and an alert fires afterstale_alert_rounds(default 5). On recovery the three-way diff against B is safe however long the gap. WrenDNS-side problems (telemetry, storage, API, cluster) never affect DNS answering (CLU-004); a failed config write just fails the round. The sync runs off the main runtime, on its own thread like the inventory (ADR-912), and nothing it does is on the query path. - What policy syncs: group membership only. WrenDNS's categories and lists are DNS-name sets; UniFi's content-filter categories come from a partner's taxonomy and, per the research, may be DNS-level themselves. A mapping between them would look like parity and would not be: a WrenDNS "adult" list and a partner's "adult" category differ in members, update cadence and failure behaviour, and a UniFi category block may be a different layer from a WrenDNS block. Mapping categories would mislead and is not built. What is useful, and cheap, is the shared group: the admin builds UniFi policies against the same device group in UniFi, WrenDNS applies its DNS policy to the same devices, and a device's effective policy page (T24.30) shows the WrenDNS side. The sync never creates, edits or reads UniFi policies, rules or content-filter profiles in the first build; a later task may show, read-only, which UniFi policies use a linked group (Open, T25.18).
- Safety. Every first sync and every held round starts with a dry-run preview that lists each change by side and device, flags private and skipped MACs and unmatched devices, and shows each affected device's change in effective policy (the T24.30 resolver); apply takes the preview's id and is refused if either side changed since (
409 preview_stale). Limits: one write request per second, 50 membership changes per round, reads no more often thaninterval_secs, one in-flight round per link. Audit: one audit record per applied change on the WrenDNS side (group_link.member_addand.member_remove: device, MAC, link, before and after,actor = sync:<id>and the admin who approved the preview), and one per UniFi write, written before the request and completed after it (a write cannot be unaudited); on UniFi's side the write carries a marker in the object's note or description where the object has one ("managed by WrenDNS link <id>"), and whether UniFi's own admin log shows it is to be checked (open). Kill switch:[unifi_sync] enabled(default false; an admin turns it on, an operator or an agent may only turn it off; cluster-wide; effective on the next round with no restart) and a separatewrites_enabled(default false) that must also be true for any UniFi write; each link also pauses. Credential: a separate write credential (ADR-999). Agents and MCP: read tools and plan tools only; applying a preview, and any link whose mode writes to UniFi, is a human admin action (no agent scope applies it, as ADR-903 §5 does for secrets). Agents also cannot cause a gateway write indirectly: any agent-originated change (origin = agent:*:plan_assign_client,plan_update_group,plan_rename_client, a client edit, a deleted[[client]]) that alters the membership of a group linked in a write mode, or turns an unlinked group into one, is refused at apply with403 agent_not_allowedand a reason naming the link; a plan reply sayspropagates_to_unifi, and the admin makes that change by hand. Testdsc_017_agent_membership_change_never_reaches_unifi. - Cluster. One node runs the sync: the primary (spec/12: the one eligible node that accepts config writes), because the sync's WrenDNS-side changes are config writes and must not be proxied from a replica. The gate refuses an ephemeral pod or a witness (as
gate::designateddoes, ADR-930). The write credential reaches full members through M23's replication (ADR-903), so a promoted node has it. The links and[unifi_sync]are shared configuration. The baselines are node-local instate.dband also sent best-effort over the cluster channel; a promoted node without a current baseline starts the link held with no baseline: additive only, removals need the admin. A node that loses the primary role stops at the next round boundary. - Relation to the CMDB (M31, fork #21, T31.1). The CMDB's "definitive source per attribute" is this ADR's per-link direction seen from the CI: for a linked group, the attribute member of group has two sources (WrenDNS configuration, UniFi).
unifi_definitiveis "UniFi is the definitive source for this attribute for CIs in this group",wrendns_definitivethe reverse,two_wayis "no definitive source: merge". The conflict view here is shaped like T31.3's (value per source, the definitive value, the disagreement) so M31 can absorb it. Until M31 exists the link holds the direction and nothing depends on M31. When T31.3 lands, the direction is read as the precedence for that attribute, and a MACD (T31.4) may replace the preview's approval for a new device. This ADR does not decide M31's model; it only must not contradict it.
- The UniFi Content Filter may bypass WrenDNS for a linked group. Because UniFi's filter likely redirects DNS to the gateway (rule 11's research), enabling it on a device group that is synced to a WrenDNS group may stop those queries reaching WrenDNS. The docs (
docs/unifi-sync.md), the help topicunifi-group-syncand the link dialog carry the warning "UniFi Content Filter on this group may bypass WrenDNS"; product text claims neither stacking nor IP-level enforcement until the owner's Q4 test (do queries to WrenDNS still arrive, for a device in the group, with the UniFi filter on?) settles it. The sync itself never reads or changes UniFi's filter.
Alternatives rejected
matching groups by name (a rename silently relinks, and a typo can join a group); one-way polling only (the owner asked for both directions); last-writer-wins for membership (no readable timestamps, and a set has no such conflict); a two-way sync with no baseline (it cannot tell a deletion from an addition, so it would resurrect or destroy members); mapping content-filter categories (misleads, see 11); writing UniFi policies or firewall rules from WrenDNS (a much larger write surface; its own ADR if ever); creating a UniFi group from a WrenDNS group (a second write class; Open); syncing usergroup or firewall address groups (cardinality and IP identity); matching devices by IP when a client has no MAC (a stale address names the wrong device, the reason ADR-902 refused it).
Consequences
a new managed kind group_links, a [unifi_sync] singleton, a sync thread on the primary, a write-capable UniFi client (ADR-999), a Groups-page control, new help topics, and a spec/10 task, T25.18. A WrenDNS operator who can edit a linked group's membership can, in a write mode, change which devices a UniFi firewall policy applies to, and a UniFi admin can move a device out of a restrictive WrenDNS group; both show in the preview, the audit and the effective policy page, and link creation and write modes are admin-only. Until the build's capability check finds a usable device-group interface the task stays at step 1, and the owner is told.
Test plan
in T25.18, against a fake UniFi only (never a real gateway): the merge function by property tests (convergence, idempotence, no removal without a baseline, no oscillation), the echo and flapping rules, outages, the guard, the preview-then-apply flow, audit-before-write, the kill switches, the cluster gate, the credential never appearing in any output, and the Playwright flow.
Owner decisions (2026-11-18). All recommendations for Q1–Q11 are accepted:
- ADR-998 and ADR-999 are accepted, with the read direction shipping first.
- A new link defaults to
unifi_definitive, preview-only,create_missing_deviceson andinclude_private_macsoff. - Writes use a dedicated local UniFi user with the narrowest role that works.
- A round that removes more than 5 members or 20 % of a link is held.
- Operators may change a linked group's membership; links and modes stay admin-only.
- Each link uses the first
unifirouter and one site. - The build comes after T25.10. For step 1, the owner supplies the gateway's OpenAPI JSON when asked.
Q4 measured: UniFi content filtering is DNS-level (sinkhole 203.0.113.250 and port-53 interception). Queries to an internal resolver are not intercepted, and nothing is blocked by IP or SNI. The product wording must say "DNS-level".
Requirements CLU-004 DSC-012
Builds on ADR-080 ADR-902 ADR-903 ADR-912 ADR-930 ADR-999
Referenced by ADR-1004 ADR-1005 ADR-999
Link to this decision · In the specification
ADR-999 UniFi write access: one operation, one credential, off by default, audited before it is sentEverything WrenDNS does to UniFi today is a read (ADR-080, ADR-902, ADR-912), through a [[router]] credential that an admin may well have created read-only.
Context
Everything WrenDNS does to UniFi today is a read (ADR-080, ADR-902, ADR-912), through a [[router]] credential that an admin may well have created read-only. ADR-998 needs the first write: changing the members of one linked group on the gateway. A gateway is the home's firewall; a bug or a stolen credential here is worse than one in a DNS resolver.
Decision
- One write class. The only UniFi write WrenDNS may make is set the members of one linked group object (add or remove one MAC at a time, on the object a link names). No client edit, forget, block or reservation; no firewall policy, zone, ACL, traffic rule, content-filter profile, network, WLAN, device or setting; no object creation or deletion. This is enforced in one function,
unifi_write::member_op, that builds the request from aMemberOpvalue (link, MAC, add or remove) and refuses any other path or method; no other code holds the write credential or an HTTP client for it. A test checks the function against a list of paths it must refuse. - A separate credential, off by default. Credential use is exclusive: the write credential is used only by
member_op(the write) and by the Check button below; the verify re-read after a write uses the read credential, as does every other read. The one stated exception, the Check button, makes one GET of the linked object with the write credential (to show what it can reach) and nothing else;dsc_017_write_credential_never_used_to_readallows exactly that call and fails on any other.[[router]]gainswrite_api_key_ref(orwrite_usernameandwrite_password_reffor a console that only offers a session; the CSRF token is then handled, and the key is preferred). The existing read credential is never used to write, and a write credential is never used to read inventory. Values are write-only secrets through the M23 store (ADR-903): entered withSecretField, never shown, never returned by any route, backup (without a passphrase), support package, MCP tool, audit record or log (api_014_planted_credential_never_returnedis extended to it). A*_filevalue wins, as elsewhere. Only an admin can set or clear it; no agent scope can. - Least privilege, as far as UniFi allows. Public sources say an API key inherits its creator's permissions and has no read-only scope, so the credential is a dedicated local UniFi user made for this purpose (not an administrator's account, not SSO) whose role is the narrowest the gateway's version accepts for editing the chosen group (Network application only; no Protect or Access, no user management, no console settings). The docs explain how to make it, and the Check button reports what the credential can do by that one GET of the target object (the exception in 2), plus the account's role only if that same GET's response carries it (no second call). "Least privilege" is limited by UniFi: there is no object-scoped role, so the credential can probably change the whole Network application and a key may need a super admin to create (ADR-998 research); the protection is WrenDNS's own controls, a session-only local user is the fallback, and the owner must accept the exposure (Q11). Replication of the write credential is limited to nodes that can become primary (not witnesses or ephemeral pods). The real minimum role is not confirmed (ADR-998; T25.18 decision Q6) and the build records what it finds.
- Two switches and a gate on the node.
[unifi_sync] enabledandwrites_enabledmust both be true, and the node must be the primary. Turning either off stops writes at the next round boundary with no restart. A UniFi write is refused if its link is not in a write mode, is paused, isheld, or the preview it belongs to was not applied by an admin. Entering a write mode, or turningwrites_enabledfrom off to on, puts every affected link intohelduntil an admin applies a fresh preview of the UniFi-side writes (applied state is kept instate.db, ADR-998 decision 5); the first write of a link is therefore always previewed (dsc_017_mode_change_to_write_needs_new_preview). - Audited before it is sent. The audit record is written first (
outcome = pending) and completed with the result; if the audit store cannot be written, no request is sent. One record per membership change, with the link, MAC, direction, before and after, the approving admin and the preview id. Rate: at most one write request a second, and 50 changes per round. - Connection. The write goes over the same pinned TLS settings as the router's reads (
tls_ca, the trusted console certificate of T23.8) and refuses plain HTTP to anything but loopback in tests. Redirects are not followed. A 401, 403, 404, 409 or 5xx stops the round (no retry storm), is shown on the link, and is alerted after the configured number of rounds. - Verification and rollback. After a write the sync re-reads the object with the read credential; the baseline advances only if the read shows the change. The audit's before-values allow Undo last round (an admin action that is itself a preview and an audited write).
- Tests never touch a real gateway. The write client takes its base URL from the router entry only; test builds and CI use a local fake (loopback), and a guard in the test support refuses a non-loopback address. No real gateway, resolver, VIP or Home Assistant is contacted by a test or by CI.
Alternatives rejected
reusing the read credential (a read-only key would silently become a write key); a general "UniFi client" that can write anything (a bug could change the firewall); writes without a preview or without a prior audit record; letting an agent apply (ADR-903 §5, ADR-914).
Consequences
"WrenDNS never writes to the gateway" stops being true for linked groups with writes_enabled; docs, the Routers page text and docs/security say so. The read-only direction (unifi_definitive) needs no write credential and is the safe first step. The owner may accept ADR-998 and refuse ADR-999: the sync then ships read-only (UniFi to WrenDNS) and the write directions stay off.
Test plan
in T25.18 (dsc_017_*), against the fake.
Owner decision (2026-11-18). Accepted. The exposure in Q11 is accepted only with the read direction shipped first.
Builds on ADR-080 ADR-902 ADR-903 ADR-912 ADR-914 ADR-998
Referenced by ADR-1004 ADR-998
Link to this decision · In the specification
ADR-1000 Serving several networks: routed by default, directly on a VLAN when the owner wants it; what changes in the nodeT24.32.
Context
T24.32. Owner decision: VLANs reach WrenDNS routed through the gateway by default; document and build what being directly on each VLAN needs, for later. Measured from a tagged VLAN (203.0.113.0/24): a VIP 192.0.2.249:53 and WrenDNS on 192.0.2.12:1053 answer through the gateway; extra 198.51.100.x and 203.0.113.x alias addresses on a node's untagged eth0 time out (an untagged alias address is on the native VLAN's wire, so nothing on a tagged VLAN can reach it). A VLAN whose DHCP hands out the gateway as DNS bypasses the filter.
Checked against the code
- Listeners. UDP (
IP_PKTINFO, the reply comes from the address that was asked) and TCP on0.0.0.0and::answer on every interface address and on a VIP. New tests ask for three local addresses and check the reply's source (dns_001_wildcard_bind_answers_every_local_address_from_that_address,dns_001_tcp_wildcard_accepts_on_every_local_address), and the keepalived e2e proves it on a second network and a second VIP. Nothing to change. - Neighbor table.
rtnetlinkRTM_GETNEIGHwithAF_UNSPECdumps every interface, so a node on a tagged VLAN sees that VLAN's neighbors. Nothing to change. The table is keyed by address alone: two directly attached networks with overlapping subnets would collide. Documented, not handled (a home does not do that). - mDNS naming joined the group on
0.0.0.0, which the kernel resolves to the default route's interface: a node on VLAN interfaces heard only one network. Changed: it joins on every up, multicast-capable, non-loopback interface with an IPv4 address (not containers, bridges or overlays, ADR-910), at most 16, and reads the interfaces again every 60 s so a VLAN interface that comes up later is joined. Newwrendns_net::ipv4_interfaces(getifaddrs, inwrendns-net, whereunsafeis allowed). mDNS is link-local, so a routed VLAN's names still come from the router's leases. - The Networks page listed only router-reported and group networks, so a node directly on a VLAN with no router integration showed none of its own networks. Changed:
GET /api/v1/networksaddssource: "interface"rows for the node's private IPv4 networks (named after the interface, with the VLAN ID from/proc/net/vlan/config), unless a router already reported the same subnet; not in a pod (KUBERNETES_SERVICE_HOST), where the pod network is not a LAN. The page badges them "this node".sourceis a free string, so the OpenAPI shape is unchanged; the description gained the value. - MAC identification across a router. The query path identifies a client by MAC (
[[client]] mac,IdSource::NeighborMac) from the kernel neighbor table only. A device behind a router has no entry of its own (the table shows the router's MAC for the router's address), so a MAC-keyed client never matched a routed device, although the UniFi leases know its MAC. The device identity (identify.rs) already fell back to the leases; the policy did not. Changed: the refresh task (off the query path, every few seconds, only while a client is MAC-keyed) now adds, for addresses the kernel table does not hold, the MAC from this node's router leases (the device's IPv4 and its reported IPv6 addresses; offline leases, empty and all-zero MACs are left out); the kernel's entry wins. The lookup on the query path is the same oneArcSwapload and hash lookup. This extends the router leases of ADR-125 to MAC matching and is an owner-visible behavior change: a MAC-keyed[[client]]now matches a device on another network when a[[router]]reports its lease on this node (the gap below says which nodes).
Decision
- Routed is the default way (each network's DHCP hands out the VIP; the gateway's firewall allows UDP and TCP 53 to it). Client IPs are kept because the gateway routes without NATing DNS; the DHCP must hand out the VIP and not the gateway, or the gateway's own forwarder is the only client WrenDNS sees (ADR-037's masked-client detector says so).
- Direct is documented and built, not required: a tagged interface and a VRRP instance per VLAN; no default gateway on the VLAN interfaces; the same health check drives every instance, so a failing node gives up every VIP.
- The four code changes above (3 to 5, with the e2e), each with tests; nothing on the DNS hot path.
Gaps and conservative choices (for the owner):
- A replica does not fill the MAC map from peer leases (ADR-125 carries names and MACs to replicas in
Names, but the MAC map is built from this node's ownrouter_leases). A MAC-keyed client therefore matches a routed device on the node that polls the router, and on a node that polls its own. Extending it to peer leases is a one-line change in the same task if the owner wants it; left out because a MAC from a peer's lease is a MAC the peer saw, one more thing a stale peer can get wrong. - The Networks page counts devices from router leases and mDNS. A directly attached VLAN with no router shows 0 devices from the neighbor table, because the neighbor table is not the page's source (ADR-910: it feeds the inventory, which has its own page).
- Overlapping subnets on two directly attached interfaces are not supported.
- The e2e's second network is a second Docker bridge with one interface per network, which proves one interface and one VRRP instance per VLAN. It does not run 802.1Q tagging (that needs a switch or the kernel's
8021qmodule on the host); the tagged-interface setup is documented from Debian's NetworkManager and has not yet been run on Pi hardware with 802.1Q.
- Review fixes: the node lists no own network inside a container that is not on the host network (
/.dockerenvor/run/.containerenvpresent, unlessWRENDNS_HOST_NETWORKis set), since a bridgedeth0is a container network. A failed neighbor-table read keeps the last good kernel entries and merges the leases into them. "This node" is the node answering the API.
Alternatives rejected
an untagged alias address per VLAN on a node's eth0 (the measured failure); macvlan per VLAN in the example (ties it to one LAN); making the node read VLAN IDs from the switch (the node has no business talking to the switch); joining mDNS on every interface including containers (names of container addresses are not devices).
Test plan
dns_001_groups_vlan_interfaces_and_vips, dns_001_prefix_from_netmask, dns_001_reads_the_real_interfaces (wrendns-net); dns_001_wildcard_bind_answers_every_local_address_from_that_address, dns_001_tcp_wildcard_accepts_on_every_local_address; dns_001_mdns_joins_every_vlan_interface; api_013_a_node_on_several_networks_lists_each, api_013_vlan_config_parses_only_rows; flt_006_routed_devices_get_their_mac_from_router_leases; Playwright api_013 networks page lists router networks (the this-node badge); deploy/keepalived/e2e.sh with the second network and VIP.
Consequences
a node on several networks hears mDNS on each, lists each, and matches MAC-keyed clients behind a router. No new dependency (libc is already in wrendns-net), no image delta beyond a few hundred bytes of code.
Builds on ADR-037 ADR-125 ADR-910
Link to this decision · In the specification
No decision matches. Try fewer words, or another status or area.