From 44164d1a891e01ed527ed02bb6cd4789bedf6036 Mon Sep 17 00:00:00 2001 From: atlas Date: Tue, 11 Aug 2026 18:26:12 +0200 Subject: [PATCH] docs(swarm): what the uncovered-service-name warning means MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Names the two ways out (install the sub-CA, or pin back under the hive domain) and says why it is a warning rather than an assertion — the module can see what it issues, not what the operator installed. --- docs/swarm/ca.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/swarm/ca.md b/docs/swarm/ca.md index 5f6ce360..537087f9 100644 --- a/docs/swarm/ca.md +++ b/docs/swarm/ca.md @@ -37,6 +37,27 @@ Moving the swarm CA onto its own host is then a matter of moving `services.hyperhive.swarm.ca.stateDir` and leaving `autoConfigure` off — there is no second code path to switch to. +### The warning about uncovered service names + +The swarm's service names (`swarm.forge.domain`, +`swarm.matrix.gatewayHost`, `swarm.authelia.domain`) default to +siblings of the hive domain — `forge.`, not +`forge.`. The hive CA's leaf is a **single-label** wildcard +over the hive's own domain, so it cannot cover them; only the +swarm-services leaf can, and this host signs that one only under +`autoConfigure`. A hive with neither serves the hive leaf on those names +and every client sees a name mismatch. + +So `hive-tls` emits an eval-time **warning** naming the uncovered names. +It is deliberately not an assertion: this module can see what *it* is +able to issue, but not an operator-installed sub-CA in +`swarm.ca.stateDir`, an external ACME setup, or a certificate delivered +by any other means. If you have arranged one, the warning is expected +and can be ignored. Otherwise either install the sub-CA, or pin the +names back under the hive domain — a supported migration, since the +sub-CA is constrained to the *configured* names and the swarm root +carries no name constraints at all. + ## Constraints on the material The root's private key never reaches the nix store: the store is