aboutsummaryrefslogtreecommitdiffstats
path: root/docs/trust.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-18 12:48:29 +0000
committertv <tv@krebsco.de>2026-11-18 13:59:42 +0100
commitd130c0612b4c63f2d30da65ebcc231018c1f2606 (patch)
tree8700f2d53351cbbecbe772ea7701bf6240d5210c /docs/trust.md
parent0bfe07af92a775b0e896e0fc5a989a1d9b65f7b3 (diff)
docs: references to another document's section linked to it
Where a document names a section of another after linking to it ("([`store.md`](store.md), Pinned checkpoints)"), the name links to that section too, by the id both GitHub and cgit's about filter give its heading; paragraphs that grew past the width are wrapped anew, links and code kept on one line each.
Diffstat (limited to 'docs/trust.md')
-rw-r--r--docs/trust.md49
1 files changed, 26 insertions, 23 deletions
diff --git a/docs/trust.md b/docs/trust.md
index 72a238d..fda0703 100644
--- a/docs/trust.md
+++ b/docs/trust.md
@@ -36,19 +36,21 @@ it creates is).
**The HTTP API.** Every endpoint but the API description, the login page (`/login`) and
logging in by key needs a user from `--htpasswd`, one a reverse proxy names
(`--user-header`), or a token a node of the swarm issued to one of those or to a user
-signing a challenge with one of its keys ([`access.md`](access.md), Tokens), sent as a
-header or as the browser session's cookie: the node believes the proxy's
-header from `--trusted-proxies` alone, but from those blindly, so whoever can send
-requests from there can be any user. With the default loopback addresses, that is every
-user of the host; with only the API's Unix socket (`--trusted-proxies unix`), those its
-file's permissions let in: the node's user and group ([`operations.md`](operations.md), Behind a
-reverse proxy). It listens on `127.0.0.1:3000` by default (`--bind-addr`) and speaks
-plain HTTP: to expose it, put a TLS proxy in front. What each user may do is the
-swarm's: its user registry, in the document, gives each capabilities by path, to read
-and to write, protocol data apart ([`access.md`](access.md)); a user the registry doesn't have
-may do nothing. In a swarm without a registry (started without one), all users may read
-and write user data and use the admin endpoints, and only those in `--protocol-writers`
-write protocol data. Epoch metadata and the swarm ID are never writable. The `/debug` endpoints exist only with
+signing a challenge with one of its keys ([`access.md`](access.md),
+[Tokens](access.md#tokens)), sent as a header or as the browser session's cookie: the node
+believes the proxy's header from `--trusted-proxies` alone, but from those blindly, so
+whoever can send requests from there can be any user. With the default loopback addresses,
+that is every user of the host; with only the API's Unix socket
+(`--trusted-proxies unix`), those its file's permissions let in: the node's user and group
+([`operations.md`](operations.md),
+[Behind a reverse proxy](operations.md#behind-a-reverse-proxy)). It listens on
+`127.0.0.1:3000` by default (`--bind-addr`) and speaks plain HTTP: to expose it, put a TLS
+proxy in front. What each user may do is the swarm's: its user registry, in the document,
+gives each capabilities by path, to read and to write, protocol data apart
+([`access.md`](access.md)); a user the registry doesn't have may do nothing. In a swarm
+without a registry (started without one), all users may read and write user data and use
+the admin endpoints, and only those in `--protocol-writers` write protocol data. Epoch
+metadata and the swarm ID are never writable. The `/debug` endpoints exist only with
`--debug-api`.
**The configuration.** Whoever can write a node's configuration file or its options can
@@ -65,13 +67,13 @@ three steps, each adding to the one before ([`access.md`](access.md)).
on what the document says:
* **User data**: any member can write or delete any path.
-* **Who wrote what** (`GET /admin/changes`): each change names its node and API user
- as the writing node says. Nodes sign their changes ([`api.md`](api.md), Signed
- changes), so a change a signature vouches for shows `verified`: its node made it. One
- that shows unverified may yet be vouched for by its node's next signature, or may be
- another member's claiming that node. The user a change names is its node's claim,
- signed or not. The names of the users who write are in the document, and so on every
- node.
+* **Who wrote what** (`GET /admin/changes`): each change names its node and API user as
+ the writing node says. Nodes sign their changes ([`api.md`](api.md),
+ [Signed changes](api.md#signed-changes)), so a change a signature vouches for shows
+ `verified`: its node made it. One that shows unverified may yet be vouched for by its
+ node's next signature, or may be another member's claiming that node. The user a change
+ names is its node's claim, signed or not. The names of the users who write are in the
+ document, and so on every node.
* **The member registry, the user registry, forget records, remakes and votes**: the
API lets only users given protocol data write them, but a member can write anything
into its own document, and every node acts on it: the topology, the electorate, who
@@ -131,9 +133,10 @@ where it matters, for the rest.
Nodes don't agree on time; each judges by its own clock: voting periods, when a remake
expires and may be aborted by others, the replay window, alive stamps (and so the
electorate). Keep the clocks within a grace period (four keepalives) of each other,
-e.g. with NTP. A node whose clock is further off can, together with an operator's
-abort, make a remake contested ([`remakes.md`](remakes.md), Limits). A node compares its clock with its
-peers' and warns when its own is off (`--clock-skew-warn`; [`measurements.md`](measurements.md), Clocks).
+e.g. with NTP. A node whose clock is further off can, together with an operator's abort,
+make a remake contested ([`remakes.md`](remakes.md), [Limits](remakes.md#limits)). A node
+compares its clock with its peers' and warns when its own is off (`--clock-skew-warn`;
+[`measurements.md`](measurements.md), [Clocks](measurements.md#clocks)).
## What a stranger can do