diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/access.md | 10 | ||||
| -rw-r--r-- | docs/example.toml | 6 | ||||
| -rw-r--r-- | docs/lifecycle.md | 2 | ||||
| -rw-r--r-- | docs/openapi.yaml | 4 |
4 files changed, 21 insertions, 1 deletions
diff --git a/docs/access.md b/docs/access.md index c5365b7..782724a 100644 --- a/docs/access.md +++ b/docs/access.md @@ -318,6 +318,16 @@ policy's own change and everything after it, as every other node does. While nei its document nor what it receives holds a policy, it judges only that a root is the epoch's, and nothing costs more than applying the changes. +An epoch's root is pinned. A remake's is its epoch's ID, the hash of its snapshot. The +first epoch's is its genesis change, which its genesis node logs (`The swarm's root`) +and `GET /admin/epochs` shows (`root`). Every node names its root in its handshakes: a +node whose document starts from another root of the same epoch refuses the handshake +(another history under the swarm's ID: a forged root, or a genesis started again). +A node joining with an empty document takes as its root only the one it was given +(`--genesis-root`), or else the one its peers name, and none while they name different +ones. So one peer hands a joiner another root only if it is all the joiner hears, or +never, with `--genesis-root`. + What it doesn't do yet: * **Prove the user.** A change is its node's (with signatures required, proven) and its diff --git a/docs/example.toml b/docs/example.toml index d5af848..70d65b2 100644 --- a/docs/example.toml +++ b/docs/example.toml @@ -105,6 +105,12 @@ htpasswd = "/etc/continuum/htpasswd" # together at most. # key-logins-per-user = 100 +# The hash of the swarm's genesis change (hex, as its genesis node logs it and GET +# /admin/epochs shows it): joining with an empty document, the only root this node +# takes. Without, the one its peers name, none while they name different ones +# (docs/access.md). +# genesis-root = "…" + # SSH keys, as authorized_keys lines (ssh-ed25519 <base64> [comment]), whose signature # on a strict remake's manifest this node takes: the values kept when the swarm turns # strict (docs/access.md). Without, it votes for no strict remake; a majority of the diff --git a/docs/lifecycle.md b/docs/lifecycle.md index 9fe9442..829e425 100644 --- a/docs/lifecycle.md +++ b/docs/lifecycle.md @@ -62,7 +62,7 @@ Then the node is either ready at once or joining: | Start | Without a remembered swarm | With one (state file) | |---|---|---| -| `--genesis` | a new swarm, ready at once | that swarm again, empty; nodes of it still running merge with this one | +| `--genesis` | a new swarm, ready at once | that swarm again, empty, from a new root, which nodes of it still running refuse (to join them, give seeds) | | document file holding a document | ready at once, on the document's swarm and epoch | the same; the two must name the same swarm | | `--recover-from` | ready at once, on the backup's swarm and epoch | the same; the two must name the same swarm | | seeds, or none | joining through the seeds | joining that swarm, through the seeds and the remembered members | diff --git a/docs/openapi.yaml b/docs/openapi.yaml index bb017f0..4a49d2b 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -3100,6 +3100,10 @@ components: properties: current: $ref: '#/components/schemas/Epoch' + root: + type: string + nullable: true + description: The hash of the epoch's root (hex), where the document holds it - for the first epoch, its genesis change, which a joining node may be given (`--genesis-root`). archived: type: array items: |