|
= Tor Test Networks using Chutney: A Guide =
|
|
# Tor Test Networks using Chutney: A Guide
|
|
|
|
|
|
A guide to creating Tor test networks with chutney.
|
|
A guide to creating Tor test networks with chutney.
|
|
(This page is an early draft outline of the documentation and functionality we want to have.)
|
|
(This page is an early draft outline of the documentation and functionality we want to have.)
|
|
|
|
|
|
Features which are not yet implemented are marked NYI, with a corresponding Trac ticket number and link (if it exists).
|
|
Features which are not yet implemented are marked NYI, with a corresponding Trac ticket number and link (if it exists).
|
|
|
|
|
|
== Chutney README ==
|
|
## Chutney README
|
|
|
|
|
|
The chutney README gives detailed descriptions and command-line examples for each chutney feature:
|
|
The chutney README gives detailed descriptions and command-line examples for each chutney feature:
|
|
|
|
|
|
https://gitweb.torproject.org/chutney.git/tree/README
|
|
https://gitweb.torproject.org/chutney.git/tree/README
|
|
|
|
|
|
== Testing an installed Tor version ==
|
|
## Testing an installed Tor version
|
|
=== Run a Single Test ===
|
|
### Run a Single Test
|
|
|
|
|
|
Get the latest version of chutney:
|
|
Get the latest version of chutney:
|
|
|
|
|
... | @@ -22,8 +22,8 @@ If you already have tor installed, you can run a test network: |
... | @@ -22,8 +22,8 @@ If you already have tor installed, you can run a test network: |
|
|
|
|
|
chutney/tools/test-network.sh
|
|
chutney/tools/test-network.sh
|
|
|
|
|
|
== Testing while Building Tor from Source ==
|
|
## Testing while Building Tor from Source
|
|
=== Run a Single Test ===
|
|
### Run a Single Test
|
|
git clone !https://git.torproject.org/tor.git
|
|
git clone !https://git.torproject.org/tor.git
|
|
|
|
|
|
git clone !https://git.torproject.org/chutney.git
|
|
git clone !https://git.torproject.org/chutney.git
|
... | @@ -39,27 +39,27 @@ make test-network |
... | @@ -39,27 +39,27 @@ make test-network |
|
----
|
|
----
|
|
The ./configure step will fail if there are missing libraries, and will indicate which those are. Run ./configure again after installing all the necessary libraries.
|
|
The ./configure step will fail if there are missing libraries, and will indicate which those are. Run ./configure again after installing all the necessary libraries.
|
|
|
|
|
|
==== Setting the CHUTNEY_PATH environmental variable ====
|
|
#### Setting the CHUTNEY_PATH environmental variable
|
|
Recent versions of Tor (0.2.7.3-alpha (?) and later) will autodetect the $CHUTNEY_PATH if the chutney directory is next to the tor directory (#16903).
|
|
Recent versions of Tor (0.2.7.3-alpha (?) and later) will autodetect the $CHUTNEY_PATH if the chutney directory is next to the tor directory (#16903).
|
|
|
|
|
|
If your tor and chutney source directories are not side-by-side, you'll neeed to set the CHUTNEY_PATH environmental variable to the path to the chutney directory (not the script itself).
|
|
If your tor and chutney source directories are not side-by-side, you'll neeed to set the CHUTNEY_PATH environmental variable to the path to the chutney directory (not the script itself).
|
|
|
|
|
|
You can do this for one command:
|
|
You can do this for one command:
|
|
|
|
|
|
* CHUTNEY_PATH=/path/to/chutney/directory make test-network ''(in many shells, or [https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-a-linux-vps see this article for a more detailed explanation])''
|
|
* CHUTNEY_PATH=/path/to/chutney/directory make test-network _(in many shells, or [see this article for a more detailed explanation](https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-a-linux-vps))_
|
|
|
|
|
|
Or while the shell is running:
|
|
Or while the shell is running:
|
|
|
|
|
|
* export CHUTNEY_PATH=/path/to/chutney/directory ''(in bash and similar shells, or [http://www.tcsh.org/EnvironmentVariable see this article for tcsh / csh], or consult your shell's documentation)''
|
|
* export CHUTNEY_PATH=/path/to/chutney/directory _(in bash and similar shells, or [see this article for tcsh / csh](http://www.tcsh.org/EnvironmentVariable), or consult your shell's documentation)_
|
|
|
|
|
|
Or for all future shells:
|
|
Or for all future shells:
|
|
|
|
|
|
* [http://unix.stackexchange.com/questions/117467/how-to-permanently-set-environmental-variables See this article]
|
|
* [See this article](http://unix.stackexchange.com/questions/117467/how-to-permanently-set-environmental-variables)
|
|
|
|
|
|
==== Test Functionality ====
|
|
#### Test Functionality
|
|
Recent versions of Tor (0.2.7.3-alpha (?) and later) run a comprehensive test of most functionality, including authorities, bridges, clients, exits, and hidden services (but no IPv6 for compatibility reasons). See tickets #16945 (tor) & #16946 (chutney). Older versions of Tor run a simpler test of authorities, clients, and exits.
|
|
Recent versions of Tor (0.2.7.3-alpha (?) and later) run a comprehensive test of most functionality, including authorities, bridges, clients, exits, and hidden services (but no IPv6 for compatibility reasons). See tickets #16945 (tor) & #16946 (chutney). Older versions of Tor run a simpler test of authorities, clients, and exits.
|
|
|
|
|
|
==== Resolving Test Failures ====
|
|
#### Resolving Test Failures
|
|
Chutney occasionally fails to bootstrap or verify. Sometimes, and on some platforms / machines, bootstrap is slower than we expect (25 seconds in 0.2.6 - 0.2.7.2-alpha), causing intermittent failures.
|
|
Chutney occasionally fails to bootstrap or verify. Sometimes, and on some platforms / machines, bootstrap is slower than we expect (25 seconds in 0.2.6 - 0.2.7.2-alpha), causing intermittent failures.
|
|
|
|
|
|
Recent tor versions (#16952, merge pending, 0.2.7.3-alpha?):
|
|
Recent tor versions (#16952, merge pending, 0.2.7.3-alpha?):
|
... | @@ -71,9 +71,9 @@ These changes make src/test/test-network.sh robust against intermittment failure |
... | @@ -71,9 +71,9 @@ These changes make src/test/test-network.sh robust against intermittment failure |
|
|
|
|
|
However, sometimes chutney fails to launch due to a persistent error. The most common issue is having a previous chutney network active. Old chutney networks are typically killed by chutney/tools/bootstrap-network.sh using chutney stop, but sometimes this doesn't happen. The tor processes launched by chutney can be found using a command like `ps auxwww | grep chutney | grep tor`. Ensure each pid doesn't belong to a process you want, like a system tor or an unrelated process, then kill each chutney tor pid using `kill`. Alternately, each tor instance's pid files can be found in the chutney/net/nodes directory. (Old nodes directories are renamed using an increasing numeric timestamp as a suffix.)
|
|
However, sometimes chutney fails to launch due to a persistent error. The most common issue is having a previous chutney network active. Old chutney networks are typically killed by chutney/tools/bootstrap-network.sh using chutney stop, but sometimes this doesn't happen. The tor processes launched by chutney can be found using a command like `ps auxwww | grep chutney | grep tor`. Ensure each pid doesn't belong to a process you want, like a system tor or an unrelated process, then kill each chutney tor pid using `kill`. Alternately, each tor instance's pid files can be found in the chutney/net/nodes directory. (Old nodes directories are renamed using an increasing numeric timestamp as a suffix.)
|
|
|
|
|
|
''NYI: Better yet, make these instructions part of the chutney failure message when some tor processes fail to launch. (#17002)''
|
|
_NYI: Better yet, make these instructions part of the chutney failure message when some tor processes fail to launch. (#17002)_
|
|
|
|
|
|
=== Run Comprehensive Tests ===
|
|
### Run Comprehensive Tests
|
|
git clone !https://git.torproject.org/tor.git
|
|
git clone !https://git.torproject.org/tor.git
|
|
|
|
|
|
git clone !https://git.torproject.org/chutney.git
|
|
git clone !https://git.torproject.org/chutney.git
|
... | @@ -103,15 +103,15 @@ IPv6 Test Suite: only run if ping6 ::1 works. |
... | @@ -103,15 +103,15 @@ IPv6 Test Suite: only run if ping6 ::1 works. |
|
* hs-ipv6: authorities, ipv4/ipv6 non-exit relays, ipv6 hidden service, ipv4 hs client, ipv6 hs client
|
|
* hs-ipv6: authorities, ipv4/ipv6 non-exit relays, ipv6 hidden service, ipv4 hs client, ipv6 hs client
|
|
* single-onion-ipv6: authorities, ipv4/ipv6 non-exit relays, ipv6 single onion service, ipv4 hs client, ipv6 hs client
|
|
* single-onion-ipv6: authorities, ipv4/ipv6 non-exit relays, ipv6 single onion service, ipv4 hs client, ipv6 hs client
|
|
|
|
|
|
''NYI: #17011 - test actual IPv6 connectivity (not just IPv4 on IPv6 instances); #16971 - remove requirement for IPv6 DNS on IPv6 exits.''
|
|
_NYI: #17011 - test actual IPv6 connectivity (not just IPv4 on IPv6 instances); #16971 - remove requirement for IPv6 DNS on IPv6 exits._
|
|
|
|
|
|
Mixed Version Test Suite: only run if a stable version of tor exists. ''NYI: try harder to find one (#17015)''
|
|
Mixed Version Test Suite: only run if a stable version of tor exists. _NYI: try harder to find one (#17015)_
|
|
|
|
|
|
* mixed: mixed authorities, mixed exit relays, mixed clients
|
|
* mixed: mixed authorities, mixed exit relays, mixed clients
|
|
|
|
|
|
Log (.log) and result (.trs) files are available in the test_network_log directory in the build directory.
|
|
Log (.log) and result (.trs) files are available in the test_network_log directory in the build directory.
|
|
|
|
|
|
== Testing using the Tor Test Network Script ==
|
|
## Testing using the Tor Test Network Script
|
|
tor/src/test/test-network.sh
|
|
tor/src/test/test-network.sh
|
|
|
|
|
|
List script arguments and corresponding chutney environmental variables in a table
|
|
List script arguments and corresponding chutney environmental variables in a table
|
... | @@ -120,7 +120,7 @@ List templates in a table |
... | @@ -120,7 +120,7 @@ List templates in a table |
|
|
|
|
|
Describe performance testing results, and what they do and don't mean (localhost, no network hardware involved, more parallelism than you'll get as a relay)
|
|
Describe performance testing results, and what they do and don't mean (localhost, no network hardware involved, more parallelism than you'll get as a relay)
|
|
|
|
|
|
== Testing using Chutney Commands ==
|
|
## Testing using Chutney Commands
|
|
chutney/chutney
|
|
chutney/chutney
|
|
|
|
|
|
Manually configure a network, a minimal set of steps similar to what tor/src/test/test-network.sh does
|
|
Manually configure a network, a minimal set of steps similar to what tor/src/test/test-network.sh does
|
... | @@ -129,13 +129,13 @@ List chutney commands in a table |
... | @@ -129,13 +129,13 @@ List chutney commands in a table |
|
|
|
|
|
Reference environmental variables and templates from previous section
|
|
Reference environmental variables and templates from previous section
|
|
|
|
|
|
== Other Usability Improvements ==
|
|
## Other Usability Improvements
|
|
''NYI: There are some minor changes to chutney which would make it much more usable, such as sensible error messages on failure. Let's work out which of these we can knock over quickly. See the full list of proposed chutney changes in #16949.''
|
|
_NYI: There are some minor changes to chutney which would make it much more usable, such as sensible error messages on failure. Let's work out which of these we can knock over quickly. See the full list of proposed chutney changes in #16949._
|
|
|
|
|
|
== Modifying Chutney Tests ==
|
|
## Modifying Chutney Tests
|
|
The torrc templates and test network configurations included with chutney can be modified using any text editor.
|
|
The torrc templates and test network configurations included with chutney can be modified using any text editor.
|
|
|
|
|
|
=== Modifying torrc Templates ===
|
|
### Modifying torrc Templates
|
|
chutney/torrc_templates
|
|
chutney/torrc_templates
|
|
|
|
|
|
The torrc template files use the tor options syntax, with the addition of a few templating commands, such as file includes. Some template expansions are performed to make configuration easier. The most important template expansion creates a list of test network authorities in every torrc file.
|
|
The torrc template files use the tor options syntax, with the addition of a few templating commands, such as file includes. Some template expansions are performed to make configuration easier. The most important template expansion creates a list of test network authorities in every torrc file.
|
... | @@ -144,7 +144,7 @@ List templating commands |
... | @@ -144,7 +144,7 @@ List templating commands |
|
|
|
|
|
List "magic" expansion operations, including the one done in the launch script
|
|
List "magic" expansion operations, including the one done in the launch script
|
|
|
|
|
|
=== Modifying Test Network Configurations ===
|
|
### Modifying Test Network Configurations
|
|
chutney/networks
|
|
chutney/networks
|
|
|
|
|
|
How this currently works:
|
|
How this currently works:
|
... | @@ -153,7 +153,7 @@ How this currently works: |
... | @@ -153,7 +153,7 @@ How this currently works: |
|
* tags identify clients?, exits and hidden services so chutney can run tests for each client and each hidden service (exits are chosen at random) (there are some subtleties I'm missing here about different kinds of tags)
|
|
* tags identify clients?, exits and hidden services so chutney can run tests for each client and each hidden service (exits are chosen at random) (there are some subtleties I'm missing here about different kinds of tags)
|
|
* other things in current files I've forgotten
|
|
* other things in current files I've forgotten
|
|
|
|
|
|
How this could work: ''(NYI: #16954)''
|
|
How this could work: _(NYI: #16954)_
|
|
|
|
|
|
Refactor the existing chutney templates so it's easier to mix and match particular authority, middle relay, client (standard, bridge, IPv6 bridge) and endpoint (exit, hidden service) nodes. Also make version mixing easier. Have a replaceable minimal default? 3 authorities, 1 client, 1 bridge client, 1 bridge, 1 middle, 1 exit, 1 hs
|
|
Refactor the existing chutney templates so it's easier to mix and match particular authority, middle relay, client (standard, bridge, IPv6 bridge) and endpoint (exit, hidden service) nodes. Also make version mixing easier. Have a replaceable minimal default? 3 authorities, 1 client, 1 bridge client, 1 bridge, 1 middle, 1 exit, 1 hs
|
|
|
|
|
... | | ... | |