123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245 |
- 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),
- - 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=""
- 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
- CHUTNEY_DATA_BYTES=104857600 ./chutney verify networks/basic-min
- # Send 100MB of data per client connection
- # 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
- # This approximates the CPU-bound tor performance on the current machine,
- # assuming everything is multithreaded and network performance is infinite.
- ./chutney stop networks/basic-min
- 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 waits CHUTNEY_START_TIME seconds
- (default: 40) before calling chutney verify, because that's the minimum
- amount of time it takes to bootstrap a consensus containing relays.
- (It takes 20 seconds for the authorities to create the first consensus,
- then 20 seconds for relays to bootstrap, submit their descriptors, and be
- included in the next consensus.) If CHUTNEY_START_TIME is negative, the
- script leaves the network running, and exits immediately (without verifying).
- chutney also has an experimental wait_for_bootstrap command. It waits for
- up to CHUTNEY_START_TIME seconds, checking whether the logged bootstrapped
- status for every node is 100%. If it is, great: it succeeds. If not, it
- dumps the bootstrap statuses and exits.
- 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 configuration files:
- networks/basic holds the configuration for the network you're configuring
- above. It refers to some torrc template files in torrc_templates/.
- The working files:
- chutney sticks its working files, including all 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.
|