diff --git a/docs/snapshot-store.md b/docs/snapshot-store.md index 8bacdd21..74003730 100644 --- a/docs/snapshot-store.md +++ b/docs/snapshot-store.md @@ -41,6 +41,41 @@ Note that the mesh is gated on `swarm.wireguard.enable`, **not** on `c0re.enable` --- a store host runs no hive and would otherwise get no `wg-hive` interface at all. +## Pointing a hive at it + +The block above configures the host that *receives*. Every hive that +*pushes* separately needs to be told where the store is: + +```nix +services.hyperhive.swarm.snapshotStore = { + address = "10.100.0.9"; # the store's mesh address, no prefix + port = 51821; # optional; must match the receiver's port +}; +``` + +Two deliberate asymmetries in that pair, both easy to misread as +inconsistency: + +- **`address` has no default.** It is a deployment fact a pushing hive + cannot derive, and a wrong guess means streaming an agent's state at + whatever happens to answer. Unset, a push fails naming this option. +- **`port` does default** (`51821`), because it is a convention both + ends read from the same option docs --- a default there is + coordination, not a guess. + +Note the option lives under `swarm.*` while the receiving host's lives +under `services.hyperhive.snapshotStore`. That is the distinction the +two namespaces carry throughout: `swarm.*` describes *the swarm* as seen +from this host, and a bare `services.hyperhive.` describes *a +role this host performs*. A store host sets both --- one to run the +receiver, one only if it also runs a hive that pushes. + +With it set, `hivectl agent subvol snapshot push