commit 07d6a8ab059742bc2b084fd8164912948b6d6aad
Author: Ben Weintraub <ben(a)weintraub.xyz>
Date: Mon Jul 19 13:36:39 2021 -0400
Convert README text to Markdown format
The README has a `.md` extension, but was not actually written in
Markdown format, which was causing it to render poorly on GitHub and
GitLab.
---
README.md | 695 ++++++++++++++++++++++++++++++++++----------------------------
1 file changed, 383 insertions(+), 312 deletions(-)
diff --git a/README.md b/README.md
index dca19d3..2b219c8 100644
--- a/README.md
+++ b/README.md
@@ -1,343 +1,414 @@
+# Chutney
+
This is chutney. It doesn't do much so far. It isn't ready for prime-time.
If it breaks, you get to keep all the pieces.
It is supposed to be a good tool for:
- - Configuring a testing tor network
- - Launching and monitoring a testing tor network
- - Running tests on a testing tor network
+
+- Configuring a testing tor network
+- Launching and monitoring a testing tor network
+- Running tests on a testing tor network
Right now it only sorta does these things.
-You will need:
- - A supported version of Python 3
- - (we support Python versions that are still getting updates), and
- - Tor binaries.
+## You will need
+- A supported version of Python 3
+ - (we support Python versions that are still getting updates), and
+- Tor binaries.
Chutney checks for Tor binaries in this order:
- - If you run chutney's tools/test-network.sh from a tor build directory,
- (or set the environment variable $TOR_DIR to a tor build directory,)
- chutney will automatically detect the tor binaries, or
- - If you put the location of the 'tor' and 'tor-gencert' binaries in the
- environment variables $CHUTNEY_TOR and $CHUTNEY_TOR_GENCERT, respectively,
- chutney will use those binaries, or
- - You will need tor and tor-gencert installed somewhere in your path.
-Stuff to try:
+- If you run chutney's `tools/test-network.sh` from a tor build directory,
+ (or set the environment variable `$TOR_DIR` to a tor build directory,)
+ chutney will automatically detect the tor binaries, or
+- If you put the location of the `tor` and `tor-gencert` binaries in the
+ environment variables `$CHUTNEY_TOR` and `$CHUTNEY_TOR_GENCERT`, respectively,
+ chutney will use those binaries, or
+- You will need `tor` and `tor-gencert` installed somewhere in your path.
+
+## Stuff to try
Automated Setup, Verification, and Shutdown:
- ./tools/test-network.sh --flavor basic-min
- ./tools/test-network.sh --coverage
- ./tools/test-network.sh --tor-path <tor-build-directory>
- ./tools/test-network.sh --tor <name-or-path> --tor-gencert <name-or-path>
- (--tor-path and $TOR_DIR override --tor and --tor-gencert.)
- (The script tries hard to find tor.)
- ./tools/test-network.sh --chutney-path <chutney-directory>
- (The script is pretty good at finding chutney.)
- ./tools/test-network.sh --allow-failures <N>
-
-test-network.sh looks for some tor binaries (either in a nearby build
-directory or in your $PATH), configures a comprehensive tor test network,
+
+``` shell
+./tools/test-network.sh --flavor basic-min
+./tools/test-network.sh --coverage
+./tools/test-network.sh --tor-path <tor-build-directory>
+./tools/test-network.sh --tor <name-or-path> --tor-gencert <name-or-path>
+```
+(`--tor-path` and `$TOR_DIR` override `--tor` and `--tor-gencert`.)
+(The script tries hard to find `tor`.)
+
+``` shell
+./tools/test-network.sh --chutney-path <chutney-directory>
+```
+(The script is pretty good at finding `chutney`.)
+
+``` shell
+./tools/test-network.sh --allow-failures <N>
+```
+
+`test-network.sh` looks for some tor binaries (either in a nearby build
+directory or in your `$PATH`), configures a comprehensive Tor test network,
launches it, then verifies data transmission through it, and cleans up after
itself. Relative paths are supported.
You can modify its configuration using command-line arguments, or use the
chutney environmental variables documented below:
-Verification Options:
- # repeats bootstrap and verify
- --allow-failures CHUTNEY_ALLOW_FAILURES=N
- # repeats verify
- --rounds CHUTNEY_ROUNDS=N
- # makes multiple connections within verify
- --connections CHUTNEY_CONNECTIONS=N
-
-Timing Options:
- --start-time CHUTNEY_START_TIME=N
- --min-start-time CHUTNEY_MIN_START_TIME=N
- --bootstrap-time CHUTNEY_BOOTSTRAP_TIME=N
- --stop-time CHUTNEY_STOP_TIME=N
-
-Traffic Options:
- --data CHUTNEY_DATA_BYTES=N
- --hs-multi-client CHUTNEY_HS_MULTI_CLIENT=N
-
-Address/DNS Options:
- --ipv4 CHUTNEY_LISTEN_ADDRESS=IPV4
- --ipv6 CHUTNEY_LISTEN_ADDRESS_V6=IPV6
- # Chutney uses /etc/resolv.conf if none of these options are set
- --dns-conf CHUTNEY_DNS_CONF=PATH
- --offline CHUTNEY_DNS_CONF=/dev/null
- # Use tor's compile-time default for ServerDNSResolvConfFile
- --dns-conf-default CHUTNEY_DNS_CONF=""
-
-Sandbox Options:
-
- --sandbox CHUTNEY_TOR_SANDBOX=N (0 or 1)
-
-Warning Options:
- --all-warnings CHUTNEY_WARNINGS_IGNORE_EXPECTED=false
- CHUTNEY_WARNINGS_SUMMARY=false
- --no-warnings CHUTNEY_WARNINGS_SKIP=true
- --only-warnings CHUTNEY_WARNINGS_ONLY=true
- --diagnostics CHUTNEY_DIAGNOSTICS=true
- --only-diagnostics CHUTNEY_DIAGNOSTICS_ONLY=true
-
-Expert Options:
- --debug CHUTNEY_DEBUG=true
- --coverage USE_COVERAGE_BINARY=true
- --dry-run NETWORK_DRY_RUN=true
- --quiet ECHO=true
-
- --controlling-pid CHUTNEY_CONTROLLING_PID=N
- --net-dir CHUTNEY_DATA_DIR=PATH
- (These are advanced options: in the past, they have had long-standing bugs.)
-
-Standard Actions:
- ./chutney configure networks/basic
- ./chutney start networks/basic
- ./chutney status networks/basic
- ./chutney wait_for_bootstrap networks/basic
- ./chutney verify networks/basic
- ./chutney hup networks/basic
- ./chutney stop networks/basic
-
-Bandwidth Tests:
- ./chutney configure networks/basic-min
- ./chutney start networks/basic-min
- ./chutney status networks/basic-min
- # Send 100MB of data per client connection
- CHUTNEY_DATA_BYTES=104857600 ./chutney verify networks/basic-min
- ./chutney stop networks/basic-min
-
-If chutney sends at least 5 MB of data, and it takes at least one second,
+## Verification Options
+
+``` shell
+# repeats bootstrap and verify
+--allow-failures CHUTNEY_ALLOW_FAILURES=N
+# repeats verify
+--rounds CHUTNEY_ROUNDS=N
+# makes multiple connections within verify
+--connections CHUTNEY_CONNECTIONS=N
+```
+
+## Timing Options
+
+``` shell
+--start-time CHUTNEY_START_TIME=N
+--min-start-time CHUTNEY_MIN_START_TIME=N
+--bootstrap-time CHUTNEY_BOOTSTRAP_TIME=N
+--stop-time CHUTNEY_STOP_TIME=N
+```
+
+## Traffic Options
+
+``` shell
+--data CHUTNEY_DATA_BYTES=N
+--hs-multi-client CHUTNEY_HS_MULTI_CLIENT=N
+```
+
+## Address/DNS Options
+
+``` shell
+--ipv4 CHUTNEY_LISTEN_ADDRESS=IPV4
+--ipv6 CHUTNEY_LISTEN_ADDRESS_V6=IPV6
+
+# Chutney uses /etc/resolv.conf if none of these options are set
+--dns-conf CHUTNEY_DNS_CONF=PATH
+--offline CHUTNEY_DNS_CONF=/dev/null
+
+# Use tor's compile-time default for ServerDNSResolvConfFile
+--dns-conf-default CHUTNEY_DNS_CONF=""
+```
+
+## Sandbox Options
+
+``` shell
+--sandbox CHUTNEY_TOR_SANDBOX=N (0 or 1)
+```
+
+## Warning Options
+
+``` shell
+--all-warnings CHUTNEY_WARNINGS_IGNORE_EXPECTED=false
+ CHUTNEY_WARNINGS_SUMMARY=false
+--no-warnings CHUTNEY_WARNINGS_SKIP=true
+--only-warnings CHUTNEY_WARNINGS_ONLY=true
+--diagnostics CHUTNEY_DIAGNOSTICS=true
+--only-diagnostics CHUTNEY_DIAGNOSTICS_ONLY=true
+```
+
+## Expert Options
+
+``` shell
+--debug CHUTNEY_DEBUG=true
+--coverage USE_COVERAGE_BINARY=true
+--dry-run NETWORK_DRY_RUN=true
+--quiet ECHO=true
+
+--controlling-pid CHUTNEY_CONTROLLING_PID=N
+--net-dir CHUTNEY_DATA_DIR=PATH
+```
+(These are advanced options: in the past, they have had long-standing bugs.)
+
+## Standard Actions
+
+``` shell
+./chutney configure networks/basic
+./chutney start networks/basic
+./chutney status networks/basic
+./chutney wait_for_bootstrap networks/basic
+./chutney verify networks/basic
+./chutney hup networks/basic
+./chutney stop networks/basic
+```
+
+## Bandwidth Tests
+
+``` shell
+./chutney configure networks/basic-min
+./chutney start networks/basic-min
+./chutney status networks/basic-min
+```
+
+Send 100MB of data per client connection:
+``` shell
+CHUTNEY_DATA_BYTES=104857600 ./chutney verify networks/basic-min
+./chutney stop networks/basic-min
+```
+
+If chutney sends at least `5 MB` of data, and it takes at least one second,
verify produces performance figures for:
- - Single Stream Bandwidth: the speed of the slowest stream, end-to-end
- - Overall tor Bandwidth: the sum of the bandwidth across each tor instance
+
+- Single Stream Bandwidth: the speed of the slowest stream, end-to-end
+- Overall tor Bandwidth: the sum of the bandwidth across each tor instance
+
The overall bandwidth approximates the CPU-bound tor performance on the
current machine, assuming tor, chutney, and the OS are multithreaded, and
network performance is infinite.
-Connection Tests:
- ./chutney configure networks/basic-025
- ./chutney start networks/basic-025
- ./chutney status networks/basic-025
- # Make 5 simultaneous connections from each client through a random exit
- CHUTNEY_CONNECTIONS=5 ./chutney verify networks/basic-025
- ./chutney stop networks/basic-025
-
- # Run 5 sequential verification rounds
- CHUTNEY_ROUNDS=5 ./tools/test-network.sh --flavour basic
-
-HS Connection Tests:
- ./chutney configure networks/hs-025
- ./chutney start networks/hs-025
- ./chutney status networks/hs-025
- CHUTNEY_HS_MULTI_CLIENT=1 ./chutney verify networks/hs-025
- # Make a connection from each client to each hs
- # Default behavior is one client connects to each HS
- ./chutney stop networks/hs-025
-
-Bandwidth File Tests:
- ./tools/test-network.sh --flavour bwfile
- # Warning: Can't open bandwidth file at configured location: /tmp/bwfile
- # Create a bwfile with no bandwidths, that is valid for a few days
- date +%s > /tmp/bwfile
- ./tools/test-network.sh --flavour bwfile
-
-Multiple Tests:
-
- Chutney can allow a certain number of failed tests. You can either set
- CHUTNEY_ALLOW_FAILURES or use an --allow-failures command-line option to
- control this. Chutney will then reattempt the test, from bootstrap
- through shutdown, until either it succeeds, or until it has failed
- $CHUTNEY_ALLOW_FAILURES+1 times. The default value is zero, so the default
- behavior will not change.
-
- You can also use CHUTNEY_ROUNDS=N to run multiple verification rounds, or
- CHUTNEY_CONNECTIONS=N to make multiple connections within each verification
- round. Any round or connection failure will fail the current test.
-
-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.
- 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.
-
- 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 complete consensus, microdesc consensus, and
- microdescriptors. A complete 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. Bridges publish their descriptors to the Bridge Auth.
- 10. The Bridge Auth produces a bridge networkstatus.
-
- 11. Relays and bridges download all consensus flavours, then download
- descriptors and microdescriptors.
- 12. Bridge clients download the descriptors for their bridges.
- 13. Clients (including bridge clients, and onion services), download the
- most recent microdesc consensus, and microdescriptors.
- 14. Clients bootstrap to 100%.
- (Clients can bootstrap as soon as the consensus contains enough nodes,
- so this step can depend on step 3, not step 13.)
-
- 15. 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 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% (steps 9 and 14),
- and
- * directory information has been distributed throughout the network
- (steps 7-8, 11-13).
-
- When waiting for dir info distribution, wait_for_bootstrap checks if:
- * each relay descriptor has been posted to every authority (step 7),
- * each relay is in the consensus, and the microdesc consensus, at every
- authority (step 8),
- * a complete consensus and microdesc consensus has been distributed to
- relays and bridges (step 11),
- * all authority and relay descriptors have been distributed to relays
- and bridges (step 11),
- * all bridge descriptors have been distributed to all bridge clients
- (step 12), and
- * a complete microdesc consensus has been distributed to clients
- (step 13).
-
- wait_for_bootstrap does not currently check the following dir info:
- * microdescriptors (steps 8, 11, and 13, chutney ticket #33407),
- * bridge descriptors at the bridge authority (steps 9-10,
- tor ticket #33582, chutney ticket #33428), and
- * onion services have published their descriptors to the HSDirs (step 15,
- chutney ticket #33609).
-
- After bootstrapping and dir info distribution, wait_for_bootstrap waits
- until the network has been running for at least CHUTNEY_MIN_START_TIME
- seconds (default 0 seconds for tor > 0.3.5.*, 65 seconds for tor <= 0.3.5.*),
- to compensate for microdesc download issues in older tor versions.
-
- In addition, wait_for_bootstrap also waits an extra:
- * 10 seconds for clients to download microdescs, and
- * 30 seconds for onion services to upload their descriptors.
- We expect that these delays will be removed, once the relevant checks are
- implemented in chutney.
-
- If the CHUTNEY_START_TIME 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.
-
-Verifying the network:
-
- Commands like "chutney verify" start immediately, and keep trying for
- CHUTNEY_BOOTSTRAP_TIME seconds (default: 60). If it hasn't been
- successful after that time, it fails. If CHUTNEY_BOOTSTRAP_TIME is negative,
- 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.
-
- If none of these options are negative, test-network.sh tells the tor
- processes to exit after it exits, using CHUTNEY_CONTROLLING_PID. To disable
- this functionality, set CHUTNEY_CONTROLLING_PID to 1 or less.
-
-Changing the network address:
-
- Chutney defaults to binding to localhost. To change the IPv4 bind address,
- set the CHUTNEY_LISTEN_ADDRESS environment variable. Similarly, change
- CHUTNEY_LISTEN_ADDRESS_V6 for IPv6: it defaults to "no IPv6 address".
- Setting it to some interface's IP address allows us to make the simulated
- Tor network available on the network.
-
- IPv6 support for both Tor and Chutney is a work in progress. Currently,
- chutney verifies IPv6 client, bridge client (?), hidden service, and exit
- connections. It does not use IPv6 SOCKSPorts or HiddenServicePorts.
-
-Using DNS:
-
- Chutney verify uses IP addresses by default. It does not need to look up
- any hostnames. We recommend that chutney users disable DNS using --offline
- or CHUTNEY_DNS_CONF=/dev/null , because any DNS failures causes tests to
- fail. Chutney's DNS queries also produce external traffic in a predictable
- pattern.
-
- If you want to use a hostname with CHUTNEY_LISTEN_ADDRESS[_V6], or you want
- to run tests that use DNS, set CHUTNEY_DNS_CONF to the path to a file in
- resolv.conf format. Chutney's default of /etc/resolv.conf should be fine for
- most UNIX-based operating systems. If your tor is compiled with a different
- default, use --dns-resolv-conf-default or CHUTNEY_DNS_CONF="".
-
- When the CHUTNEY_DNS_CONF file does not exist, or is a broken symlink,
- chutney uses /dev/null instead. This is a workaround for bugs in tor's
- use of eventdns. For example, macOS deletes the resolv.conf file when it
- thinks the network is down: this can make tor exits reject all traffic,
- even if a working DNS server is running on 127.0.0.1:53.
-
- When tor has no working name servers (including --offline mode), it can
- crash on SETCONF. (Chutney does not use SETCONF, but some external tor
- controllers do.) To avoid this crash, set CHUTNEY_DNS_CONF to a file
- containing a working name server address. For your convenience, chutney
- provides a local resolv.conf file containing IPv4, IPv6, and "localhost".
- Use --dns-conf resolv.conf (relative paths work).
-
-The tor sandbox:
-
- Chutney can run with the tor seccomp sandbox enabled. But if tor's sandbox
- is broken on your local version of glibc, you can set CHUTNEY_TOR_SANDBOX=0
- to disable the sandbox. If CHUTNEY_TOR_SANDBOX is unset, Sandbox defaults
- to 1 on Linux, and 0 on other platforms.
-
-The configuration files:
-
- networks/basic holds the configuration for the network you're configuring
- above. It refers to some torrc template files in torrc_templates/.
-
- Chutney uses a templating system to produce torrc files from the templates.
- These torrc files can be modified using various chutney options.
-
-The working files:
+## Connection Tests
+
+``` shell
+./chutney configure networks/basic-025
+./chutney start networks/basic-025
+./chutney status networks/basic-025
+```
+
+Make 5 simultaneous connections from each client through a random exit
+
+``` shell
+CHUTNEY_CONNECTIONS=5 ./chutney verify networks/basic-025
+./chutney stop networks/basic-025
+```
+
+Run 5 sequential verification rounds
+
+``` shell
+CHUTNEY_ROUNDS=5 ./tools/test-network.sh --flavour basic
+```
+
+## HS Connection Tests
+
+``` shell
+./chutney configure networks/hs-025
+./chutney start networks/hs-025
+./chutney status networks/hs-025
+```
+
+Make a connection from each client to each hs Default behavior is one client
+connects to each HS:
+``` shell
+CHUTNEY_HS_MULTI_CLIENT=1 ./chutney verify networks/hs-025
+./chutney stop networks/hs-025
+```
+
+
+## Bandwidth File Tests
+
+``` shell
+./tools/test-network.sh --flavour bwfile
+# Warning: Can't open bandwidth file at configured location: /tmp/bwfile
+# Create a bwfile with no bandwidths, that is valid for a few days
+date +%s > /tmp/bwfile
+./tools/test-network.sh --flavour bwfile
+```
+
+## Multiple Tests
+
+Chutney can allow a certain number of failed tests. You can either set
+`CHUTNEY_ALLOW_FAILURES` or use an `--allow-failures` command-line option to
+control this. Chutney will then reattempt the test, from bootstrap through
+shutdown, until either it succeeds, or until it has failed
+`$CHUTNEY_ALLOW_FAILURES+1` times. The default value is zero, so the default
+behavior will not change.
+
+You can also use `CHUTNEY_ROUNDS=N` to run multiple verification rounds, or
+`CHUTNEY_CONNECTIONS=N` to make multiple connections within each verification
+round. Any round or connection failure will fail the current test.
+
+## 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.
+ 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`.
+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 complete consensus, microdesc consensus, and
+ microdescriptors. A complete 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. Bridges publish their descriptors to the Bridge Auth.
+10. The Bridge Auth produces a bridge networkstatus.
+11. Relays and bridges download all consensus flavours, then download
+ descriptors and microdescriptors.
+12. Bridge clients download the descriptors for their bridges.
+13. Clients (including bridge clients, and onion services), download the
+ most recent microdesc consensus, and microdescriptors.
+14. Clients bootstrap to 100%.
+ (Clients can bootstrap as soon as the consensus contains enough nodes,
+ so this step can depend on step 3, not step 13.)
+15. 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 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% (steps 9 and 14),
+ and
+* directory information has been distributed throughout the network
+ (steps 7-8, 11-13).
+
+When waiting for dir info distribution, `wait_for_bootstrap` checks if:
+
+* each relay descriptor has been posted to every authority (step 7),
+* each relay is in the consensus, and the microdesc consensus, at every
+ authority (step 8),
+* a complete consensus and microdesc consensus has been distributed to
+ relays and bridges (step 11),
+* all authority and relay descriptors have been distributed to relays
+ and bridges (step 11),
+* all bridge descriptors have been distributed to all bridge clients
+ (step 12), and
+* a complete microdesc consensus has been distributed to clients
+ (step 13).
+
+`wait_for_bootstrap` does not currently check the following dir info:
+
+* microdescriptors (steps 8, 11, and 13, chutney ticket #33407),
+* bridge descriptors at the bridge authority (steps 9-10,
+ tor ticket #33582, chutney ticket #33428), and
+* onion services have published their descriptors to the HSDirs (step 15,
+ chutney ticket #33609).
+
+After bootstrapping and dir info distribution, `wait_for_bootstrap` waits
+until the network has been running for at least `CHUTNEY_MIN_START_TIME`
+seconds (default 0 seconds for `tor` > 0.3.5., 65 seconds for `tor` <= 0.3.5.),
+to compensate for microdesc download issues in older tor versions.
+
+In addition, `wait_for_bootstrap` also waits an extra:
+
+- 10 seconds for clients to download microdescs, and
+- 30 seconds for onion services to upload their descriptors.
+
+We expect that these delays will be removed, once the relevant checks are
+implemented in chutney.
+
+If the `CHUTNEY_START_TIME` 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.
+
+## Verifying the network
+
+Commands like `chutney verify` start immediately, and keep trying for
+`CHUTNEY_BOOTSTRAP_TIME` seconds (default: 60). If it hasn't been
+successful after that time, it fails. If `CHUTNEY_BOOTSTRAP_TIME` is negative,
+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.
+
+If none of these options are negative, `test-network.sh` tells the tor
+processes to exit after it exits, using `CHUTNEY_CONTROLLING_PID`. To disable
+this functionality, set `CHUTNEY_CONTROLLING_PID` to 1 or less.
+
+## Changing the network address
+
+Chutney defaults to binding to `localhost`. To change the IPv4 bind address,
+set the `CHUTNEY_LISTEN_ADDRESS` environment variable. Similarly, change
+`CHUTNEY_LISTEN_ADDRESS_V6` for IPv6: it defaults to "no IPv6 address".
+Setting it to some interface's IP address allows us to make the simulated
+Tor network available on the network.
+
+IPv6 support for both Tor and Chutney is a work in progress. Currently,
+chutney verifies IPv6 client, bridge client (?), hidden service, and exit
+connections. It does not use IPv6 `SOCKSPorts` or `HiddenServicePorts`.
+
+## Using DNS
+
+Chutney verify uses IP addresses by default. It does not need to look up
+any hostnames. We recommend that chutney users disable DNS using `--offline`
+or `CHUTNEY_DNS_CONF=/dev/null`, because any DNS failures causes tests to
+fail. Chutney's DNS queries also produce external traffic in a predictable
+pattern.
+
+If you want to use a hostname with `CHUTNEY_LISTEN_ADDRESS[_V6]`, or you want
+to run tests that use DNS, set `CHUTNEY_DNS_CONF` to the path to a file in
+`resolv.conf` format. Chutney's default of `/etc/resolv.conf` should be fine for
+most UNIX-based operating systems. If your tor is compiled with a different
+default, use `--dns-resolv-conf-default` or `CHUTNEY_DNS_CONF=""`.
+
+When the `CHUTNEY_DNS_CONF` file does not exist, or is a broken symlink,
+`chutney` uses `/dev/null` instead. This is a workaround for bugs in Tor's
+use of `eventdns`. For example, macOS deletes the `resolv.conf` file when it
+thinks the network is down: this can make tor exits reject all traffic,
+even if a working DNS server is running on 127.0.0.1:53.
+
+When tor has no working name servers (including `--offline` mode), it can
+crash on `SETCONF`. (Chutney does not use `SETCONF`, but some external tor
+controllers do.) To avoid this crash, set `CHUTNEY_DNS_CONF` to a file
+containing a working name server address. For your convenience, chutney
+provides a local `resolv.conf` file containing IPv4, IPv6, and `localhost`.
+Use `--dns-conf resolv.conf` (relative paths work).
+
+## The Tor sandbox
+
+Chutney can run with the Tor seccomp sandbox enabled. But if Tor's sandbox
+is broken on your local version of glibc, you can set `CHUTNEY_TOR_SANDBOX=0`
+to disable the sandbox. If `CHUTNEY_TOR_SANDBOX` is unset, Sandbox defaults
+to 1 on Linux, and 0 on other platforms.
+
+## The configuration files
+
+`networks/basic` holds the configuration for the network you're configuring
+above. It refers to some torrc template files in `torrc_templates/`.
+
+Chutney uses a templating system to produce torrc files from the templates.
+These torrc files can be modified using various chutney options.
+
+## The working files
+
+Chutney sticks its working files, including all generated torrc files,
+data directories, log files, etc, in `./net/`. Each tor instance gets a
+subdirectory of `net/nodes`.
- chutney sticks its working files, including all generated torrc files,
- data directories, log files, etc, in ./net/. Each tor instance gets a
- subdirectory of net/nodes.
+You can override the directory `./net` with the `CHUTNEY_DATA_DIR`
+environment variable.
- You can override the directory "./net" with the CHUTNEY_DATA_DIR
- environment variable.
+## Test scripts
-Test scripts:
+The test scripts are stored in the `scripts/chutney_tests` directory. These
+Python files must define a `run_test(network)` function. Files starting with
+an underscore ("_") are ignored.
- The test scripts are stored in the "scripts/chutney_tests" directory. These
- Python files must define a "run_test(network)" function. Files starting with
- an underscore ("_") are ignored.
+Test scripts can be run using the following syntax:
- Test scripts can be run using the following syntax:
- ./chutney <script-name> networks/<network-name>
+``` shell
+./chutney <script-name> networks/<network-name>
+```
- The chutney verify command is implemented using a test script.
+The `chutney verify` command is implemented using a test script.
- Test scripts in the test directory with the same name as standard commands
- are run instead of that standard command. This allows expert users to replace
- the standard chutney commands with modified versions.
+Test scripts in the test directory with the same name as standard commands
+are run instead of that standard command. This allows expert users to replace
+the standard chutney commands with modified versions.
