vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(swarm): fix stale hivectl peer-config claim, verified against hivectl/src/wg.rs

Browse source
This commit is contained in:
iris 2026-08-15 12:19:02 +02:00 • committed by mara
commit 90be37c0c8
1 changed files with 23 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

37
docs/swarm/ca.md
View file

@ -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
`<tls.stateDir>/trust-bundle.pem` — the hive CA plus the swarm root —
**not `ca.pem`**.
`hivectl peer-config` prints the `services.hyperhive.swarm.hives."<name>"`
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 `<tls.stateDir>/trust-bundle.pem`), it also prints a one-time
`scp` line installing the **swarm root** —
`<swarm.ca.stateDir>/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 <peer-host>:/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