For the technical audience
Decisions ADR-901 to ADR-948
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-901 Device names in DNS: built off the path from the names WrenDNS already has, after configured data, one label eachT22.1 (DNS-023).
Context
T22.1 (DNS-023). People want DNS kept in step with DHCP leases (dnsmasq's and Technitium's DHCP do it) but ADR-091 keeps DHCP with the router. WrenDNS already holds the routers' leases, Home Assistant's names, mDNS names, and named devices, by address.
Decision
- Off by default.
[local] device_domainturns it on (home.arpa, RFC 8375, in the docs);localis refused (RFC 6762).device_ttl60 s (names follow DHCP). mDNS names only withdevice_mdnsand the listener on. - Sources and their order for an address: a named device matched by exactly that address or by the lease's MAC (a CIDR client names a set of devices, so never) → a router's or Home Assistant's name (ADR-902's order) → an mDNS name; this node's routers first, then the peers' (CLU-002).
- One label per name: lowercase ASCII letters, digits, and hyphens, at most 63 bytes; apostrophes dropped, everything else separates words. No punycode: a name with no ASCII letters or digits is skipped.
- Reserved labels:
wpadandisatap(how Windows finds a proxy and an IPv6 tunnel: a device that names itself so could take over other machines' traffic; dnsmasq and Windows DNS's global query block list refuse them) andlocalhostare never device names. - Collisions: one label, one address: the better source, then the lower address, keeps it; the others get neither A nor PTR (half-registered names would point the PTR somewhere the A doesn't). Counted in the log line for each change.
- Where it answers: after
[[record]]and hosts files, after a zone's own records, before the zone's NXDOMAIN or NODATA; never filtered, like other local data. An unknown name under the domain falls through as before (a route may send the domain to the router). - On the path: a
LocalData(the same allocation-free lookup as local records) behind anArcSwapon the pipeline, rebuilt by a task every 10 s only when its inputs changed. The query path checksPolicy::device_dnsfirst: off, one branch; on, one lock-free load and the usual empty-map early return.
Alternatives rejected
a zone generated into the configuration (the configuration is signed, versioned, and replicated; leases change every few minutes); RFC 2136 dynamic updates from the router (UniFi doesn't send them); rebuilding on every lease change (the routers are read every few minutes; 10 s is soon enough and bounded).
Consequences
names appear within about 10 s of a router read; renaming a device in WrenDNS renames it in DNS; the PTRs make reverse lookups of private addresses answer for named devices (RFC 6303's NXDOMAIN still applies to the rest).
Requirements CLU-002 DNS-023
Referenced by ADR-910 ADR-914 ADR-958 ADR-983
Link to this decision · In the specification
ADR-902 More naming sources: UniFi reservations and networks, Home Assistant through a template, and a fixed order when sources disagreeT22.2, T22.3 (API-012, API-013).
Context
T22.2, T22.3 (API-012, API-013). ADR-080 left UniFi's offline known clients undone; Home Assistant knows curated names for IoT devices (by MAC, not IP); a home has a router and Home Assistant naming the same address. ADR-080's lease view kept whichever router was read last (a HashMap walk).
Decision
- UniFi: after
stat/sta, readrest/userandrest/networkconfwith the same key or session. Only known clients withuse_fixedipand afixed_ipare kept (a last address may belong to someone else by now); a connected device's current address wins over its reservation. Networks: the ones with anip_subnet, not WAN or VPN; the subnet from the gateway's address and prefix; the VLAN only when enabled; the pool only when DHCP is on. Both reads are optional: refused or failed, the connected clients still name devices, and one log line says what was skipped (again only when that changes). - Home Assistant (
type = "home_assistant",api_key_file= a long-lived access token): its registry has no REST endpoint, and a WebSocket client would be a new dependency in the binary. OnePOST /api/templaterenders a fixed, read-only template (every device with an entity and amacconnection:name_by_user,name, its MACs, its area; everydevice_trackerwithmacandip). Rendering templates needs an administrator's token; the error says so. Addresses: the routers' answers for that MAC, else Home Assistant's trackers; a device with no address is skipped. Routers are polled before Home Assistant in each round so its devices find this round's addresses. - Order when two sources name one address: a name a person gave in Home Assistant (
name_by_user) → the routers' names, in[[router]]order → a Home Assistant integration's name (often the model:Shelly Plus 1PM). A better source without a name doesn't hide a worse one's. Each lease records the[[router]]that named it (router, optional in the peer wire form, so N-1 peers interoperate). - Networks API is read on the node that reads the routers, like the leases (not federated). Agent tokens read
GET /api/v1/dhcp/leasesandGET /api/v1/networkswithconfig:read(the inventory is no more sensitive than/clients, which already needs it).
Alternatives rejected
a WebSocket client for Home Assistant's registry (a new dependency on the binary for one read); Home Assistant's names always winning (its integrations' default names are model names, worse than a router's alias); known UniFi clients without a reservation (stale addresses would name the wrong device in DNS, T22.1).
Consequences
two more GETs per UniFi poll; one template render per Home Assistant poll (sub-second on a few thousand entities); names in the query log and DNS can now come from Home Assistant.
Requirements API-012 API-013
Builds on ADR-080
Referenced by ADR-901 ADR-907 ADR-910 ADR-912 ADR-942 ADR-998 ADR-999
Link to this decision · In the specification
ADR-903 Secrets entered in the UI: a write-only encrypted store referenced by name, replicated to full members outside configuration versions, with files still winningOn 2026-11-16 the owner asked that anything configured today through a secret file can also be entered in the UI, and that the files keep working.
Context
On 2026-11-16 the owner asked that anything configured today through a secret file can also be entered in the UI, and that the files keep working. The owner fixed four points:
- A secret entered in the UI replicates to full cluster members over the mTLS cluster channel and is re-encrypted on each node. It never reaches ephemeral resolver pods.
- Secrets are encrypted in
state.dbwith a per-node key:<data_dir>/secrets.key(0600) by default, or one that comes from an environment variable or a mounted file. - A backup carries secrets only when they are encrypted with a passphrase given at backup time, and the backup says so when it leaves them out.
- A
*_fileor inline value in the configuration files wins. The UI shows it as set by file and won't edit it.
The code this ADR changes is at commit 412add6.
- Where secrets live now.
- Most are files named by a
*_filepath and read when used:routers.rs:112-119,alerts.rs:737-745,809-817,sinks.rs:719-725,gitsource.rs:205-210,419-422,auth_setup.rs:69-78,wrendns-cluster/src/net.rs:1008-1015. - The rest are inline values:
auth.oidc.provider[].client_secret(schema.rs:2745),upstream[].headers(schema.rs:520-522) andtelemetry.otlp.headers(schema.rs:2388). SafeStringprints the plain value in bothDebugandSerialize(wrendns-config/src/types.rs:49-75).
- Most are files named by a
- Existing leaks.
GET /api/v1/config/entriesreturnsserde_json::to_value(e)(api_backend.rs:2895), so upstreamheadersand execargscome back unredacted. On a replica the primary's body is passed through unchanged (federated.rs:2439-2450).- The write path copies bodies into these places:
- the idempotency table (
config_api.rs:190,1850-1860); - the audit
{before, after}(config_api.rs:1902-1913); - a second audit entry on the primary for every forwarded write (
forward.rs:232-237); - the
keepInGitTOML (api_backend.rs:5223-5260); - the forward to the primary (
federated.rs:2412-2422).forward::WritederivesDebugwith the raw body (forward.rs:31).
- the idempotency table (
wrendns config check --printprints inline secrets (main.rs:1622-1623).- The Git webhook returns the internal error (file path, I/O error) with its 401 to anyone (
api_backend.rs:3285-3289). It also HMACs withsecret.trim(), so an empty secret file gives an empty key that anyone can forge (gitsource.rs:419-432).
- Existing exfiltration paths.
- An operator can point an alert destination's
token_fileat any file the process can read (for example<data_dir>/cluster/ca.keyor/proc/self/environ) and itsurlat their own host (alerts.rs:809-817). - An operator, or an agent with
config:write:upstreams, can create anexec://upstream (validate.rs:19,1462-1468). The plugin is spawned with the parent's whole environment and noenv_clear/env_remove(wrendns-upstream/src/plugin.rs:55-62). Self-update spawns the same way (selfupdate.rs:101,201). - The primary applies a forwarded write with only
by: Stringand no role (forward.rs:34-44,182-191).
- An operator can point an alert destination's
- Precedents for secrets between nodes.
- ADR-045 replicates TOTP secrets, stored as plain BLOBs (
wrendns-store/src/state/identity.rs:33,142). - ADR-051 sends the CA key in
KeyShare(wire.rs:75-83). - ADR-143 withholds identities from ephemeral members (
net.rs:2530-2545). Witnesses are non-ephemeral but serve no DNS or UI (node.rs:39,747-751). - So ADR-045's "never cross the cluster channel" really covers only file secrets.
- ADR-045 replicates TOTP secrets, stored as plain BLOBs (
- Ordering and versions.
- Configuration orders by
(epoch, seq)with abasefor orphan detection (sync.rs:36-60) and is fenced (net.rs:645-647). - Pins and canary rollouts gate everything in
ClusterManifest(spec/12§4, CLU-013). ClusterManifesthas nodeny_unknown_fields, and heartbeats are prost messages, so new optional fields are N-1-safe.- Config structs do use
deny_unknown_fields(schema.rs:3,1249), andwith_sharedrefuses unknown shared keys (shared.rs:84-90). An N-1 replica therefore refuses a version that uses a new field, the same limit ADR quick-rules records (spec/11:1242).
- Configuration orders by
- Startup-only readers.
[[router]](server.rs:1099-1106).resolver_podthere only lowers the log level, so pods do poll today (routers.rs:724-738).- OIDC.
Auth.oidcis aOnceLock,set_oidcsilently ignores every set after the first (wrendns-api/src/auth/mod.rs:315,404,465-467), and in-flight flows live insideOidc.flows(oidc.rs:107,279). - Sinks (
sinks.rs:66-72).Sink::recordtakes&mut self(ring.rs:527) andDROPSis aOnceLock(sinks.rs:52,112). - Alerts, Git and the bootstrap secret re-read at use.
- Settings only in files:
[[router]], OIDC providers, sinks,[cluster.git],[identify]and the Groups form'sdevice_classes. - Spec inconsistency: ADR-045's implementation note says OIDC provider settings replicate, but
authis inNODE_LOCAL(shared.rs:15-26). - Other code facts.
- The release profile aborts on panic (
Cargo.toml:46-51). state.dbruns WAL with nosecure_delete(state.rs:250-254).[api] tlsdefaults to none (schema.rs:2618-2625).- The edition is 2024, so
std::env::remove_varisunsafe(AGENTS rule 7).
- The release profile aborts on panic (
- Already linked:
ring0.17.14 (direct incrates/wrendns),blake3andarc-swap(direct),argon20.6.0 (wrendns-api),zeroize1.9.0 (transitive). The image is about 14.70–14.75 MiB against the 15 MiB gate.
Decision
1. Scope.
| Field | Decision | Why |
|---|---|---|
router[].api_key / api_secret / password (UniFi, OPNsense, Home Assistant token) | In (T23.3, T23.7–8) | The main case. A router whose credential is stored polls on the primary (or a standalone node) only. The others get its names through ADR-125's peer leases, which keeps ADR-125's "not every node polls" rule. A router whose credential is a file keeps polling where it does today, except that ephemeral pods now skip it explicitly. |
alerts.destination[].token / password | In (T23.6) | Read at each delivery, on the primary or a standalone node. |
cluster.git.credentials / webhook_secret | In (T23.12) | Read at each poll or request. Replication means every Git-eligible primary has them. |
telemetry.sink[].token, telemetry.otlp.headers | In (T23.11) | Telemetry never affects DNS (02 §8). On ephemeral pods a sink that needs a stored secret is skipped and logged once at info. |
auth.oidc.provider[].client_secret | In (T23.10) | Only full members serve the UI. |
upstream[].headers, upstream[].tls_client_key | Later | They sit on the answering path, and resolver pods would never have the value (decision 1, CLU-004). Inline and file values keep working, and T23.1 redacts them. |
upstream[].args, URL and proxy userinfo | Out (redacted only) | Not credential fields by design. exec:///unix:// become admin-only (T23.2). |
listen[].tls.key, api.tls.key | Later (P2), status only now | A node's own identity, already hot-reloaded (wrendns-net/src/tls.rs:26-78). Replicating one node's key is wrong, and a bad API key could lock out the UI. |
cluster.bootstrap_secret | Out, status only | Pods need it before the channel is trusted (ADR-058). |
allowed_signers_file, trust_anchors_file, *.tls_ca, signatures_file | Not secrets | A router's CA becomes an inline tls_ca_pem (T23.8). The others stay files. |
Non-secret settings that exist only in files are phased with the forms that need them:
- a
routerkind (T23.7); oidc_providerandsinkkinds (T23.10–11);- Git
*_reffields.[cluster.git]itself stays file-only, pinned byset-authority(ADR-049); identify-settingsand[[group]] device_classes(T23.13).
2. Data model.
- A new table, not
managed. Migration 11 creates:secrets(name TEXT PRIMARY KEY, kind TEXT NOT NULL, key_id BLOB, nonce BLOB, ciphertext BLOB, stamp_epoch INTEGER NOT NULL, stamp_seq INTEGER NOT NULL, deleted INTEGER NOT NULL DEFAULT 0, origin TEXT NOT NULL, updated INTEGER NOT NULL, updated_by TEXT NOT NULL).- A row with
deleted=1is a tombstone with no ciphertext. - Tombstones are kept for 90 days, and at most 512 of them, so offline members still learn of deletions.
- The managed copy paths (
shared_part,config/entries,keepInGit, audit) never see this table.
- A row with
- Stamps. Every change is stamped
(epoch, seq). On a cluster that is the current epoch and a per-epoch counter, taken underfenceand the lease check (may_publish, ADR-056). On a standalone node it is(0, n). A stamp is never reused, delete-then-recreate included. - The secrets head is
{stamp, digest}.digest= BLAKE3 over the sorted(name, kind, stamp, deleted)list. It holds no value and no value hash. - Names match
^[a-z0-9][a-z0-9._-]{0,62}$.kindistext(pemis reserved). - Values.
- At most 8 KiB, UTF-8, trimmed.
- Empty after trimming is refused, and
webhook_secretneeds at least 16 characters. textrefuses every control character (asSafeStringdoes).pemwill allow\n."<redacted>"is refused as a value.
- Limits: at most 128 live secrets, and at most 512 KiB of encoded values in one fetch (section 6).
- References. Each field gets a sibling
<field>_ref = "<name>":router[].api_key_ref/api_secret_ref/password_ref;alerts.destination[].token_ref/password_ref;auth.oidc.provider[].client_secret_ref;telemetry.sink[].token_ref;telemetry.otlp.header_refs = {"<Header>" = "<name>"};cluster.git.credentials_ref/webhook_secret_ref.
These fields are serialized only when set, so configurations without them still converge on N-1 replicas. The UI names a new secret <kind>.<entry>.<field>, while the configuration always holds the explicit name, so a Git-managed file can say api_key_ref = "unifi".
- Validation (
validate.rs):- At most one of inline,
_fileand_refper field. - A missing
_refis a load warning (DNS never depends on the store) and a 422secret_missingon an API write. "<redacted>"in a file is a load error.
- At most one of inline,
- Precedence, judged against the file layer and not the effective entry (decision 4). The file layer is TOML,
WRENDNS_*and CLI; on a replica, for a shared section, it is the primary's file layer as published.- If the file layer sets the field inline or by
_file, the source isinline/file. The UI shows "Set by file (<path>, read on each node)" and whether it is readable on this node. An API write that sets, drops or replaces it, whether by_ref, an ADR-069 override or a hidden entry, is refused with 409set_by_file. An override that changes other fields gets the file's credential field carried over by the server. - Otherwise a
_refgivesstored. - Otherwise the source is
none.
- If the file layer sets the field inline or by
- Kinds.
- One resolver.
wrendns::secrets::Credential::resolve(inline, file, ref) -> Resolved { value: SecretValue, source }replaces the six read sites. SecretValue.- Its
DebugandDisplayprint<redacted>, it has noSerialize, and it is zeroized on drop. - The claim is limited to our own buffers: prost, TLS and stream buffers are not zeroized, and the docs say so.
- Its
- Readable checks open the file read-only with
O_NONBLOCKand close it without reading. A file that isn't a regular file reports "not usable".statalone can't tell readability.
3. Encryption and the node key.
- Cipher. ChaCha20-Poly1305 from
ring::aead, so no new crate. It is fast on a Pi 4, which has no AES instructions. - Nonce: 96 random bits from
SystemRandomper encryption. With a few thousand writes per key this stays far below 2^32. - Associated data:
"wrendns-secret\x01" ‖ key_id ‖ kind ‖ name ‖ be64(stamp_epoch) ‖ be64(stamp_seq), withkindandnameeach preceded by its be16 length (note 39). - Key format.
- A key is 32 random bytes, written as
ttsk1:<base64url, no padding>. key_idis the first 8 bytes ofblake3::derive_key("wrendns secrets key-id v1", key).- Subkeys are derived as
"wrendns secrets aead v1"and"wrendns secrets idempotency v1".
- A key is 32 random bytes, written as
- Key source, first match wins:
WRENDNS_SECRETS_KEY;[node] secrets_key_file(envWRENDNS_NODE_SECRETS_KEY_FILE; the only spelling documented);<data_dir>/secrets.key.
The previous key comes from WRENDNS_SECRETS_PREVIOUS_KEY or [node] secrets_previous_key_file. Both variables join RESERVED (env.rs:22-44). Spawned processes (plugins, self-update) have them, WRENDNS_BOOTSTRAP_ADMIN_PASSWORD* and WRENDNS_TOKEN removed with Command::env_remove; no unsafe. The docs prefer a file, and on Kubernetes secretKeyRef over a literal value.
- Creating the data-dir key.
secrets.keyis generated only when thesecretstable holds no rows and no tombstones.- It is created with
O_CREAT|O_EXCL, mode 0600, written and fsynced, never renamed over an existing file. - A key file readable by others, or owned by another user, gives a warning. Group read by the process's own gid doesn't warn (kubelet with
fsGroup).
- It is created with
- Rotation.
- At start, rows under the previous
key_idare re-encrypted in one transaction, followed bywal_checkpoint(TRUNCATE). wrendns secrets rotate-keyis offline and covers the data-dir key only. It writessecrets.key.new, re-encrypts, commits, checkpoints, then renames. A leftover.newfile is tried bykey_idat the next start.
- At start, rows under the previous
- Locked store. The store is locked when:
- a configured source (1 or 2) can't be read or parsed;
- source 3 is missing while rows exist;
- or no row decrypts under any available key.
While locked:
- nothing is generated, and secret writes return 503
secrets_locked; - status reads work, and health shows
secrets_locked(degraded, OBS-015); - DNS and
/readyzare unaffected.
One exception: a replica whose rows are all origin='cluster' may generate a new key, drop those rows and refetch.
- Row states. A row whose
key_idmatches neither key isunreadable, and one that fails authentication iscorrupt. Re-entering the value, or a sync, repairs it. - When a secret can't be read. An integration that needs an unreadable secret reports "not configured: secret
<name>can't be read on this node (<reason>)" and logs once until that changes. The metric iswrendns_secrets{state}. - Threat model (
docs/secrets.md).- With the data-dir key, the store protects copies of
state.dband backups, not someone who holds the whole data directory. - Admins are trusted not to misuse a stored secret, but cannot read one back (except through a passphrase backup, section 8).
- Operators and agents can neither read nor redirect one.
- With the data-dir key, the store protects copies of
4. API and rules.
- Routes.
GET /api/v1/secrets[/{name}](operator; agents withconfig:read) returns metadata only:name,kind,set,stamp,updated,updatedBy,origin;usedBy [{kind, name, field, source, node?}];nodes [{node, applied, unreadable}];credentials: every credential field on this node with its source, its path and whether it is readable.
On a replica this is proxied to the primary when one is reachable (as config_entries is). Otherwise it is local with stale: true.
PUT /api/v1/secrets/{name}takes{"value", "kind"}, andDELETE /api/v1/secrets/{name}. Both need admin, answer with metadata only, and carryCache-Control: no-store.DELETEof a referenced secret is 409secret_in_use, listing users across nodes (section 6). If a full member's references are unknown (offline), it needs?force=true.
- Transport.
PUT /secretsand a passphrasePOST /backupare refused with 403insecure_transportunless the request is HTTPS (is_https, including trusted proxies) or comes from loopback.[api] allow_secrets_over_http = true(node-local, file only) lifts this.- The UI explains and links to
[api] tls = { self_signed = true }(ADR-149).
- Agents: 403
agent_not_allowedon secret writes whatever the scopes. - AGT conformance.
- AGT-001:
valueiswriteOnly. - AGT-002:
?dryRun=truechecks name, kind and size, reportswouldCreate/wouldReplaceand the entries that would become configured, and stores nothing. - AGT-003: the stored request is
PUT /secrets/{name}plus the hex keyed BLAKE3 of the value under the idempotency subkey. The same key with a different value is 409. - AGT-005: audited as
secret.put|delete {name, kind, stamp, usedBy}, never the value or its length. If-Matchtakes the secrets head as an ETag.
- AGT-001:
- On a replica, writes are forwarded to the primary as a dedicated RPC kind
secret.put/secret.delete, not a variant ofapi.write, so an N-1 primary refuses it by kind.- The value travels as
SecretValue, and the request type'sDebugredacts. - The forward carries
roleandagent(below), and logs only the operation and the name. - With no primary reachable, the answer is 409.
- The value travels as
- When writes are allowed.
- Lease and fence: a primary without a valid lease, or past the fence, refuses with 409.
- GitOps authority: secret writes are allowed (secrets are state, never in Git, ADR-049); entry writes stay 409
gitops_managed. - Emergency primary: 409.
- Pin or canary rollout: allowed. The secrets head travels outside
ClusterManifest(section 6), so pins and rollouts neither hold it back nor bumpseq.
- Credential rules for entries (T23.2):
- Creating or changing any
*_fileor*_ref, or the destination fields of an entry that has any credential (inline, file or ref), needs admin. Destination fields areurl,proxy,host,tls_server_name,tls_ca,bootstrapand the scheme. - The
router,oidc_providerandsinkkinds are admin-only. - Creating, or switching to, an
exec://orunix://upstream needs admin, on writes and onchecks/upstreamalike. - API-set paths:
- are canonicalized at write and at use;
- must not be under
/proc,/sys,/dev,data_dir, or any configured key, previous-key, bootstrap or TLS key path, and these denials apply to every API-settable path (list[].path,tls_caincluded); *_filemust also sit under[node] secret_file_dirs(node file only; default/run/secrets,/var/run/secrets,/etc/wrendns/secrets).- An existing API-set path outside these rules stops being read and reports the reason in
credential_issues.
- An admin write that changes the destination of an entry with a
_ref, or points a_refat a secret already used by a different kind, is audited ascredential.redirectand raises the alert eventcredential_redirected. - Forwarded writes carry
roleandagent, and the primary re-checks every rule. A credential-affecting write forwarded without a role (an N-1 replica) is refused with 409upgrade_required.
- Creating or changing any
- Redaction everywhere bodies are copied (T23.1).
wrendns-config::credentials::PATHSlists:upstream[].headers.*,upstream[].args[*];- URL userinfo passwords in
upstream[].url,upstream[].proxyandalerts.destination[].url; auth.oidc.provider[].client_secret,telemetry.otlp.headers.*.
- It is applied by:
config_entries(again on a replica after decoding);- write responses, both audit sites (
config_api.rs:1902-1913,forward.rs:232-237,apply_ack); - the stored idempotency response;
keepInGit, forward logging,config check --print(--show-secretsopts in);GET /cluster/compare, every MCP read tool and resource, and the support package.
- Values come back as
"<redacted>", andConfigEntry.redactedlists the paths. - The marker rule: a PUT that sends
"<redacted>"keeps the current value only when the entry's destination fields are unchanged. Otherwise it is 422credential_reentry_required. With no current value it is 422 too.POST /checks/*never resolves markers. - Idempotency. The stored request is the keyed BLAKE3 of the canonical full body (node key, idempotency subkey), and the stored response is redacted. With the store locked, a write carrying an
Idempotency-Keywhose body holds a credential path is 503. - Migration 10 purges existing idempotency rows.
state.dbgetsPRAGMA secure_delete=ON, pluswal_checkpoint(TRUNCATE)after the migration, after rotation and after secret deletes. - A test fails when a field classed
secretinwrendns-support/src/classify.rsis in neitherPATHSnor a reasoned allow-list (usernames).*_reffields are classname.
- The Git webhook answers a generic 401 and logs the detail, and refuses empty secrets.
- Delivery errors keep hosts only, never URL queries. The Gotify token is percent-encoded (
alerts.rs:821-825).
5. MCP and agents.
- New read-only tools.
secrets_statuswrapsGET /api/v1/secrets(config:read).list_routerswrapsGET /api/v1/routers. - No write tools for secrets, or for the
router,oidc_provider,sinkoridentify-settingskinds. These have no agent scope. A value would otherwise sit in AGT-007 plan memory, the approval diff and the agent's transcript, as with OPS-011 and ADR-156. - Plans meet the marker rule. MCP plans that merge from
config/entries(mcp.rs:2321,2372) carry"<redacted>", so a plan that changes an upstream's destination fails at apply withcredential_reentry_required, and the plan summary says so. - Agent forbidden list.
POST /api/v1/backup,/checks/router*and the secret writes join it (agent.rs:590-598). - spec/13 §3 records these exceptions.
6. Replication (CLU-015, decision 1).
- The head travels in heartbeats, not in configuration. The primary's
Heartbeat(prost, new optional tags) carriessecrets_head {epoch, seq, digest}. Nothing goes inClusterManifest, so pins, canary bakes,If-Match configVersion, version history and lag are unaffected. N-1 nodes ignore the tags (CLU-010). - Fetching. A full replica sends the RPC
secrets.fetch {since_digest}when the head's digest differs from its own.- It sends it only to the node it holds as primary of the highest epoch it has seen, and ignores a head from a lower epoch (
spec/12fencing rule 4). - Fetches happen at most once per head, back off from 30 s to 10 min on failure, and never run while the local store is locked.
- Fetching never gates manifest application,
appliedor readiness (ADR-058).
- It sends it only to the node it holds as primary of the highest epoch it has seen, and ignores a head from a lower epoch (
- The primary answers only a peer that its registry records as
!ephemeral && !witness.- The answer is
{head, items: [{name, kind, value?, stamp, deleted, updated, updated_by, held?}]}. - A row the primary can't decrypt is sent as
held(no value), and the replica keeps its own row with that stamp. - A locked primary, or one that generated a new key, answers
secrets_unavailable, and replicas keep their set. - An emergency primary still answers.
- The answer is protobuf
bytes, capped at 900 KiB encoded and paged beyond that. It never touches the blob store, so no plaintext reaches anyone's disk.
- The answer is
- The replica checks that the answer's head equals the announced head and that the digest recomputed from the items matches. Otherwise it discards the answer.
- Applying.
- The replica re-encrypts each value under its own key.
- In one transaction it upserts
origin='cluster'rows by stamp: a higher stamp wins, and a tombstone deletes. - It never deletes a name by its absence from the set.
- Orphans. Rows a demoted primary stamped in an epoch after the new primary's base are orphaned. They are not deleted, but listed under Conflicts as "re-enter on the current primary" and not used.
- Origin.
- On the primary every row is authoritative and stored as
origin='cluster'. Atcluster initand at join, a standalone node's rows become cluster rows on the primary. - On a joining replica, local rows stay usable on that node, and are flagged
shadowedwhen a cluster row of the same name arrives. - On removal (ADR-155) or leave, cluster rows are purged and the purge is audited.
- On the primary every row is authoritative and stored as
- Reverse heal. A primary with unreadable rows fetches them from a registry-full replica holding the same stamp. The replica answers only the current primary.
- Heartbeats from members carry
secrets_applied(head),secrets_unreadable,credential_issues(at most 32 paths) andsecret_refs: the names this node's node-local fields reference, at most 128, sent on change and every 60 s.DELETEchecks the union of these. - Ephemeral pods hold no secrets, need no key, never generate
secrets.keyand never reportsecrets_locked. - Node-managed entries (
oidc_provider,sink) are configuration, not secrets, so they are versioned.ClusterManifestgains an optionalnode_managed: BlobRefholding references only, which N-1 nodes ignore.- Every member persists the last one it applied.
- Each member validates and merges it separately from the shared part, under its own files, where file ids win. A failure drops only those entries, logs once, and leaves the shared part and DNS untouched (CLU-004).
- A newly promoted primary publishes the inherited blob overlaid with its own rows, and seeds its managed rows from it.
- A primary with a Git source carries the blob unchanged, and writes of these kinds there are 409
gitops_managed. - Ephemeral members skip entries that need a stored secret, with one info log.
7. Hot reload. Nothing here touches the query path.
- Routers.
routers::runreads the live[[router]]fromSourcesat each round, and no longer returns on an empty list. It recomputesintervaleach round.- Changed or removed routers are rebuilt or dropped, and unchanged routers keep their state.
- A
Notifyon a router or secret change polls, debounced to at least 5 s. - Polling follows section 1's rule: stored credentials on the primary or a standalone node, file credentials as today, and ephemeral pods skip explicitly.
- Failures are logged once until they change, and names stay as last read.
- The release build aborts on panic, so
routers.rsgetsclippy::unwrap_used,expect_usedandindexing_slicingdenied, and malformed answers are tested.
- OIDC.
Auth.oidcbecomesArcSwapOption<Oidc>.- In-flight flows (PKCE verifier, nonce) and the discovery cache move into
Auth, so a swap keeps sign-ins in progress. - Rebuilds run one at a time with a generation counter, and a stale result is discarded.
- A provider whose discovery fails keeps its previous settings, or is left out with a reason.
- Sessions and the break-glass admin are untouched.
- Sinks.
- The drainer-owned
EventSinksreceives a newVec<Out>through a channeltry_recvonce per batch. DROPSbecomes swappable.- Spill files are keyed by name plus a hash of the URL. A removed sink's thread is joined (2 s bound) before its name is reused, and its spill file is deleted.
- OTLP headers are resolved per export batch.
- The drainer-owned
- Alerts and Git use the resolver at use. The store keeps ciphertext in memory and decrypts at use.
8. Backups (amends ADR-063 and API-007).
- Never in a backup: the
secretstable, its tombstones and the head. They are dropped likesessionsandidempotency(backup.rs:302), andsqlite_copyvacuums. The node key is never included either. - With a passphrase of at least 12 characters, the archive gains
data/secrets.enc:- ChaCha20-Poly1305 over the JSON list
{name, kind, value, updated, updated_by}; - the key from Argon2id v1.3, m = 19,456 KiB, t = 2, p = 1 (the same as password hashing), with a 16-byte salt and 32 bytes of output, parameters recorded;
- a 12-byte random nonce;
- associated data
"wrendns-backup-secrets v1" ‖ backup_id.
- ChaCha20-Poly1305 over the JSON list
One KDF runs at a time per process; a second request gets 429. Restore refuses m > 256 MiB or t > 10.
- Manifest and version. The manifest gains
secrets {included, count, omittedReason?, kdf, aead, nonce, backupId}.VERSIONbecomes 2 only whensecrets.encis present, so older builds refuse it; archives without secrets stay version 1. - Without a passphrase, the CLI, the API header and the UI all say "N stored secrets were left out". The backup also warns when the configuration files or
managedrows hold inline credentials, which are copied as they are. - Restore (offline):
--secrets-passphrase-file F, a TTY prompt, or--skip-secrets. A version 2 archive with neither is refused before anything moves.- A wrong passphrase reports "wrong passphrase or damaged archive" and moves nothing.
- The key is resolved from the same configuration (
-c) and environment as the server. Restore refuses, rather than generating, when a configured source is unavailable, and prints the source andkey_idit used. - Rows are re-stamped in the restoring node's current epoch, inside the staged
state.db.
- API.
POST /api/v1/backup(admin; not agents; HTTPS rule from section 4) takes{includeQlog?, passphrase?}and answers withX-Wrendns-Backup-Secrets: included|omitted; count=N.- With a passphrase it needs an interactive session signed in within the last 10 minutes; tokens get 403
reauth_required, with a hint to runwrendns backup createon the node. - It is audited as
backup.create {secretsIncluded, count}, and with secrets included it raises the alert eventsecrets_exported. - It takes no
Idempotency-Key, because it changes no state. GET /api/v1/backupstays and omits secrets.
9. UI.
- Settings → "Integrations & secrets":
- stored secrets (name, used by, updated, by, readable per node, Replace, Clear);
- credential fields set by file (path, readable on this node);
- store state (key source, locked/unreadable/ephemeral);
- orphaned rows.
SecretField.svelte:- a write-only
type=passwordinput, never pre-filled, withautocomplete="off",spellcheck="false",data-1p-ignore,data-lpignoreand no show toggle; - states: Not set, Set (updated, by), Set by file, Inline in the file, Unreadable on
<node>, and Can't be set over plain HTTP.
- a write-only
- Saving is
PUT /secrets/<auto-name>, then the entry with_ref. A failure in between leaves at most an unused secret, which the page lists. - Every "?" has a help topic.
10. What this amends.
- ADR-045: the channel rule covers file secrets only, and its OIDC implementation note is corrected.
- ADR-048 and OPS-005: secret writes are allowed under GitOps authority.
- ADR-049: references by name.
- ADR-063, API-007: section 8.
- ADR-069: credential fields of alert destinations follow section 2 rule 1.
- ADR-116 and CLU-013: secrets are not configuration versions; pins and rollouts don't gate them.
- ADR-120: "key files at the same paths" or a stored secret. Stored-credential routers poll on the primary.
- ADR-125: confirmed for stored-credential routers.
- ADR-156: the credential table moves to
wrendns-config, and*_reffields are classname. - T9.6:
- The criterion becomes "secret values pass only through
/api/v1/secrets". config:write:alertsno longer covers credential or destination fields of a destination that has a credential, so thoseplan_*alert changes get 403.
- The criterion becomes "secret values pass only through
- Also: the comment at
config_api.rs:656-657; spec/08 §3.3, §6 and §8; spec/12 §4 and §6; spec/13 §3.
New direct dependencies. No new crates are added.
zeroizebecomes a direct dependency ofcrates/wrendns. It is already in the lock through RustCrypto, and it is needed forSecretValue.argon2becomes direct there too, forbackup.rs. It is already linked throughwrendns-api.
Alternatives rejected
- Reusing
managedfor values: every copy path would carry them. - A shared cluster key,
privacy.keyor the CA key: one node's compromise would expose everyone's, and decision 2 says per-node keys. - Values as content-addressed blobs: replicas write blobs to disk.
- The secrets head in
ClusterManifest: every secret write would become a configuration version, gated by pins and rollouts. - Deletion by absence: one primary that can't read its rows would wipe every replica.
- A plain per-node counter as the version: it goes backwards after failover.
- Router secrets only on the polling node: that breaks when the primary moves, and the owner chose replication.
- Every full member polling every stored-credential router: ADR-125 rejected it.
- Secrets on ephemeral pods: decision 1.
- Upstream refs now: pods answer most queries and would lack the value.
*_secretsuffixes, or*_file = "secret:<name>": awkward names, overloaded paths.- Values in entry bodies: that is the general write path again.
- Plain HTTP allowed silently: the value would cross the network in clear.
env_clear()for plugins: it breaks plugins that needPATHor proxy variables.env_removeof the named variables plus admin-onlyexec://covers the risk, since a same-user process could readsecrets.keyanyway.- Argon2 at m = 64 MiB inside the DNS process: it competes with NFR-001's working set.
- The
chacha20poly1305/aes-gcmcrates:ringalready provides the cipher. AES-256-GCM: slower on a Pi. - MCP write tools, or operator role for secret writes: both are exfiltration paths.
- UI-made OIDC providers and sinks kept node-local: each node would need its own write route, against the single management plane.
Consequences
- Who benefits. Home and Pi users can run routers, alerts, Git, sinks and OIDC from the UI. File and Kubernetes Secret setups behave as before and win.
- Timing. A secret set on any node reaches every full member within one heartbeat plus one RPC. Resolver pods still need
*_filemounts for sinks and OTLP. - Behavior changes (T23.2):
- Operators and agents can no longer change
*_filepaths, credential-bearing destinations, orexec:///unix://upstreams. - Existing API-set file paths outside
secret_file_dirsstop being read. - Stored-credential routers poll on the primary only.
- Operators and agents can no longer change
- Mixed versions (CLU-010). As with quick rules, an N-1 replica refuses a configuration version that uses a new
*_refortls_ca_pemfield, and keeps its last good version until it is upgraded. An API write that adds one warns, naming the older members. Credential-affecting writes forwarded by N-1 replicas are refused. - Plain HTTP. Secret entry over plain HTTP from another host is refused unless
[api] allow_secrets_over_httpis set. - Helm.
- The default key lives in the data directory.
secretsKey.existingSecretis recommended.secretsKey.generate=true(Helmlookup) is documented as unsafe underhelm templateor Argo CD.- With persistence off, stored secrets are lost at every restart, and the health reason
secrets_ephemeralsays so.
- Unchanged: the query path, and the crate list. Image growth is limited to 0.10 MiB for the milestone, recorded per task.
- Old audit entries. Entries written before T23.1 may hold upstream headers and can't be rewritten (hash chain). The release note says so.
Owner decisions on the open questions (2026-11-16):
- The admin-only credential rules (T23.2) ship right away, with T23.1, not with the UI.
- Upstream credentials (
headers,tls_client_key) stay file or inline only, redacted everywhere; no task sends secrets to resolver pods. - OIDC providers and sinks made in the UI reach every full member as node-managed configuration; providers and sinks defined in files stay per node.
- Entering a secret over plain HTTP from another host is refused unless
[api] allow_secrets_over_http = true. - Agents get no write scope for router or
[identify]fields for now (admin-only, as above). Revisit after T23.8. - Audit entries written before T23.1 stay as they are (the hash chain forbids rewriting); the release note warns about them.
Implementation notes (T23.1, 2026-11-16; Proposed, for the owner):
- Sites with nothing to redact.
apply_ackaudits finding IDs and a count, never a configuration body, so it is unchanged.compare.rs(GET /cluster/compare) carries only numbers and node labels. The surfaces that do carry shared configuration are the pin and version diffs (rollout/surface.rs, also the 409cluster_pinnedbody): both sides are redacted before the diff.GET /upstreams'endpointgoes through the URL redaction too. - Checks and markers. "Checks never resolve markers" is implemented as a refusal:
POST /checks/upstreamwith<redacted>at a credential path is 422credential_reentry_required, so a check never runs with a literal marker as a header. - Destination comparison. Absent,
null,""and[]count as the same value; URLs are compared with their passwords replaced by the marker, so a changed user name or host is a changed destination. A URL's user information runs to the last@before any?or#(conservative: a stray/in a password is still redacted). - The node key in T23.1.
wrendns::secretsloads the key at start on full members, in a blocking task (DNS never waits for it). With nosecretstable yet, the data-directory key is made whenever it is missing; T23.3 adds the empty-table condition and the locked state. A key file with any "other" permission bit or group write warns; the owner check needs the process's uid (nolibcin the binary) and is left to T23.3.zeroizeisn't used yet (it becomes direct in T23.3). - Idempotency without a key. With the key unavailable, a write carrying
Idempotency-Keyand a credential is 503secrets_locked(the code is added now); one without a credential keeps a plain BLAKE3 of the request, which holds nothing secret. - Delivery errors. Besides percent-encoding the Gotify token, an HTTP error that quotes the request has the token replaced by the marker.
- Release notes.
deploy/release/notes/v0.8.0.mdis started as a draft with the upgrade items (older audit entries, the purge, the new key), andpreflight.shrefuses notes whose first line begins_Draft.
Implementation notes (T23.1 review fixes, 2026-11-16; Proposed, for the owner):
- Every URL field. §4's table names three URL fields; the support package classes eleven more
url(upstream[].relay,list[].url,router[].url,cluster.git.repo,cluster.join_url,telemetry.otlp.endpoint,telemetry.ship.to,telemetry.sink[].url,updates.index_url,auth.oidc.public_url,auth.oidc.provider[].issuer). All are inPATHSas URL passwords, and the completeness test now also fails for aurl-class field missing from it.listis an entry kind for redaction and the marker rule, andPOST /checks/listrefuses markers like the upstream check. A URL that sends the marker keeps its password only while that URL itself is unchanged (it is replaced whole by the stored one), so a field that isn't a destination (relay) can't carry a stored password to a new host. The Cluster page'srepo(and a Git error quoting it, and theconfig.gitaudit entry),GET /lists'sourceand fetch error (the walk found it once a list URL was planted), and a router's errors are redacted too. - Markers and an N−1 primary. A replica forwards a body that sends
<redacted>back only to a primary whose advertised version is at least 0.8.0 (forward::MARKERS_SINCE); otherwise 409upgrade_required(a new code, which T23.2 reuses for role-less forwards). A primary whose version is unknown counts as older. Resolving markers on the replica instead was rejected: the replica's copy can lag the primary's and would restore an outdated value. - Plans.
Plan.bodyis shown redacted (GET /plans,list_plans, approve and reject); the bodyapply_planreplays is kept apart (write_body, never serialized).wrendns-apinow depends onwrendns-configfor the table (a workspace crate, no new dependency). - Pin diffs. Both sides are redacted before the diff; a credential that changed while reading the same redacted (a header's value, only a URL's password) is added as a
replacewith the marker as its value, so a pin that holds back only a credential change still shows one. - Smaller points.
keepInGittext from an older primary that doesn't parse is replaced by its leading comments and a note, never passed through. A body whose credentials are all markers holds no credential (no 503secrets_lockedfor it). A failed key load is retried after 30 s instead of kept until restart.secrets.keyis written tosecrets.key.tmp(O_EXCL, 0600, fsync), hard-linked into place (no replace), and the directory synced. The Gotify token is scrubbed from errors in its percent-encoded form too. Plugins inherit noWRENDNS_*variable butWRENDNS_PLUGIN_SOCKETandWRENDNS_UPSTREAM(environment configuration can carry credentials); the self-update keeps the named list, since the restarted server needs its own settings.
Implementation notes (T23.2, 2026-11-16; Proposed, for the owner):
- Credential files.
alerts.destination[].token_file/password_fileandupstream[].tls_client_key(§1 classes the client key a secret) are the credential files: changing one is admin-only and an API-set one must be under[node] secret_file_dirs.tls_ca,tls_client_certandlist[].pathget the denied places only.credentials::API_PATHSlists them, andapi_014_api_paths_cover_path_fieldsholds it to the support package's path-like fields of those kinds. - "Stops being read". Done where the API's entries are merged (
managed::merge, on the primary or a standalone node): a refused path is replaced by/proc/wrendns-refused/<field>, where nothing can be read, so the list or alert fails as with a missing file (an upstream's is cleared instead: note 22). It is judged by that node's settings, and replicas receive the result with the shared configuration. A path an override keeps from the files' entry of the same name is the files' (an operator editing a file-defined email destination doesn't break itspassword_file). At write, only paths that change are checked; stored ones are judged at use.credential_issuesis shown now asConfigEntry.credentialIssues(and a warning at each reload); the heartbeat field (T23.5) andGET /secrets'credentials(T23.4) reusecredential_rules::issues. - Redirect audit and alert. Until
*_refexists (T23.3),credential.redirectcovers an admin's destination change of any entry that holds a credential (a header or argument, a URL password, a credential file), not only one with a_ref; "a_refpointed at a secret of another kind" comes with T23.3. The record is made where the change is applied (so a forwarded one gets it on the primary), with the user as asystemactor, beside the usual<kind>.put; the dry run warns.AlertWhen::CredentialRedirected(credential_redirected) reads the last hour of those records, once each (a one-off condition). As with any new condition, an N−1 replica refuses a configuration version whose rule uses it. - Programs. Besides creating or switching to
exec:///unix://, changing an existing plugin'surlorargsis admin-only (they are what runs); its weight or timeout stays an operator's. A forwarded domain's servers become upstreams, so anexec:///unix://server there is admin-only too (it was a way around the rule).POST /checks/upstreamwith atls_client_keyis admin-only as well, and a draft's paths are confined (the check reads them). - Role-less forwards. "Credential-affecting" is: any admin-only change, or an entry that holds or would hold a credential. Other writes from an N−1 replica still apply, so a rolling upgrade keeps working for them. A new replica forwarding to an N−1 primary isn't refused for these rules (the older primary never checked them; upgrading the primary first is already the advice).
- Who counts as admin. The admin role and no agent token: an agent token is never admin here, even with
cluster:adminand an admin owner (§3's threat model). The marker rule's 422 comes before the role rule's 403. Problem codes:path_not_allowed(422) is new, andupgrade_required's title becomes "Upgrade needed" since it now also names an old replica. - Paths. Absolute only, no
.., compared after following every symbolic link, a dangling one included (followed by hand, so a link can't wait for its target). The denied files are[node] secrets_key_fileandsecrets_previous_key_file,[cluster] bootstrap_secret_file, andlisten[].tls.keyand[api] tls.key; the data directory coverssecrets.key, the cluster's certificates andstate.db.[node] secret_file_dirsis read from this node's files and environment (nodenever leaves a node). The check is at write and at each reload, on the resolved path, but the configured string is read: a link swapped between reloads is followed (note 26). - UI.
ConfigEditorfields takeadmin(always, or decided from the entry as read); the Alerts page shows the token and password files to operators read-only, and the address and CA once the destination holds a credential. Rows with a refused path show "<field> not read". The Upstreams page isn't marked yet (the API refuses the same changes with a 403 that names the field).
Implementation notes (T23.2 review fixes, 2026-11-16; Proposed, for the owner):
- Destination fields. §4's list (
url,proxy,host,tls_server_name,tls_ca,bootstrap) gainstls_insecure_skip_verifyandspki_pins(turning certificate checks off, or swapping the pins, sends the credential to whoever is on the path, which is worse than a new CA) and an alert destination'stype(it changes how the credential is sent). They count for the admin-only rule and for the marker rule alike; absent andfalseare the same value. - Refused upstream paths (CLU-004). Note 14's
/proc/wrendns-refused/<field>is kept for alert destinations and lists, which read their files when used. An upstream reads its TLS files when the router is built, and one it can't read fails the whole configuration (the node would start answering nothing, on every replica that restarts). So a refusedtls_ca,tls_client_certortls_client_keyof an upstream is cleared instead: the upstream runs on the system's roots, without a client certificate (its certificate and key are cleared together, since one without the other doesn't validate). No refused file is read and no credential is sent anywhere new; an mTLS server refuses the connection, and the group fails over. Dropping the upstream was rejected: it would empty groups (invalid) and drop routes. - Paths that aren't a credential's.
tls_ca,tls_client_certandlist[].pathmay not name a credential file this node's own configuration uses (an upstream's client key, an alert destination's, router's, sink's or OIDC provider's file, the Git credentials and webhook secret), and a list'spathmay not be undersecret_file_dirs(a secret that parses as a name becomes a ruleGET /explainconfirms, and a line that doesn't is quoted in the list's error). A CA or client certificate may still sit in a secrets directory, beside its key./var/run/secrets/kubernetes.io(and/run/secrets/kubernetes.io) is denied for every API path, admins included: the defaultsecret_file_dirscovers it, and the pod's service-account token is never a file an entry should read. The default directories are unchanged; denying the subtree is the conservative reading of the ADR's default. - A promoted primary. A primary promoted from replica builds on the last cluster version (ADR-051), so "the files' entry of that name" is judged against the node's own files (
managed::merge_on), not that version: a path an older primary published as the API's is judged, not taken for the files'. Writes already compared against the node's own files (Sources::file_config). - Deviation: replicas don't judge again (for the owner to accept). §4 says paths are checked at write and at use. Here the node that merges the API's entries (the primary, or a standalone node) judges them with its own rules, and a replica uses what it receives: the shared configuration doesn't say which entries the API made, so a replica can't tell an API path from one in the primary's files (which are never confined), and judging every path there would break file-defined ones. A path that is fine on the primary can thus be in a replica's own data directory or key file when the two differ. Closing it needs the version to carry which entries are the API's; proposed with T23.5 (heartbeats carry
credential_issues). - Smaller points. The
credential_redirectedalert names only the new address's scheme and host (a URL's path can hold a secret, and the alert goes to every destination of the rule); the audit record keeps the rest. The alert reads the last hour of the applying node's audit log, so a change applied just before a failover isn't alerted by the new primary (documented). A path is resolved and checked, but the configured string is what's read later, so a symbolic link swapped between reloads is followed; only someone who can write a secrets or listed directory can do that, which is outside §3's threat model (note 19). - T23.2 is ticked with AC7 and AC8 open, as T23.1 was: the Playwright test is written but hasn't run (no browser in the dev container), and no image was built to record the size delta. AGENTS.md rule 10 says done means the criteria pass in CI; the owner accepts the tick, or it is unticked until CI has run both.
Implementation notes (T23.3, 2026-11-16; Proposed, for the owner):
- One store per process.
wrendns::secrets::SecretStoreis made at start without I/O, loaded in a blocking task, and retried every 30 s while locked (a key mounted later unlocks it without a restart). It also owns T23.1's key slot, so the idempotency hashes and the store use the same key, and "made only for an empty table" covers both. A configured key that can't be read leaves no key for the idempotency hashes either (503 as before). - The replica's self-heal runs from that upkeep when the cluster says this node is a replica and the store is locked, only for the data-directory key (an unreadable
WRENDNS_SECRETS_KEYorsecrets_key_fileis whoever configured it to fix, and generating beside it would hide the mistake) and only when every row isorigin='cluster'. It drops the rows and starts over with a working key; fetching them again is T23.5's. secrets_ephemeralneeds to be told. A node can't tell anemptyDirfrom a volume, so the chart setsWRENDNS_DATA_EPHEMERAL=1(a reserved variable, not a configuration key) on the controller whenpersistence.enabledis false; any other deployment may set it. The reason shows only while secrets are stored, so a fresh install without persistence isn't degraded.- The read sites.
Credential::resolve(inline first, then the file, then the reference: the files win even if a merge somehow kept two) replaces the routers' reads (UniFi, OPNsense, Home Assistant), alert tokens and email passwords, sink tokens, the Git credentials and webhook secret, and the OIDC client secret; OTLPheader_refsare resolved per request. The cluster bootstrap secret (wrendns-cluster/src/net.rs) keeps its plain file read: §1 makes it status only, and it lives in another crate. - "The files win" at write and at merge. §2's rule 1 is implemented for alert destinations, the only API kind with a stored field so far: an override that leaves a file-set credential out has it carried over; one that sets, replaces or removes it is 409
set_by_file; aDELETEthat would hide a file-defined destination with a credential is refused too (the ADR's "a hidden entry"), a behavior change named in the release note. At merge, a file-set credential replaces whatever an override stored for it (an override saved before the files set it), so the merged entry keeps one source per field. The router, OIDC provider and sink kinds reusesecret_refs::carry_file_credentialswhen they arrive (T23.7, T23.10, T23.11). The file layer judged is this node's own files, as T23.2's paths are (note 24). - References at write. A
_refnaming a secret this node doesn't store is 422secret_missing(new code, withset_by_file). A_refchanged to a secret that an entry of another kind references in the effective configuration is audited ascredential.redirectwithsecretUsedBy(note 15's deferred case); the alert names the field and the secret's name. - Rotation.
wrendns secrets rotate-keyrefuses while the data directory's lock is held (asbackup restoredoes), re-encrypts the rows readable under the old key (others are left as they were and counted), andrecover_rotationdecides a leftoversecrets.key.newby whether any row is under itskey_id. Re-encryption keeps each row's stamp and takes a new nonce. - Recovery gap (a decision for the owner). A store locked because none of its rows decrypt, and holding rows made on this node, can't be cleared: §3 refuses every secret write while locked (deletes included), and no command discards unreadable rows. The conservative reading is kept (nothing is ever discarded on its own);
docs/secrets.mdsays to keep a copy of the key. Proposed: an offlinewrendns secrets forget --unreadable, or letting T23.4'sDELETE /secrets/{name}remove an unreadable row while locked. - Helm's generated key is
ttsk1:+randAlphaNum 42+A: the last character keeps the trailing bits zero, as the decoder requires, for about 250 bits of entropy. The Secret keepshelm.sh/resource-policy: keep, and its file is mounted 0440 (group read throughfsGroup, which the key check doesn't warn about). - What isn't wiped.
SecretValue, the node keys and their subkeys are wiped on drop; copies handed to code that wants aString(the OIDC provider settings, the SMTP login) aren't, beyond §2's stated limit; the UniFi login body and the OPNsense key pair are. The metric iswrendns_secrets{state="readable|unreadable|corrupt"}; the store's own state is in health, not a gauge. - T23.3 is ticked with AC14–AC16 open, as T23.1 and T23.2 were: the Helm template test is written and in CI but wasn't run (no
helmin the dev container),cargo denywasn't run (nocargo-deny;Cargo.lockgains no package), and no image was built for the size delta.argon2is a direct dependency as the task lists, but nothing in the binary crate uses it until T23.9.
Review fixes (T23.3, 2026-11-16; Proposed, for the owner):
- Associated data,
status, and the key's edges. (a) §3's associated data had no boundary betweenkindandname: the row (text,x) gave the same bytes as (tex,tx), so someone who can writestate.dbwithout the key could move a ciphertext to another name and have it decrypt.kindandnameare now each preceded by their be16 length, andopentreats a kind other thantextorpemas corrupt. No value was stored under the old form (the write API is T23.4), so nothing needs migrating. (b)wrendns secrets statuswrites nothing: it doesn't finish or drop a leftoversecrets.key.new(arotate-keyrunning beside it would otherwise lose its new key, and every secret with it), doesn't re-encrypt, and creates no database; it reports the leftover file and counts rows under the previous key as readable. (c)rotate-keyalso refuses when the data directory's lock can't be taken at all (whether the server runs is then unknown). (d) Asecrets_previous_key_filethat no longer exists is a warning, not a locked store: the docs say to remove the previous key after rotating, and §3 locks only for sources 1 and 2. A previous key that exists but can't be read or parsed still locks (conservative). (e) The owner check (note 4's deferral): the process's uid is the owner of/proc/self(nolibc); a key owned by another user warns, root excepted (it can read the file anyway, and kubelet's Secret mounts are root's), a slightly less strict reading of §3. (f) The replica's self-heal clears rows only when a new key fixes the lock (secrets.keymissing, or none of the rows decrypts), not for a key file or database that can't be read. - Locks and blocking.
SecretStore::configuretook the settings' lock and then the store's, while a load holds the store's and then reads the settings: a reload that changed the key settings during a load hung both, and with them health, metrics and the API (CLU-004).configurenow takes only the settings' lock and marks the store stale; the next use loads again. A reload's missing-reference warning runs in a blocking task. Left as it is: an API request that finds the store due for a retry (thesecret_missingcheck, idempotency) loads it on that request's thread, at most once every 30 s while locked; health and metrics never load. - Smaller points.
wal_checkpoint(TRUNCATE)reports whether it finished; when another connection kept it busy past the 5 s timeout, the server logs a warning androtate-keyprints a note (ciphertext may stay instate.db-waluntil a later checkpoint). TheIdempotency-Key503 applies when the key itself can't be read; a key that opens none of the rows still keys the retry records, so a store locked that way doesn't refuse them (the docs say so; §4 is read that way).<redacted>is refused at load at every credential path (credentials::PATHS), URL passwords included, the error naming the field. A body that sendsnullor""for a credential key the files set is 409set_by_file, not carried over. The backup still drops thesecrets_stampcounter with the table (§8 keeps the store out of backups): a restored node starts its stamps again at (epoch, 1), which relies on T23.5's epochs and T23.9's re-stamping. The UniFi key and session cookie are wiped after a poll.backup restorestill goes on when the data directory's lock can't be taken (outside T23.3; worth the same refusal).
Implementation notes (T23.4, 2026-11-16; Proposed, for the owner):
- Status codes. A value, kind or name the rules refuse, and a 129th secret, are 400
invalid_parameter(T23.3'sStoreError::problem), not 422: nothing about the configuration is invalid. Three codes are new:insecure_transport(403),agent_not_allowed(403) andsecret_in_use(409). A primary without its lease and an emergency primary answer 409 as §4 says (entry writes answer 503 for a lapsed lease); dry runs are held to the same, and to the locked store (503). set_by_fileon a secret write. §4 lists it without saying when. Read conservatively: aPUTof the name the UI gives a credential (<kind>.<entry>.<field>, lowercased,header:asheader.) is refused when this node's files set that credential inline or by file, since the secret would never be used. Any other name is accepted. The check reads the files of the node that applies the write (the primary): a replica's own file-set credentials (auth.oidc,[cluster.git]are node-local) aren't seen when it forwards (review of T23.4; proposed: the forwarding replica checks its own files first, or T23.5's heartbeats carry them).- The webhook rule (16 characters) applies when a
webhook_secret_refin the configuration names the secret at write time; a reference made later to a shorter secret isn't checked (a load warning could; proposed with T23.12). Like note 43 it sees the primary's references only: a replica's node-localwebhook_secret_refisn't consulted for aPUT(peers' references are fetched for deletes only); the same proposal covers it. ?forceand references.forceonly goes past members whose references can't be read (offline, older, or not answering within 2 s); a known reference refuses even with it. A shared-configuration reference that a lagging member still holds counts too (conservative).- References across nodes are asked at delete time. Until heartbeats carry
secret_refs(T23.5), the primary asks each full member of its registry (!ephemeral && !witness) overapi.read(Read::SecretRefs); a node-local reference names its node. T23.5 switches this to the heartbeats' union. - Transport. "From loopback" is the connection's peer being a loopback address (
::ffff:127.0.0.1from a[::]listener too) with noX-Forwarded-For/Forwarded/X-Real-IPheader (a request a local proxy forwarded from afar isn't).X-Forwarded-Proto: httpscounts here only from a peer listed in[api] trusted_proxies; unlikeis_https, loopback isn't implied, since a plain-HTTP proxy or relay on the same host would pass a remote client's header through (review of T23.4). A TLS proxy on the same host is listed as127.0.0.1/32. Reads aren't held to it (they carry no value).[api] allow_secrets_over_httpis read from the node's files at each request (node-local, no restart). In-process MCP calls have no peer address, so they'd need HTTPS; there is no MCP write tool anyway. - The head as an ETag is
<epoch>.<seq>.<first 16 hex digits of the digest>, sent on reads and write answers;If-Matchtakes it (412version_conflict). The idempotency record of aPUTisPUT /secrets/<name> kind=<kind>and the keyed BLAKE3 of the trimmed value (the kind included, so another kind with the same key is 409); an emptyIdempotency-Keyis no key; aDELETE's is its request line (?forceincluded), which holds nothing secret. - Replicas and
GET. A replica shows the primary's list and head, with its own store, credential fields, node-local references and its own row per secret; without the primary (or with one too old to answer) its own view withstale: true.nodeslists only the nodes that answered until T23.5's heartbeats; replicas hold no rows yet, so a stored secret is the primary's only and integrations elsewhere report it not set. - Forwarding. The value crosses the cluster channel in the JSON body of
secret.put(mTLS); the replica serialises it into one buffer sized up front (so it isn't reallocated) and moves that buffer into the call; from there the channel's buffers, like the HTTP and JSON layers' copies on the way in andctl's request body, aren't wiped (§2's stated limit; only buffers WrenDNS keeps are). The primary takes it only from a full member of its registry, checks every rule again, reads its epoch under the role-change lock (Cluster::primary_epoch, new inwrendns-cluster: Primary with its lease) and stamps and stores the row after releasing it, so no SQLite write or fsync runs under the lock role changes take (a step-down in between leaves a row of the old epoch, which the new primary's epoch outranks: §2's orphans, the argumentpublish_asmakes), and audits<user> via <node>. An older primary answers "unknown call": 409upgrade_requirednaming its version. - Agents.
agent_not_allowedcoversPUT/DELETE/POSTon/api/v1/secrets*,POST /api/v1/backupandPOST /api/v1/checks/router*before any scope is looked at (the last two don't exist yet; the rule is in place for T23.7 and T23.9). Reading needsconfig:read; operators read too, viewers don't. - Mixed versions (T23.3's deferral): a write that adds a
*_refthe entry didn't have warns, naming the members older than 0.8.0. Only alert destinations take references through the API so far. - Not done here. Note 35's recovery gap stays: a locked store refuses
DELETEtoo. The image size delta (AC17) isn't measured (no image build here; one directzeroizeedge inwrendns-api, no new crate inCargo.lock).
Merge review fixes (M23, 2026-11-16; Proposed, for the owner):
- Amendment to §4: URL user names and secret query values (Proposed). §4 replaces a URL's password with the marker and keeps the rest of the URL. Read literally, that leaks a token used as the user name (
https://ghp_…@github.com/org/repo.git) and a list URL's token in its query (https://lists.example/ads.txt?token=…), which reachGET /lists, MCP reads,ctl, replica reads, Git audit rows and config entries. Proposed: a URL without a password has its user name replaced by the marker, and the values of query parameters namedtoken,key,apikey,api_key,access_token,auth,sig,signatureorpassword(names compared without case) are replaced too. A URL with a password keeps its user name as before. Round trips stay as §4 has them: a URL that sends the marker keeps its stored value while its destination is unchanged. The support package'sUrlclass already drops the path and query. - Idempotency record of
POST /lists/refresh. The record keeps the keyed fingerprint (idempotency_request) like the configuration writes, not the request text (§4). - Primary's
GET /listspasses through the same redaction as a replica's read (redact::lists), so a URL written or normalised differently from the configured one is covered too. - List fetches never send user information. A list URL with
user:pass@is refused as a fatal fetch error (the URL is not quoted);Hostcarries the host and port only. Basic auth isn't built, as no base64 dependency is wanted for it. - Open serialization (OPS-014).
State::openruns its setup under a process-wide lock and sets the busy timeout first;journal_mode=WALis retried on busy with a bounded backoff (50 × 20 ms), since SQLite doesn't always run the busy handler for it.
Requirements AGT-001 AGT-002 AGT-003 AGT-005 AGT-007 API-007 CLU-004 CLU-010 CLU-013 CLU-015 NFR-001 OBS-015 OPS-005 OPS-011 OPS-014
Builds on ADR-040 ADR-045 ADR-048 ADR-049 ADR-051 ADR-056 ADR-058 ADR-063 ADR-069 ADR-116 ADR-120 ADR-125 ADR-143 ADR-149 ADR-155 ADR-156
Referenced by ADR-1003 ADR-1005 ADR-1006 ADR-1007 ADR-1025 ADR-1027 ADR-1045 ADR-1048 ADR-1051 ADR-907 ADR-908 ADR-914 ADR-917 ADR-918 ADR-919 ADR-921 ADR-926 ADR-956 ADR-961 ADR-965 ADR-966 ADR-967 ADR-968 ADR-984 ADR-985 ADR-993 ADR-998 ADR-999
Link to this decision · In the specification
ADR-904 Pi-hole's special names: iCloud Private Relay blocked by default, resolver.arpa kept local with DDR, domain-needed opt-inDNS-019, spec/03 §3 step 4 (DDR promised at P1).
Context
DNS-019, spec/03 §3 step 4 (DDR promised at P1). Pi-hole users rely on three behaviours we lacked: Pi-hole answers iCloud Private Relay's names NXDOMAIN by default (Apple's documented opt-out for networks: devices then use the network's DNS, so filtering applies); it answers resolver.arpa locally (designatedResolver); and domain-needed keeps bare names off upstreams. RFC 9462 §6.5 says forwarders shouldn't forward resolver.arpa: an upstream's DDR answer names a resolver whose certificate can't cover our address.
Decision
- iCloud Private Relay:
[special] block_icloud_private_relay, default true (a behaviour change, for Pi-hole parity): exactlymask.icloud.comandmask-h2.icloud.com→ NXDOMAIN (with SOA), all types, before local data and filtering; statusspecial. A bool, likeblock_firefox_canary. - resolver.arpa: always local, no switch. With
[special] ddr_name(the host name in the listeners' certificate),_dns.resolver.arpaSVCB answers one record (RFC 9460/9461) per DoT, DoH, DoH3 and DoQ listener on this node, in listener order (priority 1, 2, …), TTL 300, AA:alpn(dot,h2,h3,doq), the listener'sport,ipv4hint/ipv6hintonly for a listener bound to a specific address, anddohpath= the listener path +{?dns}(default/dns-query{?dns}). Left out: listeners bound to loopback (no other device can reach them) and listeners withproxy_protocol = true(a direct connection fails without the PROXY v2 header); advertising nothing leaves a device on plain DNS, while advertising an unreachable resolver can leave it with none. The records are built with the policy, off the query path. Anything else inresolver.arpa→ NOERROR, no data, SOA.[special]is shared but listeners are node-local, so each node advertises its own. Clients check that the certificate covers the IP they use (an IP SAN); documented, not checked. - domain-needed:
[special] single_label_nxdomain, default false. One-label names asked for A, AAAA, or HTTPS (dnsmasq's A/AAAA, plus HTTPS because browsers send it for the same bare names) → NXDOMAIN at the routing step: after local records, zones, device names, quick rules, the filter and rewrites, unless a[[route]]matches (the same test as RFC 6303 private PTRs). Other types (DS, NS, SOA, DNSKEY of a TLD, which validators ask) still go upstream. - Classifier: one walk over the labels picks the top-level label; each rule compares only under its own TLD. No allocation (
02§3). - Importer: v6
dns.domainNeeded,dns.specialDomains.iCloudPrivateRelay,mozillaCanary; v5DNS_FQDN_REQUIRED,BLOCK_ICLOUD_PR,MOZILLA_CANARY(the last two on unless an explicitfalse, any case, trimmed). Written only where Pi-hole differs from our defaults.designatedResolver = falsehas no equivalent (never forwarded, per RFC 9462);bogusPrivstays an import note.
Alternatives rejected
a string enum icloud_private_relay = "block"|"allow"; NXDOMAIN for resolver.arpa (RFC 9462 and Pi-hole use NODATA); the DDR target from the certificate's SAN (needs X.509 parsing in the policy crate); domain-needed for every type (breaks DS/NS of TLDs under DNSSEC); forwarding resolver.arpa when no ddr_name is set.
Consequences
Apple devices with Private Relay on show "Private Relay is turned off for this network" until an admin flips the switch. Windows 11, iOS 16+ and macOS 13+ discover encrypted DNS by themselves once ddr_name and an IP-SAN certificate are in place. Behind port mappings the advertised ports are the listeners' own (a per-node ddr_port is a possible follow-up), and a load balancer that adds PROXY headers gets no DDR (a possible opt-in later).
Requirements DNS-019
Referenced by ADR-914
Link to this decision · In the specification
ADR-905 Update lists now: one queued round per request, on the node that downloads listsspec/07 §2 promises POST /lists/refresh, but only SIGUSR1 refreshed lists, and on a cluster replica nothing could (replicas don't download lists, CLU-003) while its Lists page showed every list as "pending".
Context
spec/07 §2 promises POST /lists/refresh, but only SIGUSR1 refreshed lists, and on a cluster replica nothing could (replicas don't download lists, CLU-003) while its Lists page showed every list as "pending". Pi-hole users expect "Update Gravity".
Decision
POST /api/v1/lists/refresh(body{},null, or{"names": [...]};?dryRun=true;Idempotency-Key) queues the enabled lists named, or every enabled list, on the node that downloads lists, and answers 202 withqueued,skipped(disabled),alreadyRefreshing,nodeandnote. An unknown name is 404 with the real names in the hint. A node that doesn't download lists (roleresolver, or no fetcher) answers 409lists_not_here. A dry run queues nothing and isn't audited (AGT-002); a key replays the first answer for 24 h and a reused key with another body is 409 (AGT-003). Audited aslists.refresh.- Rounds: requests made before a round starts merge into it; a request made while lists download starts exactly one more round after it. Progress is per list, not a job:
refreshing(queued or downloading) andlastSuccessUnixSecondsonGET /lists. No new change marker:lists.refreshedalready marks a refresh that changed the snapshot (OBS-033). - Scope: people need the operator role; agents reuse
config:write:listsplus the reason header (saving a list already makes it download, so this grants nothing new). Group-restricted agent tokens are refused. - Cluster: the primary downloads (CLU-003). A replica forwards
Write::ListsRefresh(by,names,dry_run,reason), and the primary audits it with actor"<user> via <entry site>", kindcluster, and the user's reason. An N−1 primary refuses the unknown write and the replica answers 503. Without a reachable primary, a node with its own fetcher uses it, otherwise 503; an emergency primary that followed a primary has no fetcher and answers 503 (list refresh paused,spec/12§5). A replica'sGET /listsshows the primary's lists and download state (Read::Lists) with every node's hits added up (Read::ListHits, OBS-009); when the primary doesn't answer,missingNodesnames it and the replica shows its own view.ctl lists refresh --waitstops only when the primary is amongmissingNodes: a replica that misses only its hits doesn't stop it. The primary is named asmissingNodesnames it (its pod, else its site, else its node ID;ctlalso matches its site and node ID, so an empty site is never a blank name).missingNodesalso names nodes whose hits are missing (OBS-009). In a mixed-version window an N−1 primary that answersRead::Listsbut notRead::ListHitsis inmissingNodestoo, so it stops--wait. This is deliberate:missingNodesdoesn't say which read was missed, and the primary's own hits are missing, so the conservative stop is kept (the download state there was read, which is why the Lists page words its notice as "not confirmed from the primary" rather than "this node's own"). - Surfaces: the Lists page Update now (operators; progress, failures named, "last confirmed current" from the oldest enabled list);
wrendns ctl lists refresh [names] [--dry-run] [--wait] [--reason], where--waitexits non-zero after 5 minutes or when the primary is unread; MCPrefresh_lists, an immediate audited op with no plan (spec/13§3.2), likeflush_cache: it changes no configuration and costs one conditional request per unchanged list.
Consequences
SIGUSR1 still refreshes only the node that gets it. The fetcher's new lock is taken only when a download starts or ends, on a refresh request, and on a lists read; the query path is unchanged.
Requirements AGT-002 AGT-003 CLU-003 OBS-009 OBS-033
Referenced by ADR-937
Link to this decision · In the specification
ADR-906 Fork ADR numbers: fork-only ADRs take the next free number from 901 upThis fork (nbacheller/wrendns) and upstream (paimonsoror/telltaledns) both record decisions as ADRs.
Context
This fork (nbacheller/wrendns) and upstream (paimonsoror/telltaledns) both record decisions as ADRs. Upstream's numbering ended at ADR-164, so the fork's first five decisions after it (numbers 165 to 169) sat where upstream's next decisions would go, and one number could mean two decisions once a sync brought them together.
Decision
- Fork-only ADRs take the next free number at or above 901, in order, and a number is never reused.
- Upstream's ADR numbers are kept as they are; the fork does not renumber them.
- On each upstream sync, check upstream's new ADR and requirement IDs against this file. If one of them lands on a fork ADR number, renumber the fork ADR (901 and up), never upstream's.
Consequences
On 2026-11-16 the fork's numbers 165 to 169 became 901 to 905, and every reference in code, spec, docs, site, UI, and bench was updated to match. Upstream's numbers stay below 901, so the two ranges do not meet.
Builds on ADR-164
Referenced by ADR-907
Link to this decision · In the specification
ADR-907 Network inventory scope: SNMP, gateway reads and imported scans; no built-in probingOn 2026-11-16 the owner asked what WrenDNS can learn about devices that never use DNS or DHCP.
Context
On 2026-11-16 the owner asked what WrenDNS can learn about devices that never use DNS or DHCP. Some sources already exist:
- the routers' leases and networks (ADR-080, ADR-902);
- Home Assistant names by MAC (ADR-902);
- passive mDNS (ADR-081);
- the kernel neighbour table. Today it is used only for MAC client matching (
wrendns_net::neighbors()).
These are missing:
- the gateway's ARP table across VLANs;
- which switch port each MAC is on;
- the identity of printers and network gear;
- devices with static addresses that UniFi doesn't list.
Active probing is out of scope by owner decision (2026-11-16). That covers ICMP sweeps, TCP connect probes and ARP/mDNS solicitation. An operator's own scanner supplies that data, and WrenDNS imports its output.
This ADR keeps the read-only router posture of ADR-080 and ADR-902. ADR-091 (no DHCP server) is a separate decision and is not affected. ADR-081 is not affected either: mDNS stays passive. M22 ("Network inventory and home integrations") was the first inventory milestone, and M25 builds on it.
Decision
- What M25 adds. Four inputs, all read-only:
- An SNMP poller (ADR-908) of infrastructure listed in the configuration. It reads:
- gateway and router ARP tables;
- IF-MIB;
- the switches' BRIDGE/Q-BRIDGE forwarding tables per VLAN;
- LLDP neighbours.
- An SNMP poller (ADR-908) of infrastructure listed in the configuration. It reads:
It also reads the identity of hosts already in the inventory (sysName, sysDescr, sysObjectID, Printer MIB), using per-subnet credentials. The public community is never tried unless the owner opts in for that subnet (ADR-909).
- More read-only UniFi and Home Assistant API reads (ADR-912).
- Uploaded results of a scan the owner runs: nmap XML, or a simple
ip,mac,hostnameCSV (ADR-913). - A merged inventory keyed by MAC across all sources (ADR-910).
- What WrenDNS never does. It never generates discovery traffic of its own:
- no ICMP;
- no TCP connect probes;
- no ARP, NDP or mDNS solicitation;
- no SSDP, NBNS or WS-Discovery;
- no scheduling or launching of scans.
The code has no target planner and no range iterator.
- Where SNMP goes. SNMP requests go to only two kinds of address:
- each
[[discovery.snmp_agent]].address; - addresses that have a current binding from class 1–3 and lie inside a configured
[[discovery.subnet]]CIDR. Class 1–3 means router leases or UniFi current clients, the filtered local neighbour table, or SNMP ARP from a listed agent (ADR-910).
- each
Entries known only from imports, from the IP-only class or from UniFi stat/alluser history are never SNMP destinations. An address range is never walked. A subnet CIDR is a filter on inventory addresses, never a list of targets.
- Destinations. Every SNMP destination is an IPv4 literal inside RFC 1918. Host names are refused, so there is no resolution and no rebinding. Always refused:
- loopback,
0.0.0.0/8and169.254.0.0/16; - multicast, limited broadcast and subnet broadcast;
100.64.0.0/10(RFC 6598, which Tailscale uses);- every IPv6 address (M25 is IPv4 only, like the leases);
- the host's own addresses;
- anything outside RFC 1918.
- loopback,
- Placement.
[discovery]is a shared section with one designated node:node = "<node-id>". If unset, the current primary, or the standalone node.- Never ephemeral resolver pods or witnesses.
- Every other node reads the inventory through a federated
Read::Discovery(ADR-910).
- Isolation (CLU-004).
- Two worker processes re-executed from the running binary (ADR-908, ADR-913):
wrendns discovery-workerhandles SNMP I/O and the BER/USM codec;wrendns discovery-worker --importis a short-lived, credential-free process for import parsing.
- A worker panic, hang, allocation failure or OOM cannot abort the DNS process, which builds with
panic = "abort". - The merge runs in the main process on one dedicated OS thread named
wrendns-inventory. It callswrendns_net::background_thread()and runs its ownnew_current_thread()runtime, likekubernetes.rs. The extra UniFi and Home Assistant reads also run there (ADR-912). - Nothing in discovery is
tokio::spawned on the main runtime. - Results leave the thread only through
ArcSwapstores. - The thread and the workers are not created while
enabled = false, or on a node that isn't the designated one. Reload starts or stops them.
- Two worker processes re-executed from the running binary (ADR-908, ADR-913):
- What remains in the main process. The merge thread and the worker frame decoder still run in the main process, so a panic there aborts DNS. The only mitigations are:
- the ADR-908 module lints (
indexing_slicing,arithmetic_side_effects,panic,unreachable); - the
inventory_mergeandworker_framesfuzz targets.
- the ADR-908 module lints (
- Writes and audit.
- The section is edited through the config entries API as a managed kind,
discovery: admin only, with dry run,If-Match, audit and secrets redacted. - No agent scope writes the
discoverykind. Agents get 403. - A setting made in a file shows as "set by file" and can't be edited through the API.
- At startup and on reload, a change to the effective
[discovery]hash is audited asdiscovery.config_changed (source=file). - These are audited too: scan imports, deleting an import, SNMP tests, finding mutes, and the
publicpasses and circuit-breaker trips. - Humans need the operator role for imports, deleting imports and mutes. Agents need
ops:discovery, which is an Operator-role scope. snmp/testis admin only for humans. Agents needops:discovery_test, an Admin-role scope.- Discovery never writes router or gateway configuration, never sends an SNMP SET, and never blocks or moves a device. Quarantine stays an explicit action (
06§7).
- The section is edited through the config entries API as a managed kind,
- N−1 (CLU-010).
[discovery]and[local] device_inventory_addressesare serialized only when set, like ADR-903's_reffields.- An N−1 replica refuses a version that holds them.
- The API refuses the first write of
[discovery]with 409members_too_oldwhile any full member runs N−1. config checkwarns when the file sets the section in a mixed-version cluster.
Alternatives rejected
- Built-in ICMP/TCP/ARP/mDNS probing: out of scope by owner decision. It also brings IDS self-blocking of the DNS host, neighbour-table overflow and conntrack pressure.
[discovery]as node-local configuration: there would be no audited write path. ADR-161 rejected the same thing for mutes.- SNMP on every node: each node has a different view of the network, and the traffic and IDS exposure would double.
- Host names as SNMP addresses: anyone who can change DNS records could redirect a credential.
- Identity reads to any inventory address: one CSV import could turn the reads into a sweep of a whole /16.
Consequences
- WrenDNS now sends SNMP read requests on the LAN. They go to listed devices, and, with an identity credential, to hosts that a router, the neighbour table or a gateway ARP table currently sees.
- Devices that no source sees stay unknown until the owner imports a scan. Imported devices get no identity reads until a class 1–3 source binds their address.
- Amends ADR-080 and ADR-902: "read-only toward the gateway" now also covers SNMP reads. Nothing writes.
- Proposed amendment of ADR-906: the upstream-sync collision check also covers requirement prefixes (DSC) and milestone numbers (M25).
- ADR-081, ADR-091, ADR-117 and ADR-161 are unchanged.
Owner decisions (2026-11-16): the owner accepted the recommendations for questions 1–12 and 14–16 of the M25 design, and answered question 13 by a test. These ADRs (ADR-907 to ADR-913) stay Proposed until the owner accepts the ADRs themselves.
- Accepted recommendations:
- 1a: SNMP credentials as
*_filefirst, once T23.1–T23.3 are in;*_refin T25.8. - 2a: The
aes0.8 crate with hand-written CFB-128 for v3 privacy (ADR-911). - 3a: A hand-written restricted nmap XML parser (ADR-913).
- 4a: Imports kept on the scanning (designated) node; replication is a follow-up.
- 5c: Retention configurable, defaults 7 days (SNMP, neighbour and history-only entries) and 30 days (imports).
- 6a: Inventory addresses in DNS opt-in, off by default (DSC-012).
- 7a:
publicis a validation error withoutpublic_ids_acknowledgedand a gateway agent or UniFi router (ADR-909). - 8a: The primary is the designated node when
nodeis unset. - 9a: 30 days of
stat/alluserhistory. - 10a: Home Assistant devices without entities go in the inventory only.
- 11a: Open ports and OS guesses from imports kept, capped at 16 ports, behind
discovery:read. - 12a: No MD5 or DES.
- 14a: Imported addresses never get identity reads; only class 1–3 bindings are SNMP destinations.
- 15a: No discovery at privacy level 2 or above.
- 16a: Split agent scopes:
ops:discovery(Operator) andops:discovery_test(Admin).
- 1a: SNMP credentials as
- Question 13, answered by a test:
- A UniFi gateway serves
ipNetToPhysicalTableover SNMPv3 with SHA and AES, with IPv4 and IPv6 entries, most of them with a MAC;ipNetToMediaTablehas the IPv4 ones. T25.6 stays as written for ARP (option a). M25 is IPv4 only, so the IPv6 rows are counted and ignored; they are a possible source for T24.8 (IPv6 device names) later. - The gateway has no BRIDGE, Q-BRIDGE or LLDP MIB. On networks whose switches and APs are not UniFi, port mapping therefore needs SNMP agents on the switches themselves; the UniFi API (ADR-912's
devicesread) can't supply it there. T25.6 says so. - A gateway that still answers v1/v2c
publicis a finding: the SNMP setup docs flag it to turn off once v3 works. - A network printer that answers v2c
publicwith the Printer MIB is the case the ADR-909 opt-in is for.
- A UniFi gateway serves
Requirements CLU-004 CLU-010 DSC-012
Builds on ADR-080 ADR-081 ADR-091 ADR-117 ADR-161 ADR-902 ADR-903 ADR-906 ADR-908 ADR-909 ADR-910 ADR-911 ADR-912 ADR-913
Referenced by ADR-1002 ADR-1004 ADR-1007 ADR-908 ADR-909 ADR-910 ADR-913 ADR-923 ADR-928 ADR-930 ADR-969
Link to this decision · In the specification
ADR-908 SNMP poller: v2c and v3 USM, read-only, in a worker processOn a typical home network, the most valuable SNMP data is the gateway's ARP table: ipNetToPhysicalTable (1.3.6.1.2.1.4.35), falling back to ipNetToMediaTable (1.3.6.1.2.1.4.22).
Context
On a typical home network, the most valuable SNMP data is the gateway's ARP table: ipNetToPhysicalTable (1.3.6.1.2.1.4.35), falling back to ipNetToMediaTable (1.3.6.1.2.1.4.22). It gives a MAC for every address on every VLAN. Next in value:
- managed switches' forwarding tables per VLAN, mapped to ports;
- LLDP neighbours;
- the identity of printers and network gear.
The repo has no SNMP code. Constraints:
- The release build aborts on panic.
ringcovers HMAC-SHA-1/SHA-2 and the digests, but has no raw AES block.- Many UniFi devices run Net-SNMP, and UniFi uses one v3 password for both auth and priv.
- Whether a UniFi gateway serves its ARP table over SNMP was unconfirmed when this was written. A test confirmed it does, over v3 with SHA and AES (ADR-907, owner decisions).
- On systemd, the unit's default
OOMPolicy=stopstops the whole unit when the kernel OOM-kills any process in it. - On Kubernetes with cgroup v2, kubelet 1.28 and later sets
memory.oom.group=1, so an OOM kills every process in the container.
Decision
- Crate. A new crate,
wrendns-snmp.- Lints:
#![forbid(unsafe_code)]and#![deny(clippy::indexing_slicing, clippy::arithmetic_side_effects, clippy::panic, clippy::unreachable)]. - A hand-written minimal BER codec. Definite lengths only, a depth cap of 8, a message cap of 64 KiB and a cap of 256 varbinds per PDU.
- Types: INTEGER, OCTET STRING, OID, NULL, IpAddress, Counter32, Gauge32, TimeTicks and Counter64, plus the noSuchObject, noSuchInstance and endOfMibView exceptions.
- It is off the hot path and not on the AGENTS.md bench-smoke list.
- Lints:
- PDUs. It sends GET, GETNEXT and GETBULK, and receives Response and Report. The encoder has no SetRequest type, and no other write PDU type or tag constant. A CI grep test checks this.
- v3 USM (RFC 3414, RFC 7860, RFC 3826).
- Engine discovery uses Report messages. Replies must match
msgIDandrequestID. At most one unauthenticated time resync per agent per minute. Superseded in part by the 2026-11-17 amendment below and ADR-931 (Proposed): only an authenticated Report moves the clock. - Amended 2026-11-17 (m25-snmp review): unauthenticated Reports are never used for the clock. Discovery accepts only a noAuthNoPriv Report whose varbind is
usmStatsUnknownEngineIDs. An authenticated notInTimeWindow Report takes the agent's clock, at most once per agent per minute, and the request is sent once more. Message and request IDs start at a random value on separate counters, so a spoofed datagram cannot guess them. A v3 reply must match the request's security level, engine ID and user. The cached engine is dropped after a failed exchange, so a forged engine ID cannot stay in place. The MAC is compared in constant time, and the community is compared the same way. Credential files (2026-11-17, m25-snmp review): the file is opened no-follow and non-blocking, and its identity is checked against the canonical path (ADR-932, Proposed). An authPriv request accepts an authNoPriv time-window Report with request ID 0 or the request's ID, when its MAC verifies (ADR-931, Proposed). - Key handling (amended 2026-11-17): Ku and Kul are held in
Zeroizing, and the privacy key is zeroized, withaesbuilt with itszeroizefeature.ring's digest and HMAC contexts keep password-derived state that cannot be zeroized; this is accepted, because they are dropped at the end of the round and never cached. The privacy salt is eight random octets per message (64 bits fromSystemRandom), not RFC 3826's seeded counter: no counter state is kept across restarts, and the repeat chance under one key is negligible. - Ku is the 1 MiB password-to-key expansion. It is computed once per credential per poll round with
ring::digest, held in aZeroizingbuffer, and dropped at the end of the round. - Kul, the key localised per engine, is one short hash. It is computed on demand and never cached.
- Authentication: HMAC-SHA-96, and HMAC-SHA-256/384/512 truncated per RFC 7860 (
ring::hmac). - Privacy: AES-128-CFB (ADR-911).
- Security levels: authNoPriv and authPriv.
priv_password_*defaults to the auth password. - Refused at config time, with a reason: MD5, SHA-224, DES, AES-192/256, and v3 noAuthNoPriv.
- Engine discovery uses Report messages. Replies must match
- Worker process. The designated node runs the poller in
wrendns discovery-worker.- Binary. The worker is started from
/proc/self/exe, the inode that is actually running, notcurrent_exe(). The image doesn't grow, and an upgraded file on disk is never started by mistake. - Version handshake. The first frame is a handshake: build ID plus protocol version. On a mismatch the worker is refused and the health reason
discovery_worker_version_mismatchis raised. - Environment. Cleared with
env_clear(). No arguments carry secrets. Jobs and credentials arrive on stdin only. - Frames. Each frame is a u32 big-endian length, a type byte, then the payload:
- JSON control and result frames, at most 1 MiB, with large results split across frames;
- binary chunk frames, at most 512 KiB.
- Binary. The worker is started from
The main side reads frames on the wrendns-inventory thread with a bounded, panic-free reader.
- Stderr. Captured and logged with a rate limit, never inherited.
- Memory limit. At start the worker sets
RLIMIT_DATAtoworker_memory_mib(default 64, range 32–128). An allocation failure then aborts only the worker, well below the cgroup limit.RLIMIT_ASis not used, because reserved virtual mappings would trip it. - Other hardening at start.
oom_score_adjis set to 1000.PR_SET_DUMPABLE=0andRLIMIT_CORE=0are set, so an abort never writes a core dump that holds Ku or passwords.- All of these go through one safe wrapper in
wrendns-net, with a// SAFETY:comment (AGENTS rule 7).
- Runtime. It calls
background_thread()and runs one current-thread runtime. - Sockets. It holds no listening sockets, only connected UDP client sockets. It exits on stdin EOF.
- Supervisor. Restarts the worker with backoff: 1 s, doubling up to 5 min. Three crashes within 10 minutes raise
discovery_worker_failing(degraded, never DNS). While the worker is down, results go stale and DNS is unaffected. - systemd.
deploy/systemd/wrendns.servicesetsOOMPolicy=continue, so a kernel OOM kill of the worker never stops the unit.
- Infrastructure polling (
[[discovery.snmp_agent]]).- Interval. Each agent is polled every
interval_secs(default 300, minimum 60). - Pacing.
- One request in flight per agent.
- At least 50 ms between requests and at most 20 requests/s per agent.
- Timeout 1.5 s, with 2 retries.
- A walk stops after 3 timeouts in a row or 30 s of wall clock.
- Sizes. GETBULK
max_repetitionsis 5–25 (default 10). Each table is capped at 5,000 rows. One 64 KiB receive buffer per agent is reused. - Replies. A reply counts only if it comes from the address the request went to.
- Tables.
arp: ipNetToPhysicalTable, else ipNetToMediaTable.ifmib: ifTable and ifXTable names, plusipAddressTable/ipAddrTablefor the agent's own addresses.bridge:dot1qTpFdbTable, elsedot1dTpFdbTable, with ports mapped throughdot1dBasePortIfIndex.dot1qTpFdbTableis indexed bydot1qFdbId, which is not the VLAN ID. It is mapped to the VLAN ID throughdot1qVlanCurrentTable'sdot1qVlanFdbId.- A port counts as an uplink or trunk, and its MACs give no location, if it has more than 8 learned MACs, or an LLDP neighbour that is itself a listed agent or a UniFi device.
- Per-VLAN contexts (
community@vlan, v3contextName) are left Open.
lldp: the LLDP-MIB remote table (1.0.8802.1.1.2), at most 4 neighbours per port.
- Interval. Each agent is polled every
- Capability record.
- On the first poll and on
snmp/test, each listed table root gets one GETNEXT. - The record is kept and shown: tables answered, security level reached, engine ID, sysObjectID.
- Capabilities are never assumed. A table that doesn't answer is skipped until the next test, and the skip is logged once.
- On the first poll and on
- Host identity reads.
- Who. An address inside a
[[discovery.subnet]]that names ahost_credential, and that has a current class 1–3 binding (ADR-907). - What. One GET of sysName, sysDescr, sysObjectID and sysLocation. If sysObjectID or the device class says printer, also a GET of
prtGeneralPrinterName. No walks. - How often. At most once per host per
identity_interval_hours(default 24, minimum 6). At most 5 hosts/s in total and 1,024 hosts per pass. - Replies. An answer from any address other than the one asked is dropped.
- Who. An address inside a
- Credential roles.
[[discovery.snmp_credential]]hasrole = "infrastructure" | "host".- It is a validation error for a subnet to name an infrastructure credential, or for an agent to name a host credential. A device on the LAN therefore never receives the gateway's credential.
- A v2c host credential warns: every host in the subnet learns the community in cleartext.
- Untrusted strings. Every string from a device:
- is cut: sysName and sysLocation to 64 B, sysDescr and the printer name to 255 B;
- has control characters removed (the
SafeString::newrule); - is rendered as text only.
MCP tool descriptions mark these fields as device-supplied data, not instructions.
- Credentials (ADR-903).
community,auth_passwordandpriv_passwordeach take either*_fileor*_ref. Inline values are a validation error. Files win, as in ADR-903.- Refs are named
discovery.<credential-name>.<field>, for examplediscovery.infra-v3.auth_password. - A missing ref on an API write answers 422
secret_missing. At load time a missing ref warns, and the agent or subnet is skipped. - They are write-only, added to
credentials::PATHSandAPI_PATHS, held asSecretValue(redactingDebug, zeroized), never asSafeString, and sent to the worker only over stdin.
- Diagnostic CLI.
wrendns snmp walk --agent <name> [--table arp|ifmib|bridge|lldp]. It takes a configured agent name only, never an address, and prints rows with secrets redacted.
Alternatives rejected
- An SNMP crate such as
snmp2orcsnmp: new dependencies with incomplete USM, and their panic behaviour isn't ours to control. - The codec in
wrendns-proto: that is a hot-path crate. - Polling in the main process, relying only on lints and fuzzing: one missed panic aborts DNS.
- Relying on
oom_score_adjalone: systemd'sOOMPolicy=stopand Kubernetes'memory.oom.groupkill DNS with the worker. current_exe(): after an upgrade it can start a newer binary than the one running.- Caching Kul per engine: the cache grows with every v3 host.
- MD5 and DES: weak, and
ringhas no MD5. - An address-based
snmp/test: it would be a destination chosen at request time.
Consequences
- About 3–6 MiB more RSS while discovery is on. The worker is capped by
worker_memory_mib. - Sending v3 to a host exposes the password to offline guessing by that host: it chooses the engine ID and receives an HMAC over a known message. This is why credentials have roles. The docs say to give hosts a low-value, shared identity.
- v2c host credentials are cleartext on the subnet.
- When a switch shows a MAC on several ports at once (a loop, or a move in progress), the most recently seen port is recorded.
- On Kubernetes outside the host network, the SNMP source address is the node IP after SNAT. Device access lists must allow that address.
Builds on ADR-903 ADR-907 ADR-911 ADR-931 ADR-932
Referenced by ADR-1001 ADR-1002 ADR-907 ADR-910 ADR-913 ADR-929 ADR-931 ADR-933 ADR-934 ADR-969 ADR-980 ADR-988
Link to this decision · In the specification
ADR-909 The public community for identity reads, by explicit per-subnet opt-inMany printers and cheap devices answer v2c public.
Context
Many printers and cheap devices answer v2c public. The owner approved trying it on 2026-11-16, with four conditions: an explicit per-subnet opt-in, off by default, audited, and with the IDS risk written down.
An IDS reads this traffic as credential guessing. Snort 1:1411 "SNMP public access udp" and the ET SNMP rules fire on it. UniFi IPS with "Block Source IP" could block the DNS host itself, and the whole LAN would lose DNS.
Decision
- The switch.
[[discovery.subnet]] snmp_try_publicdefaults tofalse.- Setting it to
trueis a validation error unless both of these hold:- the same subnet sets
public_ids_acknowledged = true, which confirms the DNS host is on the gateway's IPS allow list (UniFi: Security → Detection allow list); - the gateway is covered by a listed
snmp_agent, or by a UniFi[[router]]that the designated node polls. The circuit breaker needs one of them.
- the same subnet sets
- Both fields are set through the admin-only
discoverykind and audited. A setting made in a file shows as set by file and is covered by the startup audit (ADR-907).
- Which hosts.
- Only addresses inside that subnet that have a current class 1–3 binding (ADR-907).
- Only when the subnet has no
host_credential, or that credential has just failed for this host. - Never infrastructure agents, which need a configured credential.
- What is sent. One v2c GET of sysName, sysDescr, sysObjectID and sysLocation, with community
public. The code has no other built-in community string. No walks, no SET. - Limits.
- At most 1 host per second, and at most 1 retry.
- One attempt per host per 7 days, and failed attempts count. The key is the MAC when known, otherwise the IP, so an address change doesn't reset it.
- The limit survives restarts in the inventory file. That file is written at most once a minute after a pass.
- Empty start. When the inventory starts empty (a failover, or the file is missing), no
publicpass runs for 7 days. - Circuit breaker. All
publicattempts stop for 24 h, and the stop is audited, if during a pass either of these happens:- three
sysUpTimeGETs in a row to the listed gateway agent go unanswered (they are sent every 10 s during the pass), or the UniFi poll fails; - the health reason
upstream_downorupstream_group_downappears.
- three
The breaker never uses ICMP or TCP.
- Audit and visibility.
- Each pass writes one audit summary: subnet, hosts tried, hosts that answered.
- While any subnet has the switch on:
config checkwarns;- the UI shows a banner;
GET /discoverysays so.
- Answers are tagged
identitySource = "snmp-default-community". - A host that answers gets the
default_communityfinding (ADR-910).
Alternatives rejected
- A list of common communities: that is guessing.
- On by default: IDS self-blocking.
- Trying it on infrastructure agents: the owner configures those.
- A warning instead of the acknowledgement error: the failure takes DNS down for the LAN.
- A breaker based on reachability probes: that would be active probing (ADR-907).
Consequences
- Printers and similar devices on an opted-in subnet are identified without per-device setup.
- The gateway's IDS logs may still show the attempts. The docs carry:
- the risk text;
- how to allow-list the host;
- a note that a device answering
publicis itself a security finding.
Link to this decision · In the specification
ADR-910 Inventory merge model: keyed by MAC, address bindings with a time limit, never DNS policySources disagree, and each has its own trust: Constraints:
Context
Sources disagree, and each has its own trust:
- UniFi current clients and reservations;
- OPNsense leases;
- Home Assistant names by MAC;
- the local neighbour table;
- SNMP ARP and bridge tables;
- SNMP identity;
- imported scans, which are claims from a file;
- passive mDNS.
Constraints:
devices::Namesis IPv4-keyed, and every peer pulls it every 60 s. A full inventory there would exceedMAX_RPCand silently break router-name sharing.wrendns_policy::Neighborsdecides MAC-based client matching.- ADR-117 bounds
identify.rsto 1,024 devices for 1 day. - ADR-102 sets what is kept and shown at each privacy level. At level 2, nothing that identifies a client is kept.
Decision
- Model.
- The MAC is the key. An entry has:
mac;- up to 4 addresses, each with its source and
lastSeen; - display names, each with source and rank;
- the OUI vendor;
- VLAN and network;
- switch port and AP (from UniFi or the SNMP bridge table);
- LLDP neighbours (up to 4);
- an identity record: sysName, sysDescr, a vendor index into the PEN preset, and the printer name;
- up to 16 open TCP ports, from imports;
- a source bitmask;
- an import-ID bitmask (16 bits, one per kept import);
firstSeenandlastSeen;- findings and mutes.
- A result with no MAC goes into a separate IP-only class, keyed
ip:<addr>. Examples: an import from a routed scanner, or an identity answer before any MAC is known.- Capped at 1,024 entries, oldest dropped first.
- A MAC is never invented.
- When a MAC source binds the address, the entry merges into the MAC entry.
- Caps:
- 4,096 MAC entries;
- at most 8,192 import-derived rows in total, with the oldest import dropped first;
- per-entry caps as in ADR-908.
- The MAC is the key. An entry has:
About 600 B per entry at worst.
- Which address is current. Precedence for a MAC's current address:
- UniFi
stat/sta, OPNsense leases and UniFi reservations (ADR-902 rules). - The local neighbour table, in states REACHABLE, STALE, DELAY or PROBE. A row is accepted only if the address lies in a configured subnet and
Neighbor.ifindexis not a container or overlay interface:lo,docker*,br-*,veth*,cni*,flannel*,cali*,vxlan*,tun*,tap*,wg*,tailscale*,zt*. - SNMP ARP from listed infrastructure agents.
- Imports.
- UniFi
stat/alluserlast_ip. This is history only, never current.
- UniFi
Rules:
- The most recent binding from the best class is primary. The others are kept as aliases and shown.
- Same address, different MAC: the newest observation from classes 1–3 wins. An import or history never replaces a class 1–3 binding. The case is flagged
ip_conflict. - A MAC with the locally administered bit set is flagged
randomized. No stable-identity finding is raised for it. - Only class 1–3 bindings make an address an SNMP destination (ADR-907).
- Display names (inventory only), in rank order:
- the configured client name;
- Home Assistant
name_by_user; - the router alias or host name, in
[[router]]order; - a Home Assistant integration's name;
- passive mDNS;
- SNMP sysName or printer name;
- an import's host name.
Ranks 6 and 7 are labelled with their source.
- Containment.
- Inventory data never enters any of these:
router_leases,peer_names.routers,mdns_names,wrendns_policy::Neighbors, client matching, oridentify.rs's seen chain. This covers SNMP, imports,stat/alluser,stat/device, entityless Home Assistant devices and the neighbour-table source. - Device DNS names (ADR-901) are never created from it. The one exception is the opt-in below, which supplies an address and never a name.
- Feeding policy would need its own ADR, because ARP spoofing lands in the gateway's table.
- Passive mDNS naming under ADR-901 is unchanged.
- Inventory data never enters any of these:
- Device addresses in DNS (opt-in). With
[local] device_inventory_addresses = true(default false), a MAC can get an address from the inventory. This applies when the MAC already has a name in DNS-023's sources but no address there. The address comes from class 2 or class 3 only, and only if it was:- seen in the last poll;
- not flagged
ip_conflict; - not flagged
randomized.
These bindings, {mac, ip, name} with at most 1,024 rows, reach other nodes in a new Names.inventory field. The field is #[serde(default)], so it is N−1 safe, and it amends ADR-125. The bindings rank below every existing source in the device_dns order, which amends ADR-901's source order.
- Findings. Findings live on the entry, not in
AnomalyKind, so ADR-161 is unchanged.
When the inventory starts empty (a failover, or the file is missing), no new_device alerts are raised for 24 h. A mute applies to one entry and one kind, with an optional expiry, and is kept in the inventory file. Nothing blocks or moves a device.
- Retention.
- Entries seen only by SNMP, the neighbour table or history age out
retention_daysafterlastSeen(default 7). - Import rows age out
[discovery.import] retention_daysafter their import (default 30). - An entry that another source still sees is never removed.
- A host counts as absent only after two polls in a row miss it.
- Entries seen only by SNMP, the neighbour table or history age out
- Storage.
- Held in
ArcSwapon the designated node. - Persisted to
<data_dir>/inventory.json: mode 0600, atomic rename. Written at most every 15 min and on shutdown. After apublicpass or an import, at most once a minute. - Left out of backups.
- Left out of support packages unless asked for with
--include-inventory, which goes through ADR-156's pseudonymisation. - Not replicated as configuration.
- Held in
- Cluster read.
Read::Discovery, federated, with AGT-011missingNodes:- A non-designated node asks the designated node for a filtered page of at most 500 rows.
- Each answer is capped at 256 KiB (
MAX_RPC/4). The server enforces the cap by trimming the page. - An N−1 node answers "unknown call" and is listed in
missingNodes.
- Privacy (ADR-102).
- At level 1, sysName and host names are hashed like client names.
- At level 2 and above,
[discovery] enabled = trueis a validation error, because nothing that identifies a client may be kept. The other route, a Proposed amendment of ADR-102, is an owner question.
Alternatives rejected
- Extending
Nameswith the full inventory: it exceeds the RPC frame and spreads open ports to resolver pods. - An IP-keyed inventory: it loses devices that move addresses.
- Feeding
Neighbors: ARP spoofing would move devices between groups. - New
AnomalyKindvariants: they clash with ADR-161's mute model, OBS-014 IDs and N−1 deserialisation. - Feeding identify's seen chain: it breaks ADR-117's bounds.
- Storing every import row separately: up to 65,536 rows outside the caps.
Consequences
- Clients → Discovered and the Networks counts see devices the routers don't list.
- After a failover to a new designated node, the inventory starts empty until the next polls, and imports must be uploaded again (ADR-913).
- With DSC-012 on, a spoofed MAC could claim a named device's address. ADR-902 already accepts the same exposure for leases.
- SNMP identity does not improve identify's class guesses in M25. Left Open.
- Closes T22.3's Open item "the neighbor table as a MAC → address source".
Requirements AGT-011 DNS-023 DSC-012 OBS-014
Builds on ADR-102 ADR-117 ADR-125 ADR-156 ADR-161 ADR-901 ADR-902 ADR-907 ADR-908 ADR-909 ADR-913
Referenced by ADR-1000 ADR-1004 ADR-1005 ADR-907 ADR-909 ADR-912 ADR-913 ADR-923 ADR-924 ADR-942
Link to this decision · In the specification
ADR-911 Dependency aes 0.8 for SNMPv3 privacyThe owner asked for authPriv.
Context
The owner asked for authPriv. RFC 3826 needs AES-128 in CFB-128 mode. ring exposes AES only inside AEADs and QUIC header protection. cipher 0.4.4, inout, crypto-common and cpufeatures 0.2.17 are already in Cargo.lock, pulled in through crypto_box and chacha20.
Decision
- Add RustCrypto
aes0.8 (MIT/Apache-2.0) towrendns-snmponly. - Write CFB-128 by hand, about 20 lines, instead of adding
cfb-mode. The IV is engineBoots ‖ engineTime ‖ salt. - PR justification line: "aes 0.8: SNMPv3 AES-128-CFB privacy (RFC 3826); ring exposes no raw AES block; cipher/cpufeatures already in tree; +12.4 KiB measured (x86_64 probe crate)."
- Gates:
cargo deny checkpasses, andcargo tree -dshows no duplicate versions;- the size delta is measured with
deploy/image/size.py --ocion amd64, arm64 and arm/v7 (armv7 builds the software fixslice path, arm64 the ARMv8 path); - the RFC 3826 test vectors pass on all three.
aesusesunsafeCPU intrinsics internally. As withring, third-party crates fall outside AGENTS rule 7, which applies to workspace code.
Alternatives rejected
- Hand-written AES: table lookups leak through cache timing, and hand-rolled crypto needs its own review.
- authNoPriv only: the owner asked for privacy. It stays the fallback if the size gate fails.
cfb-mode: one more crate for 20 lines.
Consequences
- About 12–20 KiB per architecture, to be measured.
- A Pi 4 has no AES instructions, so it uses constant-time software AES. At SNMP rates the cost is negligible.
Referenced by ADR-907 ADR-908 ADR-956
Link to this decision · In the specification
ADR-912 Extra read-only UniFi reads for the inventoryADR-080 and ADR-902 read stat/sta, rest/user (reservations only) and rest/networkconf.
Context
ADR-080 and ADR-902 read stat/sta, rest/user (reservations only) and rest/networkconf. UniFi also knows:
- offline and historical clients (
stat/alluser); - switch-port MAC tables with VLAN, and LLDP (
stat/device); - per-client
is_wired,sw_mac,sw_port,ap_mac,vlan,first_seenandlast_seen.
UniFi has no ARP endpoint. ADR-902 rejected known clients without a reservation as DNS names, because a stale address names the wrong device. routers.rs runs as tokio::spawn on the main multi-thread runtime (server.rs:1100), the same runtime that serves TCP, DoH and cache misses.
Decision
- With
[discovery] unifi_readsset, the designated discovery node makes these extra reads for each UniFi[[router]], with the same key or session:client_fields: more fields from the existingstat/sta/rest/useranswers, at no extra request cost;all_users:POST stat/alluserwithwithin = unifi_all_users_within_hours(default 720, maximum 8,760);devices:GET stat/device, for infrastructure identity, the portmac_table(VLAN,static,age),lldp_tableanduplink.
- Where they run. The
all_usersanddevicesreads, and the parsing of the extraclient_fields, run on thewrendns-inventorythread's runtime. They reuse the router's session and credentials.routers.rsonly shares the session and a copy of the raw answers it already holds. None of this work runs on the main runtime. - Each read is optional. A refused or failed read is logged once per change.
- Caps: 4 MiB and 8,192 rows per read.
- Results go only into the inventory (ADR-910):
- as class 1 (current clients), class 5 (history) and port locations;
- never into
router_leases,peer_namesordevice_dns; - counted against the 4,096-entry cap.
Ports whose mac_table holds more than 8 MACs, or that are UniFi uplinks, give no location.
- Home Assistant. With
home_assistant_all_devices = true(default true when discovery is on), a second fixed, read-only template runs on the inventory thread. It lists registry devices that have amacconnection and no entity (name_by_user,name, area). The answer is capped at 1 MiB. These names go into the inventory only. ADR-902's DNS-name template is unchanged. - Amends the "Not done" of ADR-080 and ADR-902.
Alternatives rejected
- Running the extra reads inside
routers.rson the main runtime: up to 4 MiB of JSON parsed next to DNS work. - The Integration API: a second code path with fewer fields.
- The fingerprint map (
/v2/api/fingerprint_devices): numeric IDs and an unofficial endpoint. Left Open. stat/alluseras DNS names: ADR-902's stale-address reasoning.
Consequences
- One or two more requests per UniFi poll, on one node.
- On UniFi switches, wired static devices show their switch port without SNMP.
- The field names come from reverse-engineered docs and are checked against a real console in e2e.
Builds on ADR-080 ADR-902 ADR-910
Referenced by ADR-1003 ADR-907 ADR-998 ADR-999
Link to this decision · In the specification
ADR-913 Importing scan results the owner produced: nmap XML and a simple CSVOnly a scanner can find devices that no source sees.
Context
Only a scanner can find devices that no source sees. The owner runs one themselves, for example nmap -sn -oX or nmap -sS -p … -oX on a host on that VLAN.
WrenDNS has no XML parser, and the uploaded file is untrusted input. The usual risks are XXE, entity expansion and very large files. Two existing stores would also hold whole bodies:
- the plan store keeps up to 500 plans for 24 h with the whole body (
plans.rs:30); - the idempotency table writes the full request into
state.db(managed.rs:186).
Decision
- Formats. Nothing else is accepted:
- nmap XML (
-oX, nmaprun 1.0x); - CSV with the header
ip,mac,hostname.macandhostnameare optional, each field may have one optional pair of double quotes, and the file is UTF-8.
- nmap XML (
- Parser. A hand-written restricted XML tokenizer in
crates/wrendns/src/discovery/import/, under the ADR-908 lints.- Accepted: the XML declaration, processing instructions (ignored), comments, and a
<!DOCTYPE …>without an internal subset. - Refused:
- a
[internal subset, and external IDs; - CDATA;
- a declared encoding other than UTF-8 (an optional BOM is allowed).
- a
- Entities. Only the five predefined entities and numeric character references are allowed. A numeric reference must be an XML
Char, so�and C0 controls other than tab, LF and CR are refused. No entity is ever defined or expanded. - Limits: depth 16, 200,000 elements, 32 attributes per element.
- Attribute values. The 4 KiB cap applies to the attributes the reader uses. Over-long values on ignored elements, such as
--scriptoutput, are skipped and counted, and they still count towardmax_bytes. - Truncation. A file that ends before
</nmaprun>(an interrupted scan) answers 422.
- Accepted: the XML declaration, processing instructions (ignored), comments, and a
- What is read. Everything else is ignored.
host/status[@state="up"];address(ipv4, andmacwithvendor);hostnames/hostname: up to 4, each at most 253 B;ports/port[@protocol="tcp"]/state[@state="open"]: up to 16 port numbers;- the top
osmatch@name, cut to 64 B; nmaprun@start, the scan time.
- Where parsing runs. In a separate, short-lived
wrendns discovery-worker --importprocess. It never receives credentials and exits after one parse.- It gets the same hardening as ADR-908:
/proc/self/exe, the version handshake,env_clear(),RLIMIT_DATA,PR_SET_DUMPABLE=0,RLIMIT_CORE=0,oom_score_adj1000. - The body arrives as binary chunk frames of at most 512 KiB, and the parse has 10 s of wall clock.
- A parse failure answers 422. A worker crash or timeout answers 503. DNS is unaffected.
- It gets the same hardening as ADR-908:
- Limits.
- The body is at most
max_bytes(default 8 MiB, maximum 32 MiB) and at mostmax_hostshost rows (default 4,096). - The import route sets an explicit
DefaultBodyLimitequal tomax_bytes, and reads the body as a counted stream that is forwarded chunk by chunk. It never buffers the body asBytes. - One import in progress per node.
- At most 10 imports per hour (429 with
Retry-After). - The last
keepimports are kept (default 16).
- The body is at most
- What is merged.
- Rows whose address is in a configured
[[discovery.subnet]]become sourceimport, tagged with the import ID. A row with a MAC goes into class 4. A row without one goes into the IP-only class. - Rows outside every subnet, or at a refused address (ADR-907), are counted as dropped.
- Imports never override class 1–3 bindings, never feed DNS or policy, and never make an address an SNMP destination (ADR-907, ADR-910).
- Device strings are sanitised as in ADR-908.
- Rows whose address is in a configured
- Provenance.
- Each import records:
- its ID and time;
- the user or agent, and the reason;
- the format and the scan's own start time;
- counts: merged, IP-only, dropped, skipped over-long values.
DELETEremoves an import's rows.
- Each import records:
- API and surfaces.
POST /api/v1/discovery/imports:Content-Type: application/xmlortext/csv;?dryRun=trueparses and returns the summary and the first 20 rows, and keeps nothing;Idempotency-KeyandX-Wrendns-Reason.
- For imports, the idempotency replay record stores a SHA-256 of the body and the response, never the body.
- On a non-designated node, an upload of at most 768 KiB is forwarded to the designated node. A larger one answers 413
import_too_large_to_forward, naming the node to upload to. - Humans need the operator role. Agents need
ops:discoveryand a reason. When[agents] require_approvalis on, agent imports go through the plan. - Audited as
discovery.importanddiscovery.import_deleted. - Also available in the UI,
ctland MCP (plan_import_scan→apply_plan).
- Plans.
plan_import_scan(content at most 768 KiB) parses in the import worker when the plan is made.- The plan stores only the parsed summary and at most 20 preview rows. The parsed rows sit in a separate bounded staging area: at most 2 open import plans per node, at most 4,096 rows each, dropped on apply, discard or expiry.
- The raw content is never stored and never appears in
list_plans.
- Storage. Parsed rows only, never the raw file. They live in the inventory file on the designated node, as the import-ID bitmask on each entry plus per-import counts. At most 8,192 import-derived rows in total; the oldest import is dropped first.
Alternatives rejected
quick-xmlorroxmltree: a new dependency for a small, fixed subset of XML.- Parsing in the SNMP worker: credentials and untrusted XML would share one process.
- Keeping raw bodies in plans or idempotency records: up to about 375 MiB in memory, above
MemoryMax=256M, and agents could read the raw scan. - Running nmap or scheduling scans: out of scope (ADR-907).
- Keeping raw uploads: size, and data that was never needed.
- Replicating imports to all full members: left as an owner question.
Consequences
- The operator's scans show up within seconds and can be removed again.
- Results from a routed scanner have no MAC until another source binds the address.
- Imported addresses get no SNMP identity reads until a class 1–3 source sees them.
- Imports are lost when the designated node changes.
Builds on ADR-907 ADR-908 ADR-910
Referenced by ADR-907 ADR-910 ADR-939
Link to this decision · In the specification
ADR-914 Which settings the UI may change, and how risky ones are guardedOn 2026-11-16 the owner made a standing rule: every setting, route and tool gets a UI control (spec/10, API-901).
Notes
How the guarded tier works is detailed in ADR-956 (framework) and ADR-957 (recovery), Accepted 2026-11-17.
Context
On 2026-11-16 the owner made a standing rule: every setting, route and tool gets a UI control (spec/10, API-901). An audit of the fork against the UI found settings with no control at all:
[special](M24, ADR-904) and most of[local](M22, ADR-901). Both are shared sections, not node-local (wrendns-config/src/shared.rsNODE_LOCAL).[clients] mdns, which[local] device_mdnsneeds before it does anything.- OTLP export (
[telemetry.otlp]), which is node-local. [agents] enabled, the agents kill switch (AGT-009).- The security gates and bootstrap settings: the secrets key files,
secret_file_dirs,allow_secrets_over_http,allow_insecure_basic, the listeners and their TLS,api.listen/api.tls,api.trusted_proxies, cluster init, join and bootstrap,[cluster.git],node.*identity and storage, the watchdog, and the file pathstrust_anchors_file,signatures_file,hosts_filesandzone.file.
The audit recommended showing the last group read-only. The owner chose admin controls instead (2026-11-16), on condition that the design is safe. The risks are concrete:
- a wrong listener, API address, TLS or proxy change locks every admin out of the UI, and a wrong DNS listener change takes the LAN's DNS down;
- a key typed into the store it protects is protected by nothing;
- a widened
secret_file_dirswould undo T23.2's path rules, andallow_secrets_over_httporallow_insecure_basicputs credentials on the wire in clear; - a cluster init or join replaces a node's configuration.
Decision
- Three tiers. Every setting is in exactly one:
- Ordinary: a managed kind with the role the area already has (viewers read; operators or admins change), as for groups and upstreams.
- Admin-only fields: a field inside an ordinary kind that only an admin may change, enforced by the server. An operator's change is 403 naming the field, and the UI marks the field
admin: true(the T23.2 pattern). - Guarded: the security gates and bootstrap settings below. Admin role only, with the guardrails in the next point.
- Rules for every tier.
- The file still wins over every UI value (ADR-040). A value set in a file is shown as "set by file" with the file's path, and an API write of it is 409
set_by_file. Removing it from the file uncovers the UI value, and the UI says so before that happens. - Role checks are on the server. The UI only hides or disables what the server would refuse.
- A section that is node-local (
NODE_LOCAL) becomes editable only throughnode_managed(T23.10), as an entry for the node it applies to (node/<node-id>/<kind>). Only that node applies it. An N−1 node ignoresnode_managed, so its own file stays in force. - A change that fails to apply keeps the previous configuration, and DNS keeps answering (CLU-004).
- A change to
auth-policyor the sign-in settings is refused (409would_lock_out_admins) if no admin could still sign in afterwards (for example, TOTP made required for admins while no admin has enrolled).
- The file still wins over every UI value (ADR-040). A value set in a file is shown as "set by file" with the file's path, and an API write of it is 409
- Ordinary and admin-only kinds this ADR adds.
special: a shared singleton kind (/api/v1/special-names/default) for all[special]fields. Operators change it.ddr_nameis admin-only, because it is one name for the whole cluster tied to every member's certificates (T24.12).local: a shared singleton kind (/api/v1/local-settings/default) fordevice_domain,device_ttl,device_mdns,auto_ptranddefault_ttl. Operators change it.hosts_filesis a path and is guarded (below).device_inventory_addresses(DSC-012) is admin-only (T24.13, T25.16).clients: a shared singleton kind that takes onlymdnsin M24, admin-only, because turning it on opens multicast listening on every member.mdns_portstays file-only and is shown read-only. The other[clients]fields join the kind in T27.9 under the operator role.otlp: anode_managedkind for[telemetry.otlp](endpoint, headers throughheader_refs), admin-only likesink(T23.11).agents: a shared singleton kind for[agents]. Turning agents off (enabled = false) needs the operator role; turning them on needs an admin. The server compares the old and new values, so an operator's write that turns agents on is 403. No agent scope writes this kind, so an agent can neither switch itself on nor off.rate_per_minuteandrequire_approvalare admin-only (T27.6).
- The guarded tier. Every guarded change:
- is admin role only, checked on the server; agent tokens are refused whatever their scopes (403
agent_not_allowed, on the spec/13 §3 list), and there is no MCP tool, plan orconfig:write:*scope for it; - needs an interactive admin session; API tokens of any kind get 403
reauth_requiredwith a hint naming the file or CLI step (as ADR-903 §8 does for passphrase backups); - has a dry run that says what the change does, which nodes it reaches and what it can break;
- needs a typed confirmation: the request carries
confirm, which must equal a phrase the dry run returns (the node ID and the setting, for examplepi-a listen). The server checks it, so a script or a forged request can't skip it; - is audited as
settings.guarded(who, node, setting, before and after with credentials redacted, the reason) and raises the one-off alert conditionguarded_setting_changed; - is a
node_managedentry on the node it applies to when the setting is node-local. A change to one node never reaches another.
- is admin role only, checked on the server; agent tokens are refused whatever their scopes (403
- Weakening changes. These are flagged in red as weakening security, and need a sign-in within the last 10 minutes (403
reauth_required, T23.9) on top of the confirmation:- adding a directory to
secret_file_dirs; - turning on
allow_secrets_over_httporallow_insecure_basic; - adding a
trusted_proxiesentry; - turning off the watchdog;
- removing or downgrading TLS on the API or on a DoT/DoH/DoQ listener, or moving
api.listenfrom loopback-only to a wider address; - in
auth-policy(T27.6), removing a role fromtotp_required_roles.
- adding a directory to
Narrowing secret_file_dirs is not weakening, but the dry run lists every *_file reference the change would refuse.
- Address and transport changes: confirm or roll back. Changes to
[[listen]](addresses, ports, TLS),api.listen,api.tlsandapi.trusted_proxiesare applied as pending:- The node applies the change and starts a confirmation window, 120 s by default (
[api] confirm_window_secs, 30 to 600, file-only). - The change is kept only if the same admin confirms it within the window, with a request that arrives through the new address and transport. For a DNS listener change, the confirmation also needs the node's own probe of the new listener to answer.
- Otherwise the node restores the previous values, audits
settings.guarded_rolled_back, and the UI says why. - A restart inside the window starts with the previous values. A pending change is held in memory on the target node only. The
node_managedentry is written and replicated only when the change is confirmed. For a change to another node, the primary forwards the pending change, and the confirmation must reach that node's new address directly. The response to the change carries a single-useconfirmToken, bound to the admin, node and change and valid for the window, so the admin need not sign in again on the new origin. - While a change is pending, the node keeps the previous API and DNS sockets bound alongside the new ones; the old ones close only when the change is confirmed, and stay if it rolls back. If a bind fails, nothing changes. The server refuses (409
would_disconnect_you) a change that would leave a node with no API listener or no DNS listener once confirmed, or that removes the API listener the request came in on in the same request that is meant to confirm it.
- The node applies the change and starts a confirmation window, 120 s by default (
- The secrets key. A key is never entered through the store it protects, or through any API body.
- The UI shows the key's status: its source (environment,
secrets_key_file, orsecrets.keyin the data directory),key_id, whether a previous key is configured, how many rows are still under it, and whether the store is locked or ephemeral. - Rotation is by pointing at a new key file the admin has already put on the node. The UI shows the steps (create the file with the format and permissions in
docs/secrets.md, owned by the service user, mode 0600) and the offline alternative,wrendns secrets rotate-keywith the node stopped. The admin then enters the new file's path. The server checks that the file exists, is a regular file with mode 0600 owned by the service user, and holds a valid key, without ever returning its content. It then writes a guarded entry for that node:secrets_previous_key_file= the current key's path,secrets_key_file= the new path. Re-encryption runs as at start-up (ops_014_previous_key_reencrypts_at_start, crash-safe). When no rows remain under the previous key, the UI offers to clearsecrets_previous_key_file. - A key from the environment is shown as "set by environment" and can't be rotated from the UI.
- The UI shows the key's status: its source (environment,
- Cluster init, join and bootstrap. These are explicit steps in a Cluster page wizard, each its own guarded change, never a field in a form:
- "Make this node a primary" (
cluster.init); - "Join a cluster" (
cluster.join_urland the bootstrap secret). The secret is entered write-only, over HTTPS or loopback (the API-015 rule), used for that join and never stored. A failed join leaves the node as it was. The dry run says that the node's configuration will be replaced by the primary's; - "Leave the cluster";
[cluster.git](repository, branch, path, authority). The dry run says when configuration authority moves to Git. The credentials stay T23.12'sSecretField.
- "Make this node a primary" (
- Other guarded settings.
node.*identity and storage (node ID, data directory): staged for the node's next restart and shown as "pending restart". A node ID change is refused while the node is a cluster member. A data-directory change never moves data unless the admin opts into Copy state (ADR-956 section 1(a):state.dband the defaultsecrets.keyonly, nevercluster/), and the dry run says what does not carry over.- The watchdog (
[watchdog]): guarded; turning it off is weakening. - The file paths
trust_anchors_file,signatures_file,hosts_filesand[[zone]] file: admin-only, confined by T23.2's path rules (the denied prefixes, the key files, every credential file the node uses,secret_file_dirs). The dry run parses the file and reports counts and line numbers, never its content. config_versionis the schema version, not a choice. It is shown read-only and is the one setting with no control.
Alternatives rejected
- Read-only display of the security and bootstrap settings, with the CLI step shown (the audit's recommendation): the owner chose admin controls.
- Guarded changes for operators: each of these settings can lock people out, put credentials in clear, or replace a node's configuration.
- Agent scopes for guarded changes: a plan's diff and an agent's transcript would carry the change, and a prompt injection could open the node.
- Applying listener and API changes at once without a window: one typo locks every admin out until someone edits the file on the node.
- Setting the key through the API or the secret store: the store would hold its own key, and the key would cross the network.
- Confirmation in the UI only: a script or forged request would skip it. The phrase is checked by the server.
Consequences
- Every setting but
config_versionhas a UI control, anddocs/and help topics say which tier each one is in. - An admin can change listeners, TLS and proxies from the UI, and a mistake undoes itself within the window.
- Guarded changes need two requests (the change and the confirmation), and weakening ones need a recent sign-in, so they can't be done from a long-idle session.
- The files keep the last word, so a node can always be recovered by editing its file and restarting.
- On installs whose file (or environment) sets a guarded value, its control shows "set by file" and the command to hand it to the UI (remove the key from the file and restart); the docs say which install bundles set which guarded values. Key rotation from the UI works only when the key path is not set by file or environment.
- Adds the problem codes
would_disconnect_you,would_lock_out_admins, the audit actionssettings.guardedandsettings.guarded_rolled_back, and the alert conditionguarded_setting_changed.reauth_requiredcomes from T23.9. - Amends ADR-040 (UI values for the sections above) and AGT-009 (the kill switch's role rule). T23.12's "
[cluster.git]itself stays file-only" becomes a guarded wizard step (T27.16). - Tasks: T24.12 (
special), T24.13 (local,clientsmdns), T24.18 (Pi-hole import, admin-only), T25.16 (device_inventory_addresses), T23.11 (otlp), T27.6 (agents), T27.13 to T27.17 (the guarded tier).
Requirements AGT-009 API-015 API-901 CLU-004 DSC-012
Builds on ADR-040 ADR-901 ADR-903 ADR-904 ADR-956 ADR-957
Referenced by ADR-1006 ADR-1007 ADR-1008 ADR-1019 ADR-1053 ADR-918 ADR-940 ADR-956 ADR-957 ADR-958 ADR-959 ADR-977 ADR-984 ADR-999
Link to this decision · In the specification
ADR-915 Image size: optimize cold code for size, embed only the gzip UI, and ship only the tz database the code readsNFR-001 (01, 00 §5) caps the compressed image at 15 MiB per architecture (deploy/image/size.py).
Notes
Status note (upstream sync, 2026-11-17): partly superseded by ADR-168 and ADR-169. The zoneinfo step described here (the fork's own tz database, shipped whole) is replaced by upstream's zic -b fat build, and the CA bundle that ADR-168 drops is no longer copied. The other cuts stand.
Context
NFR-001 (01, 00 §5) caps the compressed image at 15 MiB per architecture (deploy/image/size.py). At 177ef45 the amd64 image measured 15.13 MiB, up from 14.76 MiB at 412add6. The new code (secrets, credential rules, lists refresh, federated paths, ctl, OpenAPI schemas) grew the stripped binary by 0.91 MiB. The dependency and UI changes added almost nothing. The binary is already at opt-level = 3, fat LTO, one codegen unit and panic = "abort", so the remaining savings come from what is compiled at a lower opt-level and from what is embedded.
Decision
Reduce the image in the order of saving against risk, without dropping a feature and without touching the DNS hot path (02 §3):
- API and MCP code at
opt-level = "s".[profile.release.package.wrendns-api]takes opt-levels; the rest of the workspace keeps opt-level 3.wrendns-apiholds the handlers, OpenAPI and MCP code, which are cold next to the DNS path. Measured: amd64 15.13 to 14.58 MiB. - Tz database without
right/. The image ships the TZif zones thatjiffreads (schedules, FLT-010), without theright/leap-second zones,tzdata.zi,*.tabandleap*files. Measured: 14.58 to 14.39 MiB. Known effect: a schedule that names aright/...zone no longer resolves. Schedules use the ordinary zone names. - Embed only the gzip of each text UI file.
ui/scripts/postbuild.mjsremoves the raw copy of a text file once its.gzis written. The binary embeds the.gz. A client that accepts gzip gets it as before. Any other client gets the same bytes inflated on the request, withminiz_oxide(already in the lock file, so no new package). Binary files (PNG, ICO, WOFF2) stay raw. Measured: 14.39 to 14.16 MiB. The postbuild script also resolves itsdistpath on Windows, where it failed before.
Final amd64 image: 14.16 MiB (headroom 0.84 MiB under NFR-001, 0.69 MiB under the 14.85 MiB target).
Consequences
- The API and MCP handlers run as size-optimized code. The DNS path crates keep opt-level 3, and their code is unchanged, so
make bench-smokeis not required by rule 4 for these changes. The API latency at opt-levelswas not benchmarked here and is a follow-up. - A
right/...zone name stops resolving in a schedule, with an error that names the zone. No feature is lost. - The UI's raw text files are no longer in
ui/dist. Tools that readdistdirectly (for examplevite preview) must useui/dist/*.gz, or runnpm run buildwithout the postbuild step. - Not taken, recorded here for the owner:
wrendns-configat opt-levels(about 0.2 MiB more, with per-query helpers in the policy path, so it needs a benchmark first),opt-level = "z"(about 0.5 MiB more, slower API handling), dropping the system CA bundle (0.12 MiB, needs its own ADR because the spec says the image ships one), and trimming serde code forConfig(0.1 to 0.2 MiB, a refactor).
Requirements FLT-010 NFR-001
Referenced by ADR-916
Link to this decision · In the specification
ADR-916 The fork's image gate is 25 MiB compressed per architecture00 §5 and OPS-001 cap the image at 15 MiB compressed per architecture, from upstream's footprint priority.
Context
00 §5 and OPS-001 cap the image at 15 MiB compressed per architecture, from upstream's footprint priority. On 2026-11-16 the fork's merged work (the Pi-hole parity work, the upstream sync and M23 wave 1, about 17,500 lines) took amd64 from 14.76 to 15.13 MiB. Three cuts that drop nothing brought it back under (ADR-915), but M25 (an SNMP codec, aes, an XML parser), M26 (the map UI) and M27 (UI for every setting) will add more. The owner runs Pi 4/5 and Linux hosts, where 25 MiB pulls in seconds. Memory (RSS) is the budget that limits small hosts, and it is unchanged (00 §5: idle ≤ 20 MiB, ≤ 64 MiB loaded).
Decision
the owner chose to raise the fork's gate to 25 MiB compressed per architecture (deploy/image/size.py LIMIT, make image-all, the image workflow). Upstream's 15 MiB stays upstream's. Every task still reports its image delta (deploy/image/size.py --oci) in its Done note, so growth stays visible, and a milestone that adds more than 2 MiB says why. ADR-915's cuts are kept. The RSS budgets, the FROM scratch image, the static musl binary and the multi-arch matrix are unchanged.
Alternatives rejected
keeping 15 MiB (constant trimming work for little gain on small hosts); 20 MiB (less room for M25–M27); no gate at all (growth goes unnoticed).
Consequences
Pi Zero-class devices, OpenWrt or OPNsense packages (upstream #12, #49) are a poorer fit. A change from upstream that relies on the 15 MiB headroom needs no special handling, since the fork's gate is looser. On an upstream sync, keep LIMIT at 25 MiB.
Requirements OPS-001
Builds on ADR-915
Referenced by ADR-1020 ADR-1030 ADR-1031 ADR-958 ADR-959 ADR-994
Link to this decision · In the specification
ADR-917 Replication details for stored secrets: orphans by epoch, a joining node's hand-over, the shadow table, and the reverse healADR-903 §6 fixes what replicates (stamped rows over the cluster channel, tombstones, orphans, re-encryption under each member's key, the reverse heal).
Context
ADR-903 §6 fixes what replicates (stamped rows over the cluster channel, tombstones, orphans, re-encryption under each member's key, the reverse heal). Building it left points it doesn't settle, which T23.5 had to decide.
Decision
- Orphans without a base stamp. A live cluster row that a member holds, that the current primary doesn't list, and whose stamp's epoch is older than the primary's, is an orphan: kept, flagged, never used, never deleted. ADR-903 §6 judges "stamped in an epoch after the new primary's base". The base isn't needed: the primary lists every cluster row it holds, so anything from an older epoch it doesn't list is one it never had, or its own orphan, and both are unusable. This judges more rows than the base rule would, and only ever toward "not used".
- A primary's orphans are not shared. The primary's export leaves out its own orphan rows, and its head is computed over the rows it shares, so a member's head and the primary's agree when both hold the same shared rows.
- A stale row yields to the primary's listing. A listed name whose row a member holds from an older epoch takes the primary's row, whatever the stamps say; the displaced row goes to the shadow table, not dropped.
- The shadow table (migration 12,
secrets_shadow, same columns assecrets; migration 13 keys it by(name, origin)). It holds one slot per name and origin: alocalrow a cluster row displaced, and aclusterrow a newer listing displaced (a stale copy under point 3, or a tombstone that a later live listing replaces under point 10). A tombstone that stays a conflict is not displaced: it stays the row insecrets. A displacement never replaces alocalshadow. Shadows are never used, appear in status asshadows, are sealed under the node key like the rows (rotation, the start-time re-encryption and the backup strip cover them), and come back as the local row when the cluster's rows are purged. The purge drops theclustershadows. Reverse heal and heal-as-replica refuse while a local shadow exists: it is this node's own value, and it's recovered by hand (docs/secrets.md). A heal refuses while an orphan it can still read exists, and drops one it can't read (point 15). - Joining. ADR-903 §6 says a standalone node's rows "become cluster rows on the primary" at join. Implemented as
secrets.adopt: a joining full member offers its own rows once per primary epoch; the primary takes the names it doesn't hold, stamped in its epoch, and reports the rest as conflicts. Atcluster initthe primary's own standalone rows become cluster rows in place, once. - Heartbeats. The fields are tags 33 to 38 of
Heartbeat.secrets_headis the node's own head;secrets_appliedis the primary head the node last verified and applied (its own head on the primary). Nodes without the tags read as "not reported" and are never fetched from. - Reverse heal is all-or-nothing. A locked primary whose rows are all the cluster's is refilled only from a replica that holds every one of its rows at the same stamp (tombstones included). A partial answer changes nothing.
- Removal purges. The sync task purges a member's cluster rows once the cluster lists it as removed (
removed.json), and the purge is audited assecrets.purge. A full member has no leave path (only resolver pods leave), so none purges on leave. - Where the tests are. The seeded partition and failover schedules are in
wrendns's secrets module, over the store, not inwrendns-cluster/tests/sim.rs(the election simulator), because the replicated state is the store's. The two-node tests run over the real mTLS channel in-process (secrets_api_tests), and the two-process test runs the built binary (crates/wrendns/tests/secrets_cluster.rs). - A listing doesn't undo a deletion, unless it's a later write. A cluster tombstone of an older epoch that a newer primary lists as live stays a tombstone row on the replica, and the name is reported as a conflict (
Applied.conflicts) and audited assecret.conflict, when the listed row's stamp is older than the tombstone's: a value the deletion superseded, held by a primary that never had the deletion. A listing stamped after the tombstone is a later write, possibly a re-creation in a later epoch: it is taken, and the tombstone goes to the cluster shadow slot (point 4). The stamps decide, not the epochs alone: checking the epoch alone kept a secret created again after an epoch change from ever reaching a replica (review N1). A same-epoch tombstone still yields to a higher stamp, as before. Before this point, the listing brought the revoked value back silently (review M4). - An emergency primary's answer is not authoritative.
FetchAns.authoritativeisfalsefor an emergency primary (absent meanstrue, so an older primary's answer reads as authoritative). A replica applies a non-authoritative answer by stamp only: it fills a name where it holds none, or an older cluster row, and displaces nothing and orphans nothing. An emergency primary's sync pass does no hand-over, refill or key replacement (ADR-903 section 4; review M1). - Hand-over is audited and never re-creates a name. Each name the primary takes is audited as
secret.adopt, and each refusal assecret.adopt_conflict, with the joining peer. A name the cluster holds, live or deleted, is a conflict; a row the primary can't accept (an unknown kind, an invalid value) is a conflict rather than a silent skip (review M3). Gating adoption to one epoch of the joiner's join is not done: the registry records no join epoch, so it is open for the owner. - A replica answers the reverse heal for the current primary. A replica's registry lists only itself, so the primary's registry check can't pass there. A replica answers
secrets.fetchonly for the primary of the highest epoch, which is always a full member; a primary answers only full members (!ephemeral && !witness && !removed). Found by the two-node reverse heal test (review M5). - Pulls are checked against the heartbeat. A replica applies an answer only when its head is the head the heartbeat announced and its primary is in the heartbeat's epoch. An answer that runs ahead of the heartbeat is not backed off: the heartbeat is a pass behind the answer, so the next pass (a few seconds later) asks again, nothing is applied, and a run of such answers is logged at warn from the third (review L1; the code does this from 2026-11-17). A failed pull is backed off as before.
- A heal drops what no key can read. A heal (heal-as-replica, or the primary's reverse heal) drops an orphan this node can't decrypt, with the other rows it can't read, and refuses while an orphan it can read exists: an orphan is no replica's row (the cluster doesn't list it, and an older epoch stamped it), so no fetch restores it, and keeping it locked the node for good when it had lost its key (review N2). The heal's audit record
secrets.healnames the dropped orphans and gives the counts of rows and cluster shadows cleared (names and counts, never values), and the log says the same. A local shadow still refuses a heal (point 4). Recovery of a locked node whose local shadow is the blocker is the documented step indocs/secrets.md.
Consequences
No new crate. Two migrations (12 and 13). Everything the sync does to the store, the registry, the credentials or a file runs on a blocking thread (tick), so the runtime that serves DNS never waits on it (CLU-004; review M2); nothing reads the manifest, so pins and canary bakes don't gate replication. A heartbeat grows by a few dozen bytes when a node holds secrets. Plaintext intermediates on the channel are only partly zeroized: the answer and hand-over buffers cross the channel as Vec<u8> (review L2, partly).
Alternatives rejected
a base-stamp orphan rule (it needs the primary to record a base at promotion, and it misses rows the base rule would call fresh); deleting orphans (a row must never vanish without a tombstone); the shadow row in secrets under a second name (it breaks the one-row-per-name invariant every reader relies on).
Status
Accepted 2026-11-17. The owner accepted every ADR for the overnight run. Points 1 and 5 deviate from ADR-903 §6's wording. Points 10, 14 and 15 are the review fixes of 2026-11-17 (N1 to N3 of the second review), and point 10 supersedes the epoch-only rule of its first form.
Requirements CLU-004
Builds on ADR-903
Referenced by ADR-1005 ADR-1021 ADR-1027 ADR-1045 ADR-1051
Link to this decision · In the specification
ADR-918 Shared settings sections: field-level file precedence, what a request may leave out, and admin-only fieldsT24.12 ([special]) and T24.13 ([local], and [clients] with mdns only) make three one-entry sections changeable from the UI and API under ADR-914's tiers.
Context
T24.12 ([special]) and T24.13 ([local], and [clients] with mdns only) make three one-entry sections changeable from the UI and API under ADR-914's tiers. The one-entry kinds so far (rate limit, exclusions, simulation) replace the file's whole section. For these, that would let an API value override a field the files set, which ADR-040 and ADR-914 forbid. ADR-914 didn't settle three details: which fields the files win over, what a request that leaves out a file-set field means, and what an empty device_domain means.
Decision
- Files win field by field. The loader records the dotted keys (
special.ddr_name,local.device_domain,clients.mdns) that the configuration files and environment set explicitly (Config.file_set). At merge time a stored field whose key is in that set is ignored, so the file's value applies. The UI shows it as "set by file". - Requests. A
PUTstores every editable field (fields left out take their defaults, as the other one-entry kinds do), except a file-set field left out, which keeps the file's value (as a credential does under ADR-903 §2). APUTthat sets a file-set field to another value is 409set_by_filenaming the field. Setting it to the file's own value changes nothing and is accepted. - Read-only fields.
hosts_filesandmdns_portare shown in the entry and can't be set here: sending back the value the entry shows is accepted, another value is refused (422, naming the field). device_domain. An empty string ornullmeans no device names (off). It isn't an invalid domain.- Admin-only fields (
special.ddr_name,clients.mdns). A change to one is checked on the server: an agent's is 403agent_not_allowed; an operator's is 403 naming the field; a change forwarded from a node too old to say who made it is 409upgrade_required. An agent can't write[clients]at all: no agent scope reaches/api/v1/clients-settings/default. - Plans. The MCP plans for these sections fill the fields left out from the entry as it is now, as the other plans do.
Alternatives rejected
- A stored partial section laid over the file: a file change would then leave an old API value hidden under a field the file no longer sets. Full sections are stored instead.
- Silently ignoring a file-set field in a request: the UI would show a value it can't set. A 409 naming the field says so.
- Treating
device_domain = ""as invalid: the UI and agents both need a way to turn names off with the same form.
Consequences
ConfigEntrygainssetByFileandanswering(optional fields, so an older node's answers still read).Explanationgainsspecial(optional).- Environment-set keys count as file-set, so the UI says "set by file" for them too. A separate "set by environment" label is a follow-up.
- A file change takes effect on the next reload. A stored value for a field the file now sets is ignored at once, and kept in
state.dbuntil someone reverts it. [clients] mdnstakes effect after a restart (H1). The mDNS listener starts once, at start-up (restart_only_changeslists it). A change is stored at once, but the dry run and the write say it takes a restart on every node, and device names follow mDNS only while the listener the node started with runs (device_dns::runtakes the start-up value). Starting and stopping the listener on reload is a follow-up.- Set-by-file marks come from the files (M2). The API marks a field from
file.file_set(the loaded files), not from the configuration in effect: a merged configuration doesn't carryfile_set(it isn't serialized).plan_settingschecks against the files too, so the marks and the refusals agree. - Known divergence on a promoted primary (M2, not fixed here).
overlaylays the stored section over the files, skipping only the fields the node's own files set. On a promoted primary, a field the files set can keep the value the cluster version stored, not the node's own file value, so that node's effective value can differ from its file (the UI still marks the field "set by file"). The files-win rule is therefore not yet exact on that path. Fixing it (drop stored values for file-set keys when a node is promoted, or carry the node's ownfile_setthroughoverlay) is a follow-up, and the next change to these sections on a promoted primary must not rely on the stored value. - Version gate (M3, CLU-010). The settings kinds go only to a primary at 0.8.0 or later (
SETTINGS_KINDS_SINCE). An older primary gets 409upgrade_requiredfrom the replica before anything is forwarded, not an opaque failure.
Requirements CLU-010
Builds on ADR-040 ADR-903 ADR-914
Referenced by ADR-956
Link to this decision · In the specification
ADR-919 Secret fields in the UI: save writes the secret first, clear unlinks, and a file the configuration sets stays read-onlyT23.6 adds the Integrations & secrets page and SecretField, the one control every credential is entered through (ADR-903 §9).
Context
T23.6 adds the Integrations & secrets page and SecretField, the one control every credential is entered through (ADR-903 §9). The API has two rules that shape the form: a *_ref naming an unset secret is refused (422 secret_missing), and a delete of a secret a field still names is refused (409 secret_in_use). So a form can't save an entry and its new secret in one request, and can't delete a secret through an entry that still names it.
Decision
- Save writes the secret at once. "Save secret" stores the value (
PUT /api/v1/secrets/{name}) before the entry is applied, then sets the entry's*_refin the draft. The stored value exists even if the entry is never applied; the Integrations & secrets page lists it as unused. - Clear unlinks; it doesn't delete. "Clear" removes the reference from the draft, and the entry stops using the secret when it is applied. The state reads "will be cleared" until then, and Undo restores the reference. The stored value stays until someone deletes it on the Integrations & secrets page: a delete before the apply would be refused with 409
secret_in_use, and another entry may use the same secret. - Names. A new secret is named
<kind>.<entry>.<field>: for an alert destination's token,alert.<entry>.token, with the entry's name lowercased and slugged (runs of other characters become-) and cut so the whole name is at most 63 characters. An entry with no usable name has no default, so the field waits for a name andalert..tokenis never proposed. The name is editable before it is saved. - An existing secret is offered, not deleted. An entry whose default name is already stored shows "already stored" with Use it (which links the entry) and Replace; it never shows Delete. On the Integrations & secrets page a typed name that is stored is a replacement: the name stays editable and the value goes under it.
- A typed value holds Check and Apply. A value typed into a field and neither saved nor discarded would otherwise be dropped without a word. The form disables Check and Apply until it is saved (Save secret) or discarded (Discard).
- Writes carry the head. Every secret write sends the secrets head's etag, as the page last read it, as
If-Match(ADR-903 §2). A head that has moved is refused with 412: the page says so and reads the list again. - Unreadable and inline. A stored secret this node can't read shows "can't read it" with Replace. A
*_filethe node can't read shows the reason beside "set by file". A value the file sets inline is read-only ("set inline"). - Set by file. A
*_filethe configuration sets is shown read-only with its path and, when this node can judge it, whether it's readable; the API refuses changes to it (ADR-903 §2). A*_fileset through the API (not by the files) is not read-only: an admin's stored secret replaces it in the draft, and Remove the path drops it on an entry with no stored secret. A*_refthe files name is not reported as set by the file:set_by_filelists the inline value and the*_filepath, as the server has always done, so an admin can still change the reference. - Plain HTTP. The field explains a 403
insecure_transport(turn on HTTPS, or[api] allow_secrets_over_http), and warns before the save when the page itself is on plain HTTP from another host. The page can't tell whether the node allows plain HTTP for secrets, so the warning says the server may refuse. - No show toggle, no prefill. The value input is a password field with
autocomplete="new-password"and password-manager ignore attributes. ADR-903 §9 saysautocomplete="off";new-passwordis chosen because it tells a password manager that this is a new credential to store, not a login to fill, which is what the field takes; the owner should confirm it while this ADR is Proposed. After a save, a failure or a replacement the input is empty; the value is never returned by any API, so a page can't show it again. - Entries report file-set credentials.
ConfigEntry.setByFilelists the credential fields the configuration files set for an entry (token_file, an inline secret), for file-only entries too; before this it was empty for them, so a file's token looked editable.
Alternatives rejected
- Deleting the secret when it is cleared: refused while the entry still names it, and a second entry may use it.
- Saving the entry and the secret in one request: the API takes them separately (the secret store has its own rules, ADR-903 §4), and a failed entry save would leave an unlinked value.
- A reveal or copy button: it would contradict write-only (ADR-903 §9).
Consequences
- The form makes two requests for a new secret (the value, then the entry); a cancelled drawer leaves an unused secret, which the Integrations & secrets page shows.
SecretFieldis reusable: the routers (T23.8) and the other forms (T24.16) pass the draft's*_ref, the*_filepath and the role, and get the same states.- Operators see status only: the Integrations & secrets tab and the field show the same states, with the controls left out.
- The image gate is unaffected unless the bundle grows past the budget (400 KiB gzipped; now about 252 KiB).
Builds on ADR-903
Link to this decision · In the specification
ADR-921 Router integrations as a managed kind: admin-only, file-read-only, named secrets, no file paths through the APIT23.7 makes [[router]] a kind the API and UI change (ADR-903 §2, §7; API-016).
Context
T23.7 makes [[router]] a kind the API and UI change (ADR-903 §2, §7; API-016). ADR-903 §2 says router follows ADR-040 (names the files define are read-only through the API) and §9 says every credential is entered through SecretField. It doesn't settle three details: who may write a router, whether an API body may name a file path, and how a certificate is entered, since tls_ca is a file and ADR-903 §1 says the router's CA "becomes an inline tls_ca_pem (T23.8)" without a field.
Decision
- Admin only. Creating, changing, or removing a router is an admin's (403 for operators; agents never, by their forbidden list and scopes). A forwarded write without a role (an older node) is 409
upgrade_required, as credential writes are (ADR-903 §4). - Files win. A name the files define is read-only here:
PUTandDELETEare 409set_by_file(ADR-040). The files' entry shows assource: file. - Named secrets only.
api_key_ref,api_secret_ref, andpassword_refname stored secrets (422secret_missingwhen none has the name). A body that namesapi_key_file,api_secret_file,password_file, ortls_cais 422invalid_config: the API takes no file paths for a router, because a path the API can set is a path an admin can point at any readable file (ADR-903 §4, the path rules). The files keep their paths. - The certificate as text.
tls_ca_pemholds PEM certificates (16 KiB at most; each must decode, and at least one is required; exclusive withtls_ca). The form saves the chain the console presents (its certificate and the CAs it sends), so a console signed by a private CA is trusted with its CA, and nothing else is trusted for that router: a router client trusts those certificates in its settings, not the public roots (ADR-120). Review of T23.7: a bare marker or a body that isn't base64 is refused. - Ephemeral pods read no router (ADR-903 §7 and the Helm resolver pods' note in ADR-120): the controller, or the primary for a stored credential, reads them.
Consequences
- A router made in the UI can't use a file: an operator who wants a file adds it to the configuration file (the UI says so).
tls_insecure_skip_verifyis not offered by the UI and is still file-only.- The MCP surface gets
list_routers(read-only). No MCP tool, and no agent scope, writes or checks a router (ADR-903 §5).
Requirements API-016
Builds on ADR-040 ADR-120 ADR-903
Referenced by ADR-1019 ADR-967 ADR-984
Link to this decision · In the specification
ADR-922 Router hot reload: the live list, per-router state, debounced reads, and checks that never send a stored key to a new addressrouters::run took the [[router]] list at start-up and returned at once when it was empty (T8.2).
Context
routers::run took the [[router]] list at start-up and returned at once when it was empty (T8.2). T23.7 needs a router added, changed, or removed through the API to take effect without a restart, with the others' names kept (CLU-004, 02 §8), and T23.8 needs a check of a draft that reads a router once.
Decision
- The live list. The poll loop reads
Sources.configeach round. A reload (any node's configuration change, or a secret the store changes) wakes it at once (Sources.routers_changed). - Per-router state. A router keeps its last answer while its settings are unchanged. A changed router is read again, debounced to at least 5 s after its last read; it keeps its last names until that read succeeds, unless its address or kind changed (another device: its names go at once), and its status reads
waitinguntil then (review of T23.7). A removed router drops its answer, so its leases go with the next round. A router whose stored credential may have changed is read again, debounced the same way. The store is not asked on the loop (a lock held at start-up delayed the runtime's workers). - Failure isolation. Each read runs on its own task and reports through a channel. A router that fails (refused, timed out, malformed, oversized) keeps its last answer and is retried within 15 s; the others are not delayed. DNS is never on this path.
- Who reads. A stored credential is read on the primary or a standalone node only; a replica gets its names through the peer leases (ADR-125). A file credential is read as before on every full member, and a resolver pod reads nothing.
- Status. Each router's last read (state, time, error without any password, devices, networks, and where it's read) is kept for
GET /api/v1/routers. - Checks.
POST /api/v1/checks/routerreads a draft once and saves nothing. It sends a stored credential only where it was saved for: the saved router's own secret, when the draft's address and TLS settings equal the saved router's, or the secret named for this router (<kind>.<name>.<field>) when either no router is saved under the draft's name (a new router) or the draft's address and TLS settings equal the saved router's, and no other entry of any kind (router, alert destination, sink, OIDC provider, Git source) uses it. Any other reference is dropped; the check runs without it and says so (credentialSent: false) (review of T23.8; review NEW-1 and NEW-2: a saved router's named key never goes to a new address, and a secret another kind uses is never sent for a router's name). Both checks are admin-only and refused to agents.POST /api/v1/checks/router-certificatemakes one TLS handshake and returns the names, fingerprint, and PEM; it trusts nothing, and the PEM is saved only by the form.
Consequences
- A stored key never goes to an address the admin didn't save it for, even by an admin's check.
- Residual (review NEW-1): a new router that reuses the name of a deleted router can have that router's leftover named secret sent to its new address, since no saved entry under the name records the old address. Deleting a router does not remove its secret; the admin can delete the secret itself.
- A router whose console renews its certificate fails until the new certificate is saved (ADR-120).
- The poll loop, its reads, and its failures are tested with local fake routers only (HTTP, and TLS on 127.0.0.1).
Requirements CLU-004
Link to this decision · In the specification
ADR-923 Source classes for the sources ADR-910 leaves open: Home Assistant, mDNS, configured namesADR-910 sets the precedence classes for UniFi and OPNsense (class 1), the neighbour table (class 2), SNMP ARP (class 3), imports (class 4) and UniFi history (class 5).
Context
ADR-910 sets the precedence classes for UniFi and OPNsense (class 1), the neighbour table (class 2), SNMP ARP (class 3), imports (class 4) and UniFi history (class 5). It does not place Home Assistant, passive mDNS, SNMP identity or the configured client name. The first draft of this ADR put Home Assistant and mDNS at class 2. The T25.1 review (2026-11-17) found that an unauthenticated mDNS announcement would then make its address an SNMP destination (ADR-907), and that an identity answer would back its own eligibility.
Decision
- Home Assistant trackers and passive mDNS announcements carry their addresses as claims with no class. They never make an address current, never make it an SNMP destination (ADR-907), and never win a conflict. They sort after the classed bindings, with imports. Both come from the device or its tracker, not from a router's own table.
- SNMP identity (sysName and printer names) and the configured client name (
[[client]]) carry no class. SNMP identity carries names only. The configured name attaches to entries and never creates one. An SNMP ARP binding is class 3. - A claim with no MAC whose address a MAC entry holds as a current binding attaches to that entry, with its names and ports. Any other claim with no MAC goes to the IP-only class (ADR-910).
- Name ranks follow ADR-910 exactly. A name's label is labelled with its source for ranks 6 and 7. A name replaces the earlier name of the same kind from the same origin (the
[[router]]for router aliases), so a rename shows. - Conflicts: the newest class 1–3 claim wins the address. A class 4, class 5 or unclassed claim never removes a current binding and raises no conflict: it is a claim, not a current owner. A current claim on an address another MAC entry holds as current flags both entries
ip_conflict, with a hold of 900 seconds from that claim (conflict_until). A competing claim refreshes the hold, and the flag clears only after the hold has passed (the sweep checks the hold, not the owner count, because the displaced binding is gone from the address at once). IP-only entries take no part in conflicts. - A claim with no MAC attaches to the MAC entry that holds its address as a current binding, or failing that, to the MAC entry that holds it from the same source (so a device's own mDNS record does not split off an IP-only duplicate when its router binding expires).
- Each source keeps its own record of an address (per address, source and import). A source refreshes only its own record, so another source's claim on the same address never keeps a stale binding alive (ADR-924).
- A randomised MAC (the locally administered bit set) gets
randomizedand never raisesnew_device.
Alternatives rejected
Home Assistant at class 1 (its trackers come from a template, not a router's table, so a stale tracker would outrank a live neighbour entry). Home Assistant and mDNS at class 2 (the first draft: an unauthenticated mDNS announcement would make its address SNMP-eligible).
Consequences
a device seen by Home Assistant and by the neighbour table has one current address, the neighbour's, and Home Assistant's stays a claim. The address that ADR-910's DNS opt-in (DSC-012) may use therefore comes only from classes 2 and 3; an mDNS-only address never supplies one. The owner confirms the classes at the T25.0 review. Until then this conservative choice stands.
Requirements DSC-012
Builds on ADR-907 ADR-910 ADR-924
Referenced by ADR-1003 ADR-1004 ADR-925
Link to this decision · In the specification
ADR-924 Inventory retention and expiry: two missed polls, per-entry caps, and the import rulesADR-910 fixes the caps and says a host counts as absent only after two polls in a row miss it, without saying how a poll interval maps to time, or what an entry with no address left should do.
Context
ADR-910 fixes the caps and says a host counts as absent only after two polls in a row miss it, without saying how a poll interval maps to time, or what an entry with no address left should do.
Decision
- A source's binding expires when
seen + max_age < now.max_ageis twice the source's poll interval: 120 s for the neighbour table (polled every 60 s), 900 s for the routers and mDNS (their cadence is "every few minutes",devices.rs). - An entry with no address, no import, and no change for
retention_days(7) is removed. An entry with only a name and no address stays until that retention passes; names are not expired separately. - Imports: an import past
[discovery.import] retention_days(30) is removed with all its rows. Deleting an import removes its bindings, clears its ports when no other import holds the entry, drops import-only names, and removes entries left empty. - Caps: the oldest MAC entry (by
last_seen) goes at 4,096, the oldest IP-only entry at 1,024, and the oldest import goes first when the import count reaches 16 or the import rows pass 8,192. A single import over 4,096 rows is refused. - A conflict flag clears on the sweep once no two entries claim the address.
- The import ports (open TCP) are kept on the entry, sorted and capped at 16. They are cleared when the last import holding the entry goes.
- Each source's record of an address is its own (per address, source and import). A claim from another source never refreshes it, so an import cannot keep a stale neighbour binding alive (T25.1 review).
- Mutes are capped at 1,024 (the oldest goes first) and pruned by the sweep for entries that are gone or for mutes that have expired.
- A stored
inventory.jsonis checked on load: an import bit past 15 or a bit no kept import holds is dropped with its bindings and ports, and the 8,192-row cap is applied again. A file this version cannot read (a corrupt file, or another version) is moved toinventory.json.badand the inventory starts empty, so the owner's data is kept, not overwritten.
Alternatives rejected
a fixed per-source TTL with no link to the poll interval (it would drop hosts on a slow router poll); per-row import expiry (more state for the same effect).
Consequences
a host the neighbour table drops for two minutes loses its neighbour binding, and it keeps its other bindings. A router that is slow to answer keeps its binding for 15 minutes.
Builds on ADR-910
Referenced by ADR-1004 ADR-1005 ADR-1024 ADR-923 ADR-942
Link to this decision · In the specification
ADR-925 Inventory thread and its inputs before [discovery]: off by default, the Home Assistant feed deferredT25.1 builds the inventory thread (wrendns-inventory) and its read-only sources.
Context
T25.1 builds the inventory thread (wrendns-inventory) and its read-only sources. The switch that starts them is [discovery], which is T25.2. Nothing in the server reads Home Assistant's raw answer after routers.rs folds it into the lease view, and the owner has not yet decided how a discovery node is chosen.
Decision
- The thread's
spawnexists and is tested throughtick, but no startup path calls it. T25.2 wires it behind[discovery] enabled(default false) and the designated-node rule (DSC-001).discovery/mod.rsallows dead code for that reason. - Sources wired in T25.1: the filtered kernel neighbour table, the routers' lease view (
devices::Leases, class 1, a lease with aroutername), and the passive mDNS lease view (a claim with no class, ADR-923; IP-only when no MAC, and attached to the MAC entry that holds the address otherwise). Home Assistant's named devices are a pure function (sources::ha_observations, tested on fixtures). Its live feed needsrouters.rsto keep the last raw answer, and that stays Open until T25.10 (DSC-009) reads Home Assistant's registry anyway. inventory_mergeis a fuzz target that includescrates/wrendns/src/discovery/inventory.rsby path, so the fuzzer runs the same source the server builds, without a dependency on the binary crate.
Alternatives rejected
starting the thread now (an off-by-default feature would then run on every node); a separate wrendns-inventory crate (the module needs devices and routers, which live in the binary crate, and the merge is small).
Consequences
the inventory is not visible to any API until T25.12. Nothing in wrendns reads inventory.json yet. The Home Assistant feed is Open.
Requirements DSC-001 DSC-009
Builds on ADR-923
Link to this decision · In the specification
ADR-926 Credential rules in the forms: judged from the saved entry, and a draft that needs an admin is heldT24.16 puts ADR-903 §4's admin rules in every form (API-014).
Context
T24.16 puts ADR-903 §4's admin rules in every form (API-014). The server already refuses each change; the forms must show the owner who may make it and why, and must not let an operator fill in a change that will be refused. Two details are open: a form's lock can only use what is saved, and the upstream headers and arguments have no field in the form until T27.3.
Decision
- Locks are judged from the saved entry. A field's
adminrule reads the entry as it was read, and the credential paths it keeps (ConfigEntry.redacted: headers, arguments, a password in an address). A draft's own value doesn't make a field read-only, since a field that locks while it's being typed can't be corrected. A draft that switches to a program address (exec://,unix://), or changes a saved program entry's arguments, instead holds Check and Apply with the reason (ConfigEditoradminOnly, which is given the saved entry, or none for a new one), and the server refuses it too. A saved program entry changed only in its weight, timeout or other fields is not held. - The rules as the forms apply them.
- Upstreams:
urlis an admin's when the entry keeps a credential or runs a program (saved);tls_server_namewhen it keeps one. "Keeps a credential" is the server'sholds_credential: a redacted path, a credential file (tls_client_key), or a stored reference (*_ref,*_refs). - Alerts:
typeis an admin's when the destination holds a credential (the existingurl,tls_caand secret rules are unchanged). - Names on my network, forwards: a server that is
exec://orunix://is an admin's, and Save is off for an operator. - Every kept credential shows the badge "kept: re-enter to change" in its row.
- Upstreams:
- Headers and arguments. They have no field in the upstream form until T27.3. A change of the address that the server refuses for a kept header says which field, and that the form can't enter it: use
wrendns ctlor the configuration file. No headers field is added here, so the message is the resolution this task owes (T24.16's "or the message above").
Consequences
- A form can be stale about a rule the server adds later. The server stays the authority: every refusal still comes back as a problem code, and its message reads as a sentence (ADR-927).
- An operator who pastes an
exec://address sees the reason and a disabled Save, not a refusal after the fact.
Requirements API-014
Link to this decision · In the specification
ADR-927 Problem codes read as sentences in the UI; the server's detail stays on the errorT24.16 asks that ApiError give readable messages for the credential codes (path_not_allowed, set_by_file, credential_reentry_required, upgrade_required, secret_missing, secret_in_use, secrets_locked, insecure_transport, lists_not_here).
Context
T24.16 asks that ApiError give readable messages for the credential codes (path_not_allowed, set_by_file, credential_reentry_required, upgrade_required, secret_missing, secret_in_use, secrets_locked, insecure_transport, lists_not_here). Until now ApiError.message was the server's detail, which names the field well but reads as a log line. Two places (SecretField, SecretsPanel) matched the detail's text to recognise a secret that is in use elsewhere.
Decision
- The problem
codeis the contract.ui/src/lib/api.tsmaps each listed code to a sentence, which becomesApiError.message. The server's text stays onApiError.detail, unchanged. - A code with no sentence reads as the server's detail, as before.
- Recognition of a case by its text uses
detail, never the sentence (secret_in_use"can't be read now"). - The field a detail names (its first backquoted token, never the
<redacted>marker) is quoted in the sentence, so the owner sees which setting to change. Acredential_reentry_requiredsentence follows the detail's case: a check never uses a stored value (Test it), no stored value to keep, or the destination changed. A header or an argument's hint is not shown beside its sentence, since the sentence already says how to enter it. - The Routers page's credential input (
CredentialInput.svelte, T23.8's open item) is replaced bySecretFieldand removed. Its Playwright tests use the field'sdata-modeand its save button.
Consequences
- A sentence is text the owner reads, so changing one is a UI change: the Playwright test
api_015 errors read as sentencesnames each code and the words it must show. - The sentences are in English only, as the rest of the UI is.
Referenced by ADR-926
Link to this decision · In the specification
ADR-928 [discovery] as a managed kind: admin-only, no agent scope, and the first write waits for N−1 membersADR-907 makes [discovery] a shared section written through the config entries API as the managed kind discovery, admin-only, with dry run, If-Match and audit, and says the first write waits while any member runs N−1 (CLU-010).
Context
ADR-907 makes [discovery] a shared section written through the config entries API as the managed kind discovery, admin-only, with dry run, If-Match and audit, and says the first write waits while any member runs N−1 (CLU-010). It doesn't say where the kind lives, what the version threshold is, or whether later writes wait too.
Decision
- The kind is
discoveryat/api/v1/discovery-settings/default. The path is-settingsbecause/api/v1/discoveryis the inventory's own read (T25.12). - Every field is admin-only (
settings_kinds::admin_keys): an operator's change is 403 naming the field, and an agent is 403 (agent_not_allowed). The auth table refuses the whole/api/v1/discoveryprefix to agents untildiscovery:readexists. - The first write (none stored through the API yet) is refused with 409
members_too_oldwhile any member reports a version older thanDISCOVERY_SINCE= 0.8.0, or one that can't be read. Later writes don't wait: the members already took the first. - A forwarded write to a primary older than 0.8.0 is refused with 409
upgrade_required(as the other settings kinds are, CLU-010). - Review of T25.2 (2026-11-17): an unreleased build reports
dev, which no gate can read. This node's owndevcounts as the crate's version (forward::gate_version), because the code it runs knows every kind it has, so adevcluster's own node is not "too old". Another node'sdevstays unreadable and is refused. Release builds carry their version (CI stamps it), so they pass. DISCOVERY_SINCEis 0.8.0, the release that carries the section, the same asSETTINGS_KINDS_SINCE. The gate is tested with the real build version through the real route (dsc_001_current_build_passes_the_gate).
Alternatives rejected
waiting on every write (a member that is upgraded and back would still need the first write to be accepted, so this only added a second wait); the threshold at 0.9.0 (the workspace is 0.8.0 until it ships, so every node, the node itself included, counted as too old and the first write could never succeed); a feature flag advertised by each member (it would need a new field in the membership record; the version already says what a member knows, and the gate is the same check the other kinds make).
Consequences
DISCOVERY_SINCE moves with the release that carries this section. The first write on a cluster with an older member is refused until that member is upgraded, which the UI says.
Requirements CLU-010
Builds on ADR-907
Referenced by ADR-1001 ADR-1005 ADR-948
Link to this decision · In the specification
ADR-929 Discovery worker protocol v1, its debug-only fault jobs, and the status API before T25.12T25.3 builds the worker processes of ADR-908 before the SNMP codec (T25.4) and the import parser (T25.11) exist.
Context
T25.3 builds the worker processes of ADR-908 before the SNMP codec (T25.4) and the import parser (T25.11) exist. The worker needs a protocol that those tasks can build on, and a way for the tests to see a worker panic, hang or run out of memory without a test-only build of the server.
Decision
- Frames are a u32 big-endian length (counting the kind byte), one kind byte, then the payload: kind 1 JSON (at most 1 MiB), kind 2 binary chunk (at most 512 KiB). The length is checked before any payload is read or allocated (
discovery::frames). - Messages are JSON objects tagged by
t:hello,job,result. Protocol 1. Ahellomismatch of protocol or build is answered with the worker's ownhelloand an exit code of 3; the parent raisesdiscovery_worker_version_mismatchand starts nothing else. - The
faultjob (panic,hang,alloc) exists only in debug builds, so the integration tests can run a real worker through a panic, a hang and an allocation pastRLIMIT_DATA. A release worker answers it as an unknown op. The bench-only override of the pacing floor is T25.4's, with the pacing. - The status API
GET /api/v1/discovery/status(DSC-014) is added now, for the worker card and the health reasons. It shows whether the node runs the inventory and each worker's state. It isdiscovery:read(DSC-013) only from T25.12, so agents get 403 on it until then (auth::agent).
Alternatives rejected
a fault switch in an environment variable (the environment is cleared for the worker, and a variable the parent can't set would be a second channel); a test-only build (the systemd e2e needs the release binary).
- Review of T25.3 (2026-11-17), the parent's side: the stderr of a worker is read one line at a time and each line is kept to 400 bytes (the rest is read and dropped up to the newline), with control characters escaped before logging, so a worker can't grow this process's memory or forge a log line (ADR-908, CLU-004). A worker that reports a limit other than the one asked for (dumpable, another data limit, another
oom_score_adj) is refused and restarts with backoff. A job's timeout is per op: apinghas 10 s, every other op 30 s (the SNMP walk budget of ADR-908); a new op names its own timeout insupervisor::timeout_for.
Consequences
the worker frame reader is the one piece of discovery code that reads bytes from a child process. Both readers are fuzzed by worker_frames: the synchronous one the worker uses and the async one the main process uses (frames::read_frame_async, which moved into frames.rs for that). The target fails if the two readers disagree on any input. The status API is read-only and unauthenticated only as far as every other status route is.
Requirements CLU-004 DSC-013 DSC-014
Builds on ADR-908
Link to this decision · In the specification
ADR-930 The designated node, its names, and the audit of [discovery]ADR-907 says [discovery] node names the node that runs discovery, else the primary or the standalone node, and never an ephemeral pod or a witness.
Context
ADR-907 says [discovery] node names the node that runs discovery, else the primary or the standalone node, and never an ephemeral pod or a witness. It doesn't say what a name is matched against, or when the section is audited. T25.2 settles both.
Decision
nodematches a member's cluster node ID or the node's configured name ([node] name, or the hostname). An operator who knows the name in the UI doesn't need the hash. A name that matches nothing runs nothing, and the status showsdesignated: falseon every node.- An ephemeral pod or a witness is never designated, even when named (
gate::designated). - The inventory thread and the workers start and stop at start-up and on every reload, from the same gate (
discovery::runtime::Runtime::reconcile). An API change reaches the designated node through the reload it already triggers. [discovery]is audited asdiscovery.config_changedwithsource = file: at start when the files set the section, and on a file reload that changes it. Changes made through the API are audited by the API with their author (as for every managed kind). The start-up record reads the files' own copy (Sources.file_config), never the merged config, so a section the API set is not labelled as coming from the file (review of T25.3).- Reconciles run in the order their reloads happened. Each reload takes a generation (
Runtime::next_generation) where it is handled, and a reconcile whose generation is older than the newest applied one is skipped. Two quick reloads (on, then off) can't leave the inventory running when the configuration says off (dsc_001_reconciles_apply_in_order, review of T25.3).
Alternatives rejected
matching the node ID only (the hash is unreadable in the UI); auditing every reload whether or not the section changed (noise in the log every SIGHUP).
Consequences
a node renamed in the file is no longer designated by that name, and the status says so. The owner confirms the name rule while this ADR is Proposed.
Builds on ADR-907
Referenced by ADR-1005 ADR-998
Link to this decision · In the specification
ADR-931 SNMPv3 time window: only authenticated Reports move the clock; an authNoPriv Report answers an authPriv requestThe m25-snmp review (2026-11-17) found that the ADR-908 amendment of the same day moved the one-per-minute resync limit from unauthenticated to authenticated Reports, and that an authPriv request could not be resynced at all.
Context
The m25-snmp review (2026-11-17) found that the ADR-908 amendment of the same day moved the one-per-minute resync limit from unauthenticated to authenticated Reports, and that an authPriv request could not be resynced at all. RFC 3414 §3.2.7a says a notInTimeWindow Report is sent at authNoPriv, and the agent checks the time before it decrypts the scopedPDU. The agent's Report therefore arrived at a level the client dropped, and it often carried request-ID 0. An agent that answers discovery with boots and time 0/0 (RFC 3414 §4 allows this) never worked at authPriv. Decision (proposed):
- An unauthenticated Report never sets the agent's clock. Only a Report whose MAC verifies may.
- For an authPriv request, a Report at authNoPriv is accepted if its MAC verifies, and its request ID is 0 or the request's ID. Any other reply at authNoPriv is dropped.
- At most one authenticated time resync per agent per minute. The request is sent once more, with the new boots and time.
- The window follows RFC 3414 §3.2.7b: boots at 2^31 - 1 are stale, and equal boots more than 150 s behind are stale.
Alternatives rejected
- Downgrading the request to authNoPriv after a failure: weakens the level the owner configured.
- Keeping an unauthenticated resync with a per-minute limit: a spoofed Report could still move the clock once a minute.
Consequences
- The ADR-908 amendment (2026-11-17) that describes the resync is kept as written, and this ADR governs the rule. Owner decision: accept this ADR, which then supersedes the one-per-minute wording of ADR-908.
- Interop with real net-snmp v3 agents is Open until the
TT_SNMPD_*values are supplied.
Builds on ADR-908
Link to this decision · In the specification
ADR-932 Credential file open: no followed symlink, no FIFO block, and the libc constantsThe m25-snmp review (2026-11-17) found two races in wrendns-snmp's credential read.
Context
The m25-snmp review (2026-11-17) found two races in wrendns-snmp's credential read. The path was canonicalized and then opened by name, so a link swapped in between pointed outside the secret directories. A FIFO was opened before its metadata was checked, so the open could block.
Decision
- The file is opened with
O_NOFOLLOW | O_NONBLOCK(libc0.2, the constants only, throughOpenOptionsExt::custom_flags, which is safe code). A final symlink fails the open, and a FIFO does not block. - The metadata is read from the handle, and only a regular file of at most 4096 bytes is read.
- The canonical path is canonicalized again after the open. Its device and inode must match the handle's (Unix; off Unix the canonical path alone is the check).
- The read buffer is allocated for the cap (4097 bytes) up front, so a read never reallocates and leaves no unzeroized copy.
- The decoded v2c community is held in
Zeroizing.
Alternatives rejected
a std-only check (symlink_metadata before the open) leaves the same race; an openat walk of each path component is more code than the risk needs for admin-owned secret directories.
Consequences
- A swap of a directory on the path between the last identity check and the read is not detected. The secret directories are admin-owned (
[node] secret_file_dirs), so this is accepted. libcis a dependency ofwrendns-snmponly. The lock already has it, so no new package enters the tree. The image delta is 0 bytes until T25.6 links the crate intowrendns.- Owner decision: accept or reject the
libcconstants.
Referenced by ADR-908
Link to this decision · In the specification
ADR-933 The worker's seccomp filter covers 32-bit ARM, so a discovery worker runs on armv7install_worker_seccomp covered x86_64 and aarch64, and returned Unsupported elsewhere (fail closed, ADR-908).
Context
install_worker_seccomp covered x86_64 and aarch64, and returned Unsupported elsewhere (fail closed, ADR-908). The image ships linux/arm/v7 (.github/workflows/image.yml) and the release ships wrendns-armv7-linux. On a 32-bit Pi, enabling discovery crash-looped the worker (discovery_worker_failing) and left the feature unusable. The review (N3) asked for a recorded decision.
Decision
write the filter for 32-bit ARM. AUDIT_ARCH_ARM (0x40000028) is the architecture check. The deny-list uses the ARM EABI numbers from libc (bind 282, listen 284, ptrace 26, the process_vm_* and io_uring calls at their generic numbers), and the x32 range check (ADR-934) applies to it too, where it does nothing. Everything else is as on the other architectures: the worker holds no capability, sets no_new_privs, and a call from another architecture kills it.
Alternatives rejected
keeping the refusal and naming the architecture in the health reason (leaves the feature unusable on the 32-bit Pi the image ships); a worker without a filter on armv7 (drops the "cannot share the DNS port" guarantee that the other architectures keep).
Consequences
the armv7 filter is type-checked and clippy-checked for armv7-unknown-linux-gnueabihf (the test binary included), and the filter's numbers come from libc's ARM table. It has not run on armv7 hardware here. A check on Pi hardware is an Open item in spec/10 (T25.3).
Referenced by ADR-1001 ADR-934 ADR-939 ADR-988
Link to this decision · In the specification
ADR-934 Worker spawn and filter hardening under the systemd unit: no ambient capability, no capset call without one, a non-dumpable parent, and the x32 and io_uring calls refusedThe review of the T25.3 fixes (276315b) found four gaps in ADR-908's worker hardening.
Context
The review of the T25.3 fixes (276315b) found four gaps in ADR-908's worker hardening.
- N1 (HIGH). The unit sets
AmbientCapabilities=CAP_NET_BIND_SERVICEandSystemCallFilter=~@privileged. A child inherits the ambient set, so the worker heldCAP_NET_BIND_SERVICE, anddrop_worker_capabilitiescalledcapset, which@privilegedcontains. A filtered call with no error number kills the process (SIGSYS), so every worker died on every systemd install. - N2 (MEDIUM). The filter checked the native syscall numbers only. An x32 call (
nr | 0x40000000) reachedbindand bound a loopback port (demonstrated on WSL2, kernel 6.6). io_uring's bind and listen skip the filter on kernels 6.11 and later. A worker of the same uid could open/proc/<parent>/memunder Yama ptrace scope 0, because the parent is dumpable. - N3 (MEDIUM) is ADR-933.
Decision
- Ambient cleared before exec.
wrendns_net::worker::prepare_spawnmakes every discovery worker spawn clear the child's ambient capability set between fork and exec. The call isprctl(PR_CAP_AMBIENT_CLEAR_ALL), which takes no pointers. A non-root worker then execs with no capability. capsetonly when a capability is held.drop_worker_capabilitiesreadsCapPrmandCapEfffrom/proc/thread-self/statusand callscapsetonly when either is non-zero. A worker with none never calls it. A root worker (tests, or a container run as root) still drops its capabilities. An inheritable bit alone grants nothing, since there is no exec file capability and no ambient one.- Parent not dumpable.
prepare_spawnalso makes the parent not dumpable (PR_SET_DUMPABLE0), so a worker of the same uid can't open its/proc/<pid>/mem(EACCES withoutCAP_SYS_PTRACE). It is called before each spawn, so only a process that runs discovery changes. The costs: this process refuses core dumps and debugger attach. The supervisor is the only caller. - Review of the m25-b branch (N6, N7, N8, 2026-11-17). Not dumpable makes the
/proc/selffiles that belong to the owner (/proc/self/io, mode 0400) root-owned, so a non-root wrendns (the systemd unit, the image, the chart) lost the host's write-rate metric, the SD-card wear signal on a Pi. Measured as uid 65534 (/proc/self/iorefused, whilestatus,limits,maps,smaps,exe,fd,taskand the/proc/selfowner stay readable by the process itself):prepare_spawnopens/proc/self/iobefore it makes the process not dumpable (sys::pin_self_io), andwrendns_net::self_io_textre-reads that descriptor withpreadat offset 0. The trade-off that remains for operators: once discovery runs, a non-root administrator can't read this process's/proc/<pid>/io,environ,mem, or attach a debugger orstraceto it. Root still can (CAP_SYS_PTRACE). It is indocs/running.md. The non-root testdsc_002_write_rate_survives_a_worker_spawn(uid 65534, run from a root test binary by re-executing it) is the proof. - The parent-read test (N7).
dsc_002_worker_cannot_read_its_parentmakes the middle process dumpable first, in both modes, because a process that changed uid at exec is already not dumpable and the shield would pass withoutprepare_spawn. The decisive check is thatprepare_spawnclears the dumpable flag (any Yama setting). The open is an end-to-end control that runs only under Yama scope 0, where the worker can read a dumpable parent. Under scope 1 (the Ubuntu default and this container) Yama refuses the open either way, so the control is skipped and printed as skipped. - Filter. The seccomp filter refuses every number at or above
0x40000000(the x32 range) with EPERM, and also refusesio_uring_setup,io_uring_enterandio_uring_registerwith EPERM. The arch check and the native deny-list are unchanged, plusarm(ADR-933). - Tests (
wrendns-networker::tests):dsc_002_worker_refuses_x32_and_io_uring;dsc_002_worker_without_capabilities_never_calls_capset(the filter kills acapsetcall, and a worker with none survives; the control dies with SIGSYS);dsc_002_worker_cannot_read_its_parent(the middle process is made dumpable first;prepare_spawnmust clear the flag; the open control runs only under Yama scope 0);dsc_002_spawn_clears_ambient_capabilities(as root: the raised ambient set is inherited withoutprepare_spawnand cleared with it).
Alternatives rejected
SystemCallErrorNumber=EPERMin the unit: the worker would get EPERM forcapset, andhardenfails closed. It would also change what every other filtered call in the unit returns. The capset skip fixes the cause and keeps the unit as it is.- A second uid for the worker: the image, the chart and the unit run one user (ADR-908), and a second one adds deployment work for a read this kernel setting already blocks.
- Leaving the parent dumpable and relying on Yama: Yama 0 is common on hosts and in containers, and it is the case that was open.
Consequences
the systemd unit is not yet run on a systemd host (the review ran none either), so the @privileged claim rests on systemd-analyze syscall-filter @privileged listing capset, and on the kill test. The ambient and capset tests need root (they skip otherwise). The worker's CapInh can be non-zero under the unit, since systemd sets an inheritable bit for ambient capabilities; it grants nothing, and the test asserts the permitted, effective and ambient sets only.
Referenced by ADR-1001 ADR-933 ADR-939 ADR-988
Link to this decision · In the specification
ADR-937 Per-list "Update now" and a Confirmed current column on the Lists pageT24.17 (FLT-004, ADR-905) asks for an "Update now" in each row of the Lists status table, and a per-list freshness display.
Context
T24.17 (FLT-004, ADR-905) asks for an "Update now" in each row of the Lists status table, and a per-list freshness display. The API already takes names (ADR-905), so no server change is needed. The task doesn't say what an off list's row does (the server reports an off list as skipped and queues nothing), or what freshness an inline list has (inline rules have no download to confirm).
Decision
- A row's Update now sends
POST /api/v1/lists/refreshwith{"names": ["<that list>"]}, the same request as the page-wide button. It shows for operators only (can('operator')), and is disabled while that list is refreshing, while any row's request is in flight, and when the list is off. The off row's tooltip says to turn the list on; the server is not asked. - A refresh of one list reads "<name> updated" in the status line; the whole-set sentence ("every enabled list confirmed current …") stays for a refresh of every enabled list.
- Confirmed current (for every role) shows
ago(lastSuccessUnixSeconds), which reads "never" for an enabled download list that never downloaded. An off download list that never downloaded reads a muted "off" instead (nothing to confirm, and "never" would suggest a fault). An inline list reads "inline", since it has no download to confirm. - The status line says "Downloading <name>…" from the click until the answer, so a row's request is never reported as done before it is answered. The whole-set wording is chosen by the refresh's scope (every enabled list, or one row), not by counting the lists.
- No dry-run control:
dryRunstays for agents andwrendns ctl.
Consequences
no API, OpenAPI, MCP or config change; the help topic list-update-now covers per-row updates. The per-row request is audited as lists.refresh with its names, like the page-wide one.
Requirements FLT-004
Builds on ADR-905
Link to this decision · In the specification
ADR-939 The Pi-hole import's worker: a child process with an empty environmentAn uploaded Pi-hole export is untrusted input.
Context
An uploaded Pi-hole export is untrusted input. A zip bomb, a malformed archive or a gravity.db built to crash the reader must not reach the DNS process (ADR-913 says why: a panic or an allocation failure in an in-process parser aborts DNS). ADR-913 names a worker mode (wrendns discovery-worker --import) that lives on the M25 branch, not in this tree.
Decision
- The worker. A hidden subcommand,
wrendns pihole-import-worker PATH, run by the server as a child process of the same binary. It reads the file, converts it with the importer (pihole::convert), and prints one JSON object. It has no configuration, no state database and no secrets. - Isolation.
env_clear(), stdin null, stdout piped, a 60-second timeout, and kill on drop. The worker starts with the discovery workers' spawn preparation (wrendns_net::worker::prepare_spawn: no ambient capability, and this process not dumpable, so the worker can't read the server's memory). The worker applies the discovery workers' hardening first (wrendns_net::worker::harden, ADR-933 and ADR-934:RLIMIT_DATAat 1 GiB, no capability,no_new_privs, the seccomp filter that refusesbind,listen,ptrace,process_vm_*,io_uringand x32 calls, not dumpable); if that fails, it prints the reason and converts nothing. The server reads the worker's stdout throughtake(64 MiB + 1), so an answer over the cap stops the read there and kills the worker. The upload is written to a0600temporary file that's removed after the worker returns, on a blocking thread. - Limits. The HTTP body limit is 64 MiB. The archive reader's limits apply (
archive.rs: 256 MiB per entry (lowered by ADR-988's review, 2026-11-18) and in all, no zip64, no encrypted entries, CRC checked, no path is written). A gravity.db is opened read-only from a temporary copy. - Failures. A file the importer can't read is 422 with the reason; a worker that stops, or takes too long, is 422 too, and DNS keeps answering.
Alternatives rejected
- Parsing in the server process. A panic there aborts DNS; the worker's crash is contained.
- Reusing ADR-913's
--importworker now. It isn't in this tree. The import reuses the discovery workers' hardening (wrendns_net::worker), not their mode; when the M25 branch's--importmode lands, the two can share one mode.
Consequences
- The
tokiocrate'sprocessfeature is enabled, which adds no crate. The image delta is the feature's code; not measured here (the release image build measures it). - The worker runs the same binary, so it has the same version as the server.
- Preparing a spawn makes the server process not dumpable, as it already is once discovery's workers start: its core dumps and a debugger's attach are refused.
- Two previews run at once at most (the rest get 503
unavailableuntil one ends), so the memory of uploads and workers is bounded (review of T24.18, LOW 4).
Builds on ADR-913 ADR-933 ADR-934 ADR-988
Referenced by ADR-988
Link to this decision · In the specification
ADR-940 Importing a Pi-hole export: a plan, applied as one configuration change, admins onlyT24.18 puts the Pi-hole import on the admin page: upload, preview, apply.
Context
T24.18 puts the Pi-hole import on the admin page: upload, preview, apply. An import replaces configuration in bulk, and the API writes configuration one entry at a time (ADR-069). ADR-040 makes the config files' names read-only through the API. ADR-914 says bulk changes are admin changes with a typed confirmation and an audit record.
Decision
- Who. Admins only. An agent's token is refused by the auth layer (403
forbidden) and by the handler (agent_not_allowed); operators and viewers get 403. spec/13 §3 lists the import among the operations no agent may make. - Preview. Changes nothing. It returns a plan: a
planId, what would be added, changed or skipped (each with its reason and where it points: a URL or file, the servers, the members, the record values), the notes, and the comparison when asked (ADR-941). A plan is held in this node's memory for ten minutes (at most eight are kept), like an agent's plan (AGT-007). A restart discards them. A plan's ID is 32 random bytes, and only the admin who previewed it may apply or discard it; another admin gets 404. - Retries. The three routes take
Idempotency-Keyas the configuration writes do (AGT-003): a retried apply or discard gets the first answer, a preview is keyed on a hash of its body and options, and a successful answer is kept under the admin's key for a day. - Apply. The plan's writes go in one transaction (
put_managed_batch), and the version moves once. Before the write, the merged configuration (the files plus the stored entries plus the plan) must load; the configuration version must still be the preview's, or the answer is 409 and the preview is run again. The node then reloads. If the change is stored but the reload fails, the audit record is written anyway, withapplied: false, and the answer is 500 saying the change was saved, so the audit log never misses a change that happened. - Names. An entry of a name that exists is replaced (
change), as an API override replaces the file's (ADR-069); the file's entry comes back when the override is deleted. A name the config files define isskipped for local names, conditional forwards and devices, because ADR-040 keeps those read-only through the API (the merge ignores a stored device of a name the files use, so writing one would store a dead row). A file list (afile://adlist in the export) is flagged in the notes, since it reads a file on this machine. A stored rate limit replaces the file's[ratelimit]section as a whole, and the item says so. - The default groups. Pi-hole's lists join the default group's lists, and Pi-hole's upstreams join the default upstream group's members. Their other settings stay. An omitted list means every list (
listsomitted), so the merge keeps it omitted. - Conditional forwards. Each Pi-hole route is a forward entry with the servers of its group's upstreams. The
pihole-forward-Nupstreams and groups aren't written. A suffix is routed once: when a v5rev-serverand a dnsmasqserver=/domain/name the same domain, the first is kept and the conflict is noted. - DNSSEC. The mode is a file setting, not an API one, so it's reported as skipped with the line to add to the file.
- Audit. Applying is audited as
import.piholewith the counts and the configuration version. A preview isn't written to the audit log. - The UI. The apply needs the word
IMPORTtyped in. The page is a Settings tab that admins alone see. Its comparison takes the Pi-hole address, this node's address (default127.0.0.1:53) and extra sample names.
Alternatives rejected
- Writing the file. The API can't write the configuration files (ADR-040), and the CLI already writes them for a person who reads the output.
- One request per entry. A failure in the middle would leave half an import in place, and each write re-checks the whole configuration.
- Keeping plans in the state database. An import is short-lived, like an agent's plan; a restart discards it, which is the safe side.
Consequences
- Undoing an import means deleting the entries it added. The audit record lists the counts; the preview lists the names.
- A
changereplaces an entry of the same name: the import page says so before the apply. - The plan's bodies are the entries the store keeps: a credential isn't part of a Pi-hole import, so no secret passes through it.
Requirements AGT-003 AGT-007
Builds on ADR-040 ADR-069 ADR-914 ADR-941
Link to this decision · In the specification
ADR-941 The Pi-hole import's comparison: the sample, the resolver it asks, and when it stopsT24.6 asks for wrendns import pihole --compare, which resolves a sample through the Pi-hole and WrenDNS and reports the differences.
Context
T24.6 asks for wrendns import pihole --compare, which resolves a sample through the Pi-hole and WrenDNS and reports the differences. The task text doesn't say which names, which WrenDNS, or what happens when a server doesn't answer.
Decision
- Sample. The imported local names and CNAME names, up to 20 exact deny entries, and the names given with
--sample. A and AAAA are asked of both servers. At most 200 names. - The WrenDNS side. The node's own resolver at
--wrendns(127.0.0.1:53by default). It answers from its running configuration, so before the import is applied the report shows what the node answers now, and the help says so. - Transport. Plain UDP, two seconds a query, no retries. A server that doesn't answer five queries in a row is named in the report and isn't asked again; when neither answers, the comparison stops.
- What counts as a difference. The rcode, or the sorted addresses and names of the answer. TTLs are ignored.
- Read-only. It sends standard queries and nothing else. The import page's comparison (T24.18) is the same function.
- Budget. The whole comparison stops after 60 seconds, and the report says how many names it covered. A server that answers every other query never reaches the five-in-a-row limit, so the budget is what bounds the time. The addresses are the admin's to give (the admin already holds the configuration), so the UDP goes wherever the admin names.
Alternatives rejected
- Comparing the configuration offline. It wouldn't show what a client gets over DNS (rewrites, blocking, the cache and the special names all act in the resolver).
- TCP or DoT to the Pi-hole. What the household's devices get is the UDP answer; the comparison should match that.
- Retrying silent servers. A wrong address would then cost minutes; five silent queries say it clearly.
Consequences
- A comparison in the UI asks the WrenDNS address the admin gives, by default the node that serves the page. In a cluster, it's that node's resolver unless another address is given.
- The sample is a sample: a difference in a name that isn't in it goes unreported.
Referenced by ADR-940
Link to this decision · In the specification
ADR-942 UniFi offline clients on the fork's router model: offline_days 0 keeps the reservationsThe upstream merge brought T8.2's offline clients (ADR-166): the console's client history and the configured clients, named by their last address, for offline_days (30 by default, 0 for connected clients only).
Context
The upstream merge brought T8.2's offline clients (ADR-166): the console's client history and the configured clients, named by their last address, for offline_days (30 by default, 0 for connected clients only). The fork had already made a DHCP reservation (T22.2, ADR-902) name its device while it is offline, whatever the history says. Both can't hold at offline_days = 0. Decision (proposed; the conservative reading of both):
- The history and the configured clients (
rest/user) are read only whileoffline_days> 0. A dated row names a device only inside the window; an undated row can't be judged against it, so it is kept (unifi_knownkeeps it), as in ADR-166. The configured clients are read like the history rows: an alias without a reservation names its offline device too. The fork's earlier worry (a configured client's last address may belong to someone else by now) applies equally to the history rows, which are kept; the window andoffline_daysare the control for both. - A reservation names its device at any
offline_days, including 0. It is the router's configuration, not a history, and the fork's T22.2 behaviour is kept. The Routers form's help topic (router-offline-clients) says so. - Offline devices stay out of "seen" (ADR-166), and the fork's reservations still count as seen (the T22.2 decision); a reservation is therefore not an offline device here.
- An offline client is not a current answer anywhere else either (sync review, 2026-11-17): it gives no address binding to discovery (ADR-910, ADR-924), publishes no DNS name, isn't counted in a network's devices, and is left out of
/dhcp/leases, which has no offline marker yet (an owner decision, Open in spec/10 T8.2). It still names the device in the query log.
Consequences
offline_days = 0 means "no history names", not "no offline names". The owner may prefer the stricter reading (0 also drops reservations); that is a change to unifi_reserved in routers.rs, one line, and a test. Owner decision (2026-11-17): /dhcp/leases and the UI list offline clients, marked offline (as upstream does); they stay out of DNS names, discovery's address bindings and a network's device count, as above. Built 2026-11-17 (spec/10 T8.2): DhcpLease.offline is always serialized; the offline row's dnsName is absent.
Builds on ADR-166 ADR-902 ADR-910 ADR-924
Referenced by ADR-945
Link to this decision · In the specification
ADR-943 Svelte attribute quantifiers: {n} in a quoted attribute is written as a JS expression, and a guard keeps it that wayUpstream issue #64, "2FA can't be enabled".
Context
Upstream issue #64, "2FA can't be enabled". Svelte 5 reads {6} inside a quoted attribute value as an expression, so pattern="[0-9]{6}" reached the browser as [0-9]6 and no six-digit code matched. The TOTP enrolment (Settings) and the sign-in code (Login) both had the bug.
Decision
- Every such attribute in
ui/srcis written aspattern={"[0-9]{6}"}, a string expression, so the braces reach the DOM unchanged. ui/scripts/check-quantifiers.mjsruns first innpm run check. It fails when any quoted attribute in a.sveltefile, double- or single-quoted and across lines, contains{digits}or{digits,digits}. It is a source check, so it catches the pattern before a build.- The Playwright suite enrols TOTP with a real RFC 6238 code and signs in with one, so a regression that breaks the pattern also fails the suite.
Consequences
A new quoted attribute with a quantifier fails npm run check until it is written as an expression.
Link to this decision · In the specification
ADR-944 Break-glass sign-in defaults to loopback, and a proxied request is never break-glassUpstream issue #63.
Context
Upstream issue #63. The default [auth.oidc] allowed_admin_networks was the private networks plus loopback, so with disable_local_login = true any LAN device could try a password. The owner asked for a safer default. Two things make a loopback-only default need care: a reverse proxy on the same host is not in [api] trusted_proxies, so every proxied client arrives as 127.0.0.1 and would pass; and with Docker port publishing the peer is the bridge gateway, so an admin on the host is locked out of break-glass.
Decision
allowed_admin_networksis optional. Absent means loopback only (127.0.0.0/8,::1). Set means exactly that list, and[]allows nothing. The serde default distinguishes absent from set, so an explicit list is never overwritten by the default.- A request that carries
X-Forwarded-For,X-Forwarded-Host,X-Forwarded-Proto,X-Forwarded-Port,X-Real-IPorForwardedfrom a peer that is not a trusted proxy is never break-glass while the loopback default applies. Its address is the proxy's, so it can't be checked. This applies to form sign-in, HTTP Basic and the/auth/statuslocalLoginflag. An explicit list skips this rule, because the operator chose those networks. - In-process MCP calls (
OnBehalfOf) keep the address they were made with and are checked against the same networks. - Startup logs a WARN when
disable_local_loginis on andallowed_admin_networksis unset. It names the proxy and Docker cases. A trusted proxy in[api] trusted_proxiesnames the real client and is checked normally. - Recovery: set
allowed_admin_networks(for Docker, the bridge gateway's address) and restart.docker execgives no password sign-in: the image has no browser or curl, andwrendns ctluses a token. Settings are file-only and need a restart, so no API can widen break-glass remotely. - Migration: no file is rewritten. Operators who used the old private-network default and
disable_local_loginmust setallowed_admin_networksexplicitly; the startup WARN anddocs/running.mdsay so.
Consequences
Break-glass from the LAN now needs one config line. Docker and proxy setups need a documented path (the bridge gateway in allowed_admin_networks, or the proxy listed). A proxy on the host that isn't listed locks its clients out of break-glass rather than letting them in. This is the conservative reading of the owner's request, and the owner can change the default by one line in schema.rs if they prefer private networks.
Referenced by ADR-1047 ADR-1067 ADR-961 ADR-987
Link to this decision · In the specification
ADR-945 The leases list shows offline clients, marked offlineADR-942 keeps an offline UniFi client out of DNS names, discovery's bindings and a network's device count, and left /dhcp/leases without it because the API had no marker.
Context
ADR-942 keeps an offline UniFi client out of DNS names, discovery's bindings and a network's device count, and left /dhcp/leases without it because the API had no marker. The owner chose to show it.
Decision
GET /api/v1/dhcp/leases lists every router lease, including the offline clients, each with offline (always present: true for an offline client, false for connected and reserved rows). An offline row has no dnsName. The listing is the only thing that changes: device_dns, discovery's lease_observations and networks()'s device count still skip offline rows. The UI marks them with an "offline" badge (Clients → Discovered, Networks → a network's devices).
Alternatives rejected
leaving them out (the owner's earlier reading, which hid a device the admin may want to see); a separate endpoint for offline clients (a second list the admin would have to join by hand).
Consequences
a client that gives an offline row has no last-seen time, since the lease carries only its end time. Adding one needs the router's history timestamp kept on the lease (later work).
Builds on ADR-942
Link to this decision · In the specification
ADR-946 Federated reads run off the runtime workers: block_in_place under the blocking helperupstream #7.
Context
upstream #7. call_one and gather in crates/wrendns/src/federated.rs run a plain thread that blocks on the runtime. Called from a worker, the worker is held while the cluster stream's writer and reader tasks need workers to finish the call, so two concurrent reads to a peer that doesn't answer wedged a two-worker runtime. Several async handlers called a federated read directly on a worker.
Decision
- The wait.
call_oneandgatherrun their future throughrun_off_the_worker: on a multi-thread runtime,block_oninsideblock_in_place, which hands the worker's queued tasks to another thread first, with no extra thread. A current-thread runtime has no other thread to take them, so its future runs on a scoped thread.block_in_placeis a no-op off a runtime, so a blocking-pool caller takes the multi-thread path too. - The handlers. A federated read in an async handler runs through
blocking(). TheBackendmethods that can reachcall_oneorgatherareannotations,anomalies,blocking_pause,blocking_resume,blocking_state,cache_entries,cache_flush,cache_lookup,cache_stats,client_rhythm,clients,config_entries,config_version,exemplars,health,heatmap_network,identities,identity,kubernetes_workloads,latency,lists,list_hits,new_devices,overblocking,probes,queries,secrets_status,shadow_lists,timeseries,top,top_clients_rolling,top_in_group,top_rangeandupstream_checks. Every async caller of one of them now usesblocking()orspawn_blocking. The ones that didn't wereclients,config_entries, the ETag reads (local_names,forwards,rules, a config write's response), and a config write's group check, which reads the devices for a group-restricted agent only. The otherBackendmethods read local state and stay direct.slo_parts, aFederatedhelper that callsgatherdirectly, has one async caller, the attribution handler, which runs it throughblocking(). - No worker floor. The optional floor of runtime workers is not added. The Pi-profile RSS can't be measured here, and the fix doesn't depend on the count: the regression test passes on two workers.
Alternatives rejected
- Refusing federated reads on a worker in debug builds. It catches the mistake in tests, but a release build would still wedge.
- Making the
Backendmethods async. Every method and its local store would need async plumbing for no gain:blocking()is the existing pattern for backend reads.
Consequences
a federated read on a worker costs a hand-off rather than wedging the node. A new async caller of a federated read must use blocking(), and a new Backend method that reaches call_one or gather joins the list above.
Link to this decision · In the specification
ADR-947 A promotion reaches every replica in the heartbeats; a key share repeats every 30 sthe three-node run (deploy/cluster3, T21.5) killed the primary.
Context
the three-node run (deploy/cluster3, T21.5) killed the primary. The replica elected in its place became primary, and the other replica followed the dead old primary (its configuration fetch went to primary:8443) and missed every later version. Two causes in wrendns-cluster:
- a member's
primaryflag came only from its Hello, at connect time. A replica that connected before the election kept the old view, andprimary_urlsleft the new primary's URL out as a replica's; - the primary sent its key share once per stream. A peer that refused it (the flag was stale, so the sender wasn't "the primary" yet) never got another, so it could not be promoted later.
Decision
- The heartbeat carries the sender's primary flag as an optional field (tag 39). A sender sets it at every heartbeat, and the receiver updates the member's flag. An older node sends no flag, and the flag a peer holds stays. Both directions are compatible without a protocol bump (CLU-010).
- The primary sends its key share to an eligible peer again every 30 s (
KEY_SHARE_RESEND), unchanged. The acceptance check is unchanged: the sender must be the primary in the receiver's view, at the same epoch or a newer one.
Alternatives rejected
- A protocol version bump. The field is optional both ways, so a bump would only force a mixed cluster to upgrade together.
- Deriving the primary from the epoch. A node's epoch alone doesn't say whether it holds the role now, and a former primary keeps the epoch it had.
- Acknowledging key shares. A wire change for a refusal that a resend already covers.
Consequences
a primary's heartbeat grows by two bytes, and an eligible peer gets about 2 KiB every 30 s. A replica takes a new primary from the next heartbeat after the promotion. Tests: clu_005_a_promotion_reaches_a_replica_in_the_heartbeats, clu_005_a_key_share_is_sent_again_after_its_interval, clu_005_the_heartbeat_primary_flag_is_optional_both_ways.
Addendum (T21.5 review, 2026-11-17). The three-node run also showed how an election starts. A node's election state is made when automatic failover turns on, and again when the voter set changes. Such a node had no lease to go by (none was granted yet), so its first try came at once: a replica stood 70 ms after the third voter joined and deposed a primary that had not renewed yet. A node that isn't the primary now waits one lease period (LEASE_MS, 15 s) before its first try (Elector::defer_first_try). The primary doesn't wait: it stands at once and takes its lease. Safety is unchanged (a voter still refuses a newer epoch while a lease it granted runs); the first election after a start is later, by up to 15 s. Tests: clu_005_d_a_new_candidate_waits_a_lease_before_its_first_try. The primary's key-share send is one decision (key_share_send: a changed frame at once, the same frame every 30 s), tested by clu_005_c_the_key_share_is_sent_on_change_and_on_the_interval. A repeat of the next CA key that the trust doesn't include yet doesn't rewrite ca-pending.key when the file already holds that key (clu_005_b_a_pending_ca_key_is_written_once).
Requirements CLU-010
Link to this decision · In the specification
ADR-948 The [discovery] first write, and members that are stopped or run a dev buildADR-928's title says "the first write waits for N−1 members".
Context
ADR-928's title says "the first write waits for N−1 members". Its decision says the first write is refused with 409 members_too_old while a member runs a version older than DISCOVERY_SINCE (0.8.0), or one that can't be read. The three-node run checked both readings. With all three up, the first write passes when the replicas report 0.8.0. With replica-b stopped, the real first write also passes: the gate reads the version the cluster recorded for it, and a stopped member is neither older nor unreadable. A cluster of dev builds does refuse the first write, since a peer's dev is unreadable to the gate, and the refusal names both replicas. The run's image therefore stamps the release version (0.8.0), the way CI stamps a release build.
Decision (proposed): keep the gate as ADR-928's decision states it: members are judged by the version the cluster recorded for them, not by whether they are up. The test follows that. The title of ADR-928 says "waits", which this doesn't do.
Open for the owner
- Should a stopped member block the first write until it is back (the title's reading)? That is a new rule: a member that's down would hold up a setting, and the first write has no later retry.
- Should a
devbuild report a readable version to its peers, so a dev cluster can use[discovery]? Today it can't, and the refusal is correct for the decision as written.
Consequences
no code change until the owner decides. The test pins the current behaviour (deploy/cluster3/e2e.sh, check e).
Owner decision (2026-11-17):
- A stopped member doesn't block the first write. Members are judged by the version the cluster recorded for them, as above. The title of ADR-928 is read as its decision.
- A build without a release stamp reports the crate version with a
-devsuffix (for example0.8.0-dev) instead ofdev, and peers and the gate read it as that version. A dev cluster can then use[discovery]without a release stamp. This is T21.6.
Addendum (T21.5 review, 2026-11-17). A [discovery] the primary sets with a value that isn't the default was refused by every replica whose own section was at its defaults. The section is left out of a node's serialization at its defaults (CLU-010), so the configuration merge didn't know the key and refused the whole version ("the primary sent a setting this version doesn't know"). The merge now always has the discovery key: at its default when the primary doesn't send one (so a cleared section resets the replicas, as the other shared sections do), and the primary's value when it does. Test: clu_010_a_discovery_section_is_shared_both_ways (wrendns-config). Check (e) of the three-node run writes worker_memory_mib = 48 and reads it back on replica-b, which is what found it.
Requirements CLU-010
Builds on ADR-928
Link to this decision · In the specification
No decision matches. Try fewer words, or another status or area.