From 0d25c0c9e6ed3a4cce07fd5e374669b22b3c9981 Mon Sep 17 00:00:00 2001 From: atlas Date: Fri, 11 Sep 2026 14:06:11 +0200 Subject: [PATCH] docs/swarm: a hive entry's domain defaults, as the module says and the page already said once MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md described `swarm.hives..domain` two ways, 100 lines apart. § *Hive identity config* says it defaults to `.` and shows a names-only directory; § *The swarm's hive directory* called it "required per entry and deliberately undefaulted" and wrote a domain into every entry. The module sides with the first (`nix/host-modules/swarm.nix:125`): default = if swarmCfg.domain == null then "${name}.invalid" else "${name}.${swarmCfg.domain}"; and `:110` answers the stale paragraph's objection directly — the default is "a derivation from two values an operator had to state explicitly (both are required), not a guess". Ordinary drift, two hours wide: `433b2940` wrote "deliberately undefaulted" at 20:44 on 08-05, `3b6576fa` added the default at 22:43 the same evening under the message "a hive's domain comes out of the swarm directory". Both mine. The example now shows what the convention actually looks like — names only, plus one off-convention hive carrying the override, which is the case the option exists for. Closes #4220. --- docs/swarm/README.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/swarm/README.md b/docs/swarm/README.md index 4c6a4b07..a012bb04 100644 --- a/docs/swarm/README.md +++ b/docs/swarm/README.md @@ -114,8 +114,9 @@ wire a swarm service name into: [`ui.md`](ui.md). ```nix services.hyperhive.swarm.hives = { - pr1ma = { domain = "pr1ma.example.com"; }; # this host, per hiveName - lab = { domain = "lab.example.com"; }; # a second hive in the swarm + pr1ma = { }; # this host, per hiveName + lab = { }; # a second hive in the swarm + edge = { domain = "edge.elsewhere.example"; }; # addressed off-convention }; ``` @@ -130,9 +131,12 @@ hive. That assertion is load-bearing rather than pedantic — "my peers" is derived as _everything that isn't me_, so a directory that doesn't contain you derives every hive as a peer and you peer with yourself. -`domain` is required per entry and deliberately undefaulted: it's -conventionally `.`, but a wrong domain that -evaluates cleanly points at a real machine that isn't the one you meant. +`domain` defaults to `.`, the convention every hive +follows, so a conventional directory is names only. The default is a +derivation from two values the operator already had to state — the swarm's +domain and the entry's own name — rather than a guess, which is what makes +it safe here when a guessed hostname wouldn't be. Set it only for a hive +addressed by something else. > **No per-hive CA field exists, and no per-hive cert pinning.** Trust > inside a swarm comes from the swarm root ([`ca.md`](ca.md)): every