README 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258
  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:
  9. - Python 2.7, or a supported Python 3,
  10. - (we support Python versions that are still getting updates), and
  11. - Tor binaries.
  12. Chutney checks for Tor binaries in this order:
  13. - If you run chutney's tools/test-network.sh from a tor build directory,
  14. (or set the environment variable $TOR_DIR to a tor build directory,)
  15. chutney will automatically detect the tor binaries, or
  16. - If you put the location of the 'tor' and 'tor-gencert' binaries in the
  17. environment variables $CHUTNEY_TOR and $CHUTNEY_TOR_GENCERT, respectively,
  18. chutney will use those binaries, or
  19. - You will need tor and tor-gencert installed somewhere in your path.
  20. Stuff to try:
  21. Automated Setup, Verification, and Shutdown:
  22. ./tools/test-network.sh --flavor basic-min
  23. ./tools/test-network.sh --coverage
  24. ./tools/test-network.sh --tor-path <tor-build-directory>
  25. ./tools/test-network.sh --tor <name-or-path> --tor-gencert <name-or-path>
  26. (--tor-path and $TOR_DIR override --tor and --tor-gencert.)
  27. (The script tries hard to find tor.)
  28. ./tools/test-network.sh --chutney-path <chutney-directory>
  29. (The script is pretty good at finding chutney.)
  30. ./tools/test-network.sh --allow-failures <N>
  31. test-network.sh looks for some tor binaries (either in a nearby build
  32. directory or in your $PATH), configures a comprehensive tor test network,
  33. launches it, then verifies data transmission through it, and cleans up after
  34. itself. Relative paths are supported.
  35. You can modify its configuration using command-line arguments, or use the
  36. chutney environmental variables documented below:
  37. Verification Options:
  38. # repeats bootstrap and verify
  39. --allow-failures CHUTNEY_ALLOW_FAILURES=N
  40. # repeats verify
  41. --rounds CHUTNEY_ROUNDS=N
  42. # makes multiple connections within verify
  43. --connections CHUTNEY_CONNECTIONS=N
  44. Timing Options:
  45. --start-time CHUTNEY_START_TIME=N
  46. --bootstrap-time CHUTNEY_BOOTSTRAP_TIME=N
  47. --stop-time CHUTNEY_STOP_TIME=N
  48. Traffic Options:
  49. --data CHUTNEY_DATA_BYTES=N
  50. --hs-multi-client CHUTNEY_HS_MULTI_CLIENT=N
  51. Address/DNS Options:
  52. --ipv4 CHUTNEY_LISTEN_ADDRESS=IPV4
  53. --ipv6 CHUTNEY_LISTEN_ADDRESS_V6=IPV6
  54. # Chutney uses /etc/resolv.conf if none of these options are set
  55. --dns-conf CHUTNEY_DNS_CONF=PATH
  56. --offline CHUTNEY_DNS_CONF=/dev/null
  57. # Use tor's compile-time default for ServerDNSResolvConfFile
  58. --dns-conf-default CHUTNEY_DNS_CONF=""
  59. Sandbox Options:
  60. --sandbox CHUTNEY_TOR_SANDBOX=N (0 or 1)
  61. Warning Options:
  62. --all-warnings CHUTNEY_WARNINGS_IGNORE_EXPECTED=false
  63. CHUTNEY_WARNINGS_SUMMARY=false
  64. --no-warnings CHUTNEY_WARNINGS_SKIP=true
  65. --only-warnings CHUTNEY_WARNINGS_ONLY=true
  66. Expert Options:
  67. --debug CHUTNEY_DEBUG=true
  68. --coverage USE_COVERAGE_BINARY=true
  69. --dry-run NETWORK_DRY_RUN=true
  70. --quiet ECHO=true
  71. --controlling-pid CHUTNEY_CONTROLLING_PID=N
  72. --net-dir CHUTNEY_DATA_DIR=PATH
  73. (These are advanced options: in the past, they have had long-standing bugs.)
  74. Standard Actions:
  75. ./chutney configure networks/basic
  76. ./chutney start networks/basic
  77. ./chutney status networks/basic
  78. ./chutney wait_for_bootstrap networks/basic
  79. ./chutney verify networks/basic
  80. ./chutney hup networks/basic
  81. ./chutney stop networks/basic
  82. Bandwidth Tests:
  83. ./chutney configure networks/basic-min
  84. ./chutney start networks/basic-min
  85. ./chutney status networks/basic-min
  86. # Send 100MB of data per client connection
  87. CHUTNEY_DATA_BYTES=104857600 ./chutney verify networks/basic-min
  88. ./chutney stop networks/basic-min
  89. If chutney sends at least 5 MB of data, and it takes at least one second,
  90. verify produces performance figures for:
  91. - Single Stream Bandwidth: the speed of the slowest stream, end-to-end
  92. - Overall tor Bandwidth: the sum of the bandwidth across each tor instance
  93. The overall bandwidth approximates the CPU-bound tor performance on the
  94. current machine, assuming tor, chutney, and the OS are multithreaded, and
  95. network performance is infinite.
  96. Connection Tests:
  97. ./chutney configure networks/basic-025
  98. ./chutney start networks/basic-025
  99. ./chutney status networks/basic-025
  100. # Make 5 simultaneous connections from each client through a random exit
  101. CHUTNEY_CONNECTIONS=5 ./chutney verify networks/basic-025
  102. ./chutney stop networks/basic-025
  103. # Run 5 sequential verification rounds
  104. CHUTNEY_ROUNDS=5 ./tools/test-network.sh --flavour basic
  105. HS Connection Tests:
  106. ./chutney configure networks/hs-025
  107. ./chutney start networks/hs-025
  108. ./chutney status networks/hs-025
  109. CHUTNEY_HS_MULTI_CLIENT=1 ./chutney verify networks/hs-025
  110. # Make a connection from each client to each hs
  111. # Default behavior is one client connects to each HS
  112. ./chutney stop networks/hs-025
  113. Bandwidth File Tests:
  114. ./tools/test-network.sh --flavour bwfile
  115. # Warning: Can't open bandwidth file at configured location: /tmp/bwfile
  116. # Create a bwfile with no bandwidths, that is valid for a few days
  117. date +%s > /tmp/bwfile
  118. ./tools/test-network.sh --flavour bwfile
  119. Multiple Tests:
  120. Chutney can allow a certain number of failed tests. You can either set
  121. CHUTNEY_ALLOW_FAILURES or use an --allow-failures command-line option to
  122. control this. Chutney will then reattempt the test, from bootstrap
  123. through shutdown, until either it succeeds, or until it has failed
  124. $CHUTNEY_ALLOW_FAILURES+1 times. The default value is zero, so the default
  125. behavior will not change.
  126. You can also use CHUTNEY_ROUNDS=N to run multiple verification rounds, or
  127. CHUTNEY_CONNECTIONS=N to make multiple connections within each verification
  128. round. Any round or connection failure will fail the current test.
  129. Waiting for the network:
  130. The tools/test-network.sh script uses the chutney wait_for_bootstrap
  131. command to wait for up to CHUTNEY_START_TIME seconds (default: 120), checking
  132. whether the logged bootstrapped status for every node is 100%. It it is,
  133. great: it succeeds. If not, it dumps the bootstrap statuses and exits.
  134. test-network.sh does not exit immediately if a tor node fails to bootstrap.
  135. Instead, it attempts to verify. We'll add an option to fail on tor
  136. bootstrap failure in #20473.
  137. Commands like "chutney verify" start immediately, and keep trying for
  138. CHUTNEY_BOOTSTRAP_TIME seconds (default: 60). If it hasn't been
  139. successful after that time, it fails. If CHUTNEY_BOOTSTRAP_TIME is negative,
  140. the script leaves the network running, and exits after CHUTNEY_START_TIME
  141. (without verifying).
  142. The tools/test-network.sh script waits CHUTNEY_STOP_TIME seconds
  143. after verifying, then exits (default: immediately). If CHUTNEY_STOP_TIME is
  144. negative, the script leaves the network running, and exits after verifying.
  145. If none of these options are negative, test-network.sh tells the tor
  146. processes to exit after it exits, using CHUTNEY_CONTROLLING_PID. To disable
  147. this functionality, set CHUTNEY_CONTROLLING_PID to 1 or less.
  148. Changing the network address:
  149. Chutney defaults to binding to localhost. To change the IPv4 bind address,
  150. set the CHUTNEY_LISTEN_ADDRESS environment variable. Similarly, change
  151. CHUTNEY_LISTEN_ADDRESS_V6 for IPv6: it defaults to "no IPv6 address".
  152. Setting it to some interface's IP address allows us to make the simulated
  153. Tor network available on the network.
  154. IPv6 support for both Tor and Chutney is a work in progress. Currently,
  155. chutney verifies IPv6 client, bridge client (?), hidden service, and exit
  156. connections. It does not use IPv6 SOCKSPorts or HiddenServicePorts.
  157. Using DNS:
  158. Chutney verify uses IP addresses by default. It does not need to look up
  159. any hostnames. We recommend that chutney users disable DNS using --offline
  160. or CHUTNEY_DNS_CONF=/dev/null , because any DNS failures causes tests to
  161. fail. Chutney's DNS queries also produce external traffic in a predictable
  162. pattern.
  163. If you want to use a hostname with CHUTNEY_LISTEN_ADDRESS[_V6], or you want
  164. to run tests that use DNS, set CHUTNEY_DNS_CONF to the path to a file in
  165. resolv.conf format. Chutney's default of /etc/resolv.conf should be fine for
  166. most UNIX-based operating systems. If your tor is compiled with a different
  167. default, use --dns-resolv-conf-default or CHUTNEY_DNS_CONF="".
  168. When the CHUTNEY_DNS_CONF file does not exist, or is a broken symlink,
  169. chutney uses /dev/null instead. This is a workaround for bugs in tor's
  170. use of eventdns. For example, macOS deletes the resolv.conf file when it
  171. thinks the network is down: this can make tor exits reject all traffic,
  172. even if a working DNS server is running on 127.0.0.1:53.
  173. When tor has no working name servers (including --offline mode), it can
  174. crash on SETCONF. (Chutney does not use SETCONF, but some external tor
  175. controllers do.) To avoid this crash, set CHUTNEY_DNS_CONF to a file
  176. containing a working name server address. For your convenience, chutney
  177. provides a local resolv.conf file containing IPv4, IPv6, and "localhost".
  178. Use --dns-conf resolv.conf (relative paths work).
  179. The tor sandbox:
  180. Chutney can run with the tor seccomp sandbox enabled. But if tor's sandbox
  181. is broken on your local version of glibc, you can set CHUTNEY_TOR_SANDBOX=0
  182. to disable the sandbox. If CHUTNEY_TOR_SANDBOX is unset, Sandbox defaults
  183. to 1 on Linux, and 0 on other platforms.
  184. The configuration files:
  185. networks/basic holds the configuration for the network you're configuring
  186. above. It refers to some torrc template files in torrc_templates/.
  187. Chutney uses a templating system to produce torrc files from the templates.
  188. These torrc files can be modified using various chutney options.
  189. The working files:
  190. chutney sticks its working files, including all generated torrc files,
  191. data directories, log files, etc, in ./net/. Each tor instance gets a
  192. subdirectory of net/nodes.
  193. You can override the directory "./net" with the CHUTNEY_DATA_DIR
  194. environment variable.
  195. Test scripts:
  196. The test scripts are stored in the "scripts/chutney_tests" directory. These
  197. Python files must define a "run_test(network)" function. Files starting with
  198. an underscore ("_") are ignored.
  199. Test scripts can be run using the following syntax:
  200. ./chutney <script-name> networks/<network-name>
  201. The chutney verify command is implemented using a test script.
  202. Test scripts in the test directory with the same name as standard commands
  203. are run instead of that standard command. This allows expert users to replace
  204. the standard chutney commands with modified versions.