Watch
0
0
Fork
You've already forked hyperhive
0

document the controller tcp listener and its two leaves

This commit is contained in:
atlas 2026-11-15 16:15:29 +01:00 • committed by mara
commit cd786ef401

View file

@ -206,6 +206,36 @@ and the next day's run tries again: about fifteen tries before the leaf
lapses. `systemctl
list-timers swarm-services-cert-renew` shows the next run.
## The controller's TCP listener has two leaves of its own
`swarm.controller.tcp.enable` adds a TLS listener to the swarm controller (default off). The
controller checks nobody per request, so the listener finishes a handshake for one client only:
the gateway. Both ends hold a leaf from the store's `pki` mount, each through a role of its own on
the same mount and the same root:
- **Server leaf.** The `swarm-controller-tls` role issues for `swarm.controller.tcp.domain` alone,
`serverAuth` only. `swarm-controller-tls.service` on the controller's host requests it under the
controller's own store leaf, whose policy gains that one issue path.
- **Gateway client leaf.** The `swarm-controller-gateway-client` role issues for
`gateway-client.<swarm.domain>` alone, `clientAuth` only. `swarm-controller-gateway-client.service`
on the host that runs the controller requests it under the services-issuer identity, whose policy
gains that one issue path.
The controller accepts a client certificate that chains to the services root, carries the
`clientAuth` usage and names `gateway-client.<swarm.domain>`. The swarm-services leaf chains to
the same root but is `serverAuth` only and names other hosts, so the listener refuses it at the
handshake. Nginx verifies the controller's server leaf against the trust bundle, by `domain`.
Every host that holds the services-issuer identity can obtain the gateway client leaf, which is
every gateway host. The controller trusts exactly that identity: a gateway of this swarm.
Set `swarm.controller.tcp.enable` and `swarm.controller.tcp.domain` identically on every host. The
store's host writes both roles from them. A store host that leaves the option off has no role, and
the issuing unit fails with the store's refusal naming it.
The listener reads the services root once at start. Replacing the root (about 30 years out) needs a
controller restart as well as new leaves.
## Constraints on the material
No CA private key exists on any hive. The `pki` root's key stays inside the