diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 2d77f9fa..84fbabcc 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -51,22 +51,23 @@ sealed, so the container is up and the port responds while every read times out — the failure looks like a hang, not like a store that was never initialised. Do this before you point anything at it. -Run this **inside the store's container** — `nixos-container root-login -swarm-bao`. The store's TLS certificate is issued for its DNS name and carries -no IP SAN, and that name resolves to the bridge rather than to the container -from in there, so neither `127.0.0.1` nor the name works on its own. Verify the -name while connecting on loopback: +Run this **on the host**. The `bao` there is a wrapper carrying this store's +address, its CA, and the host's client certificate already, so nothing needs +exporting: ```bash -export BAO_ADDR=https://127.0.0.1:8200 -export BAO_TLS_SERVER_NAME=bao. # `deploy.bao.domain`, the CN the cert carries - -bao operator init # keep the keys it prints and the root token OFF this host +sudo bao operator init # keep the keys it prints and the root token OFF this host ``` -From the **host** instead, `BAO_ADDR=https://bao.:8200` reaches -the same store and needs no SNI override — that's the address every unit in -the tree builds, and what `swarm-controller` connects to. +`sudo` because the client certificate and key sit under +`/var/lib/swarm-bao-pki`, which is mode `0700`. + +Inside the store's container (`nixos-container root-login swarm-bao`) the same +command needs two extra pieces, because the certificate carries no IP SAN and +its DNS name resolves to the bridge from in there: export +`BAO_ADDR=https://127.0.0.1:8200` alongside `BAO_TLS_SERVER_NAME=bao.` to verify the name while connecting on loopback. The host is the +shorter path. While you still hold that root token, mint the one credential the swarm needs to grant itself anything. Cert auth answers a _role_, so nothing can @@ -113,9 +114,12 @@ 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. -**Delete the file once that has run.** The unit skips when it's absent, so a -host that has finished bootstrapping stops carrying the credential — and the -TTL above means a forgotten one expires rather than lingering. +**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 +bootstrapping stops carrying the credential — but deleting it before the role +exists leaves the unit skipping forever with nothing to show for it, and looks +exactly like a store that was never bootstrapped. The TTL above means a +forgotten one expires rather than lingering. Whether anything more is needed depends on `services.hyperhive.deploy.bao.seal`: