Browse Source

Updated README

Steven Engler 3 years ago
parent
commit
2242140db9
2 changed files with 3 additions and 258 deletions
  1. 0 258
      README
  2. 3 0
      README.md

+ 0 - 258
README

@@ -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.

+ 3 - 0
README.md

@@ -0,0 +1,3 @@
+# Chutney for Throughput Testing
+
+This repository contains a patched version of [Chutney](https://gitweb.torproject.org/chutney.git) with additional features for running relay performance experiments.