commit f40871d780fcc4d095ea955261465a3e67f28f52 Author: teor teor@torproject.org Date: Wed Feb 19 20:57:50 2020 +1000

README: Document "wait for relays in the consensus"

Part of 33379. --- README | 47 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 33 insertions(+), 14 deletions(-)

diff --git a/README b/README index 0d14d64..0f4cf4c 100644 --- a/README +++ b/README @@ -162,32 +162,51 @@ Bootstrapping the network: Chutney expects a tor network to bootstrap in these stages: 1. All directory authorities (DirAuths) bootstrap to 100%. 2. The DirAuths produce the first consensus. - - 3. Relays bootstrap to 100%. - 4. Relays with "AssumeReachable 1" publish their descriptors to the + Usually, this consensus only contains authorities. + 3. The DirAuths produce a bootstrap consensus. + This consensus has enough relays for: + * clients and relays to bootstrap, and + * relays to perform reachability self-tests. + Usually, this consensus needs at least 3 nodes. + This consensus is usually the first or second consensus. + + 4. Relays bootstrap to 100%. + 5. Relays with "AssumeReachable 1" publish their descriptors to the DirAuths. - 5. The DirAuths produce a consensus containing enough nodes for - relay reachability self-tests (usually 3 nodes).

6. Relays perform ORPort reachability self-tests. If the consensus contains at least 1 exit, relays also perform DirPort reachability self-tests. 7. Relays publish their descriptors to the DirAuths. - 8. The DirAuths produce a consensus containing all authorities (including - the bridge authority, if present) and all relays. + 8. The DirAuths produce a full consensus. A full consensus contains: + * the authorities + * any bridge authorities, if present, and + * all relays (including exits). + Bridges, clients, and onion services are not included in the consensus.

9. Clients bootstrap to 100%. - (Clients start bootstrapping as soon as the first consensus is - available.) + (Clients can bootstrap as soon as the consensus contains enough nodes, + so step 9 depends on step 3, not step 8.) 10. Onion Services publish their descriptors to Onion Service directories (otherwise known as hidden service directories, or HSDirs).

The tools/test-network.sh script uses the chutney wait_for_bootstrap - command to wait for up to CHUTNEY_START_TIME seconds (default: 120), checking - whether the logged bootstrapped status for every node is 100% (step 9). If - all the nodes have bootstrapped, wait_for_bootstrap succeeds. If some nodes - have not bootstrapped, wait_for_bootstrap dumps the bootstrap statuses, and - exits with a failure. + command to wait for the network to bootstrap. wait_for_bootstrap waits up to + CHUTNEY_START_TIME seconds (default: 120), checking whether the logged + bootstrapped status for every node is 100% (step 9). Once all the nodes have + bootstrapped, wait_for_bootstrap starts waiting for a full consensus. + + When waiting for a full consensus, wait_for_bootstrap checks if each relay + is in the consensus (step 8). Once all the relays are in the consensus, + wait_for_bootstrap succeeds. + + If the time limit has elapsed, and some nodes have not bootstrapped, or + there are some nodes missing from the consensus, wait_for_bootstrap dumps the + bootstrap statuses, and exits with a failure. + + (wait_for_bootstrap does not check if all the onion services have published + their descriptors to the HSDirs. But we would like to implement that feature + some time.)

Verifying the network: