[tor-commits] [chutney/master] README: Document how a tor network bootstraps

[teor at torproject.org]

commit 59c9a9764aa41e1988c878b386405bf639e890f1
Author: teor <teor at torproject.org>
Date:   Wed Feb 19 15:17:39 2020 +1000

    README: Document how a tor network bootstraps
    
    Part of 33232.
---
 README | 39 +++++++++++++++++++++++++++++++++------
 1 file changed, 33 insertions(+), 6 deletions(-)

diff --git a/README b/README
index 9712232..2e850ff 100644
--- a/README
+++ b/README
@@ -157,15 +157,40 @@ Multiple Tests:
   CHUTNEY_CONNECTIONS=N to make multiple connections within each verification
   round. Any round or connection failure will fail the current test.
 
-Waiting for the network:
+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
+        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.
+
+    9.  Clients bootstrap to 100%.
+        (Clients start bootstrapping as soon as the first consensus is
+        available.)
+    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%. It it is,
-  great: it succeeds. If not, it dumps the bootstrap statuses and exits.
-  test-network.sh does not exit immediately if a tor node fails to bootstrap.
-  Instead, it attempts to verify. We'll add an option to fail on tor
-  bootstrap failure in #20473.
+  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. But test-network.sh does not exit immediately if a tor
+  node fails to bootstrap. Instead, it attempts to verify.
+
+Verifying the network:
 
   Commands like "chutney verify" start immediately, and keep trying for
   CHUTNEY_BOOTSTRAP_TIME seconds (default: 60). If it hasn't been
@@ -173,6 +198,8 @@ Waiting for the network:
   the script leaves the network running, and exits after CHUTNEY_START_TIME
   (without verifying).
 
+Shutting down the network:
+
   The tools/test-network.sh script waits CHUTNEY_STOP_TIME seconds
   after verifying, then exits (default: immediately). If CHUTNEY_STOP_TIME is
   negative, the script leaves the network running, and exits after verifying.