diff options
| author | tv <tv@krebsco.de> | 2026-11-18 12:48:29 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-18 13:59:42 +0100 |
| commit | d130c0612b4c63f2d30da65ebcc231018c1f2606 (patch) | |
| tree | 8700f2d53351cbbecbe772ea7701bf6240d5210c /docs/trust.md | |
| parent | 0bfe07af92a775b0e896e0fc5a989a1d9b65f7b3 (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.md | 49 |
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 |
