README 8.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207
  1. This is chutney. It doesn't do much so far. It isn't ready for prime-time.
  2. If it breaks, you get to keep all the pieces.
  3. It is supposed to be a good tool for:
  4. - Configuring a testing tor network
  5. - Launching and monitoring a testing tor network
  6. - Running tests on a testing tor network
  7. Right now it only sorta does these things.
  8. You will need, at the moment:
  9. - Tor installed somewhere in your path, or
  10. - The location of the 'tor' and 'tor-gencert' binaries specified through the
  11. environment variables CHUTNEY_TOR and CHUTNEY_TOR_GENCERT, respectively, or
  12. - To run chutney's tools/test-network.sh from a tor build directory, and
  13. - Python 2.7 or later (Python 3 support is an ongoing work)
  14. Stuff to try:
  15. Automated Setup, Verification, and Shutdown:
  16. ./tools/test-network.sh --flavor basic-min
  17. ./tools/test-network.sh --coverage
  18. ./tools/test-network.sh --tor-path <tor-build-directory>
  19. ./tools/test-network.sh --tor <name-or-path> --tor-gencert <name-or-path>
  20. (--tor-path and $TOR_DIR override --tor and --tor-gencert.)
  21. (The script tries hard to find tor.)
  22. ./tools/test-network.sh --chutney-path <chutney-directory>
  23. (The script is pretty good at finding chutney.)
  24. test-network.sh looks for some tor binaries (either in a nearby build
  25. directory or in your $PATH), configures a comprehensive tor test network,
  26. launches it, then verifies data transmission through it, and cleans up after
  27. itself. Relative paths are supported.
  28. You can modify its configuration using command-line arguments, or use the
  29. chutney environmental variables documented below:
  30. Timing Options:
  31. --start-time CHUTNEY_START_TIME=N
  32. --bootstrap-time CHUTNEY_BOOTSTRAP_TIME=N
  33. --stop-time CHUTNEY_STOP_TIME=N
  34. Traffic Options:
  35. --data CHUTNEY_DATA_BYTES=N
  36. # connections are simultaneous, rounds are sequential
  37. --connections CHUTNEY_CONNECTIONS=N
  38. --rounds CHUTNEY_ROUNDS=N
  39. --hs-multi-client CHUTNEY_HS_MULTI_CLIENT=N
  40. Address/DNS Options:
  41. --ipv4 CHUTNEY_LISTEN_ADDRESS=IPV4
  42. --ipv6 CHUTNEY_LISTEN_ADDRESS_V6=IPV6
  43. # Chutney uses /etc/resolv.conf if none of these options are set
  44. --dns-conf CHUTNEY_DNS_CONF=PATH
  45. --offline CHUTNEY_DNS_CONF=/dev/null
  46. # Use tor's compile-time default for ServerDNSResolvConfFile
  47. --dns-conf-default CHUTNEY_DNS_CONF=""
  48. Warning Options:
  49. --all-warnings CHUTNEY_WARNINGS_IGNORE_EXPECTED=false
  50. CHUTNEY_WARNINGS_SUMMARY=false
  51. --no-warnings CHUTNEY_WARNINGS_SKIP=true
  52. --only-warnings CHUTNEY_WARNINGS_ONLY=true
  53. Expert Options:
  54. --debug CHUTNEY_DEBUG=true
  55. --coverage USE_COVERAGE_BINARY=true
  56. --dry-run NETWORK_DRY_RUN=true
  57. --quiet ECHO=true
  58. --controlling-pid CHUTNEY_CONTROLLING_PID=N
  59. --net-dir CHUTNEY_DATA_DIR=PATH
  60. (These are advanced options: in the past, they have had long-standing bugs.)
  61. Standard Actions:
  62. ./chutney configure networks/basic
  63. ./chutney start networks/basic
  64. ./chutney status networks/basic
  65. ./chutney verify networks/basic
  66. ./chutney hup networks/basic
  67. ./chutney stop networks/basic
  68. Bandwidth Tests:
  69. ./chutney configure networks/basic-min
  70. ./chutney start networks/basic-min
  71. ./chutney status networks/basic-min
  72. CHUTNEY_DATA_BYTES=104857600 ./chutney verify networks/basic-min
  73. # Send 100MB of data per client connection
  74. # verify produces performance figures for:
  75. # Single Stream Bandwidth: the speed of the slowest stream, end-to-end
  76. # Overall tor Bandwidth: the sum of the bandwidth across each tor instance
  77. # This approximates the CPU-bound tor performance on the current machine,
  78. # assuming everything is multithreaded and network performance is infinite.
  79. ./chutney stop networks/basic-min
  80. Connection Tests:
  81. ./chutney configure networks/basic-025
  82. ./chutney start networks/basic-025
  83. ./chutney status networks/basic-025
  84. # Make 5 simultaneous connections from each client through a random exit
  85. CHUTNEY_CONNECTIONS=5 ./chutney verify networks/basic-025
  86. ./chutney stop networks/basic-025
  87. # Run 5 sequential verification rounds
  88. CHUTNEY_ROUNDS=5 ./tools/test-network.sh --flavour basic
  89. Note: If you create 7 or more connections to a hidden service from a single
  90. Tor 0.2.7 client, you'll likely get a verification failure due to #15937.
  91. This is fixed in 0.2.8.
  92. HS Connection Tests:
  93. ./chutney configure networks/hs-025
  94. ./chutney start networks/hs-025
  95. ./chutney status networks/hs-025
  96. CHUTNEY_HS_MULTI_CLIENT=1 ./chutney verify networks/hs-025
  97. # Make a connection from each client to each hs
  98. # Default behavior is one client connects to each HS
  99. ./chutney stop networks/hs-025
  100. Waiting for the network:
  101. The tools/test-network.sh script waits CHUTNEY_START_TIME seconds
  102. (default: 20) before calling chutney verify, because that's the minimum
  103. amount of time it takes to bootstrap a consensus containing relays.
  104. (It takes 5-10 seconds for the authorities to create the first consensus,
  105. then 10 seconds for relays to bootstrap, submit their descriptors, and be
  106. included in the next consensus.) If CHUTNEY_START_TIME is negative, the
  107. script leaves the network running, and exits immediately (without verifying).
  108. Commands like "chutney verify" start immediately, and keep trying for
  109. CHUTNEY_BOOTSTRAP_TIME seconds (default: 60). If it hasn't been
  110. successful after that time, it fails. If CHUTNEY_BOOTSTRAP_TIME is negative,
  111. the script leaves the network running, and exits after CHUTNEY_START_TIME
  112. (without verifying).
  113. The tools/test-network.sh script waits CHUTNEY_STOP_TIME seconds
  114. after verifying, then exits (default: immediately). If CHUTNEY_STOP_TIME is
  115. negative, the script leaves the network running, and exits after verifying.
  116. If none of these options are negative, test-network.sh tells the tor
  117. processes to exit after it exits, using CHUTNEY_CONTROLLING_PID. To disable
  118. this functionality, set CHUTNEY_CONTROLLING_PID to 1 or less.
  119. Changing the network address:
  120. Chutney defaults to binding to localhost. To change the IPv4 bind address,
  121. set the CHUTNEY_LISTEN_ADDRESS environment variable. Similarly, change
  122. CHUTNEY_LISTEN_ADDRESS_V6 for IPv6: it defaults to "no IPv6 address".
  123. Setting it to some interface's IP address allows us to make the simulated
  124. Tor network available on the network.
  125. IPv6 support for both Tor and Chutney is a work in progress. Currently,
  126. chutney verifies IPv6 client, bridge client (?), hidden service, and exit
  127. connections. It does not use IPv6 SOCKSPorts or HiddenServicePorts.
  128. Using DNS:
  129. Chutney verify uses IP addresses by default. It does not need to look up
  130. any hostnames. We recommend that chutney users disable DNS using --offline
  131. or CHUTNEY_DNS_CONF=/dev/null , because any DNS failures causes tests to
  132. fail. Chutney's DNS queries also produce external traffic in a predictable
  133. pattern.
  134. If you want to use a hostname with CHUTNEY_LISTEN_ADDRESS[_V6], or you want
  135. to run tests that use DNS, set CHUTNEY_DNS_CONF to the path to a file in
  136. resolv.conf format. Chutney's default of /etc/resolv.conf should be fine for
  137. most UNIX-based operating systems. If your tor is compiled with a different
  138. default, use --dns-resolv-conf-default or CHUTNEY_DNS_CONF="".
  139. When the CHUTNEY_DNS_CONF file does not exist, or is a broken symlink,
  140. chutney uses /dev/null instead. This is a workaround for bugs in tor's
  141. use of eventdns. For example, macOS deletes the resolv.conf file when it
  142. thinks the network is down: this can make tor exits reject all traffic,
  143. even if a working DNS server is running on 127.0.0.1:53.
  144. When tor has no working name servers (including --offline mode), it can
  145. crash on SETCONF. (Chutney does not use SETCONF, but some external tor
  146. controllers do.) To avoid this crash, set CHUTNEY_DNS_CONF to a file
  147. containing a working name server address. For your convenience, chutney
  148. provides a local resolv.conf file containing IPv4, IPv6, and "localhost".
  149. Use --dns-conf resolv.conf (relative paths work).
  150. The configuration files:
  151. networks/basic holds the configuration for the network you're configuring
  152. above. It refers to some torrc template files in torrc_templates/.
  153. The working files:
  154. chutney sticks its working files, including all data directories, log
  155. files, etc, in ./net/. Each tor instance gets a subdirectory of net/nodes.
  156. You can override the directory "./net" with the CHUTNEY_DATA_DIR
  157. environment variable.
  158. Test scripts:
  159. The test scripts are stored in the "scripts/chutney_tests" directory. These
  160. Python files must define a "run_test(network)" function. Files starting with
  161. an underscore ("_") are ignored.
  162. Test scripts can be run using the following syntax:
  163. ./chutney <script-name> networks/<network-name>
  164. The chutney verify command is implemented using a test script.
  165. Test scripts in the test directory with the same name as standard commands
  166. are run instead of that standard command. This allows expert users to replace
  167. the standard chutney commands with modified versions.