|
|
@@ -1,258 +0,0 @@
|
|
|
-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
|
|
|
-
|
|
|
-Right now it only sorta does these things.
|
|
|
-
|
|
|
-You will need:
|
|
|
- - Python 2.7, or a supported 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:
|
|
|
-
|
|
|
-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,
|
|
|
-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
|
|
|
- --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
|
|
|
-
|
|
|
-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,
|
|
|
-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
|
|
|
-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.
|
|
|
-
|
|
|
-Waiting for the network:
|
|
|
-
|
|
|
- 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.
|
|
|
-
|
|
|
- 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).
|
|
|
-
|
|
|
- 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.
|
|
|
-
|
|
|
- You can override the directory "./net" with the CHUTNEY_DATA_DIR
|
|
|
- environment variable.
|
|
|
-
|
|
|
-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.
|
|
|
-
|
|
|
- Test scripts can be run using the following syntax:
|
|
|
- ./chutney <script-name> networks/<network-name>
|
|
|
-
|
|
|
- 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.
|
