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 ./tools/test-network.sh --tor --tor-gencert (--tor-path and $TOR_DIR override --tor and --tor-gencert.) (The script tries hard to find tor.) ./tools/test-network.sh --chutney-path (The script is pretty good at finding chutney.) ./tools/test-network.sh --allow-failures 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 # 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 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 networks/ 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.