From 90be37c0c8d62876a08ee220d947fabd40b0723d Mon Sep 17 00:00:00 2001 From: iris Date: Sat, 15 Aug 2026 12:19:02 +0200 Subject: [PATCH] docs(swarm): fix stale hivectl peer-config claim, verified against hivectl/src/wg.rs --- docs/swarm/ca.md | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/docs/swarm/ca.md b/docs/swarm/ca.md index 5db8d4e8..45b2c39c 100644 --- a/docs/swarm/ca.md +++ b/docs/swarm/ca.md @@ -76,26 +76,29 @@ sign leaves, and the chain stops there. ## What to hand a peer -`hivectl peer-config` prints the `cp` line. The file is -`/trust-bundle.pem` — the hive CA plus the swarm root — -**not `ca.pem`**. +`hivectl peer-config` prints the `services.hyperhive.swarm.hives.""` +block a peer operator pastes into their own config. When this hive's +gateway serves a self-signed leaf under the hierarchy (detected by the +presence of `/trust-bundle.pem`), it also prints a one-time +`scp` line installing the **swarm root** — +`/root.pem`, not this hive's own CA — on the peer's +host: -The distinction is load-bearing rather than cosmetic: once a hive CA is -an intermediate, it is no longer something a verifier can build a chain -*to*. OpenSSL will not terminate a chain at a trusted non-self-signed -certificate without `-partial_chain`, so handing a peer the bare -intermediate produces a verification failure that reads like a bad cert -rather than like a missing anchor. The bundle carries both, so the same -file works whichever mode issued it. +``` +scp /var/lib/swarm-ca/root.pem :/var/lib/swarm-ca/root.pem +``` -On a hive that predates the swarm root the bundle is just that hive's -self-signed CA, so the recipe does not change. +That is the point of the hierarchy: the root is installed **once per +swarm host**, not once per peer, so a hive joining later needs no edit on +the hives already running. A hive whose cert already chains to a public +CA has nothing to install — `peer-config` says so instead. -⚠️ Consumers must read `trust-bundle.pem`, never `ca.pem` directly. A -consumer that reads `ca.pem` works fine on a hive that has always been -self-signed and breaks the moment that hive adopts the hierarchy — so -the failure is invisible on the deployment you are most likely to test -on. +Handing a peer this hive's own `ca.pem` would not work even as a +one-off: once a hive CA is an intermediate under the swarm root, it is +no longer something a verifier can build a chain *to* — OpenSSL will not +terminate a chain at a trusted non-self-signed certificate without +`-partial_chain`. That is why the tool distributes the root, not a +per-hive file. ## Adopting the hierarchy on an existing hive