diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 84fbabcc..cd0bdacb 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -103,16 +103,17 @@ bao token create -policy=swarm-bootstrap -ttl=24h -orphan -display-name=swarm-bo ``` Put the token's value at `services.hyperhive.deploy.bao.bootstrapTokenFile` -(all-local names that path for you), then rebuild. A one-shot unit inside the -store's container reads it, writes the `swarm-controller` policy, enables the -cert auth method, and creates the `swarm-controller` role that attaches the two. +(all-local names that path for you), then rebuild. A one-shot unit **on the +host** reads it, writes the `swarm-controller` policy, enables the cert auth +method, and creates the `swarm-controller` role that attaches the two. It runs +there because every API listener demands a client certificate, and the host is +the side that has one. -⚠️ **This has only run once, and it didn't go all the way through.** The -first real provision against a live store returned 403, so -treat the block above as derived, then only partly tested — not proven: the -grants still come from `-output-policy`, not from a swarm that came up on them. -What that 403 does _not_ tell you is whether the login or the write was -refused — `bao read auth/cert/certs/swarm-controller` separates the two. +⚠️ **The grants above are derived, not proven.** They come from +`-output-policy`, not from a swarm that came up on them. The unit has run twice +against a live store and failed both times for reasons of its own — it could +not reach the store from where it then ran — so neither run exercised these +grants at all. **Delete the file only once `bao read auth/cert/certs/swarm-controller` returns the role.** The unit skips when the token is absent, so a host that has finished