Improve instructions for how to run a testing Tor network

Improve instructions in the wiki FAQ for running private networks.

The current FAQ entry explains manual steps that Chutney and Shadow do automatically and that nobody should have to worry about. A more useful FAQ entry would explain how to get started with Chutney and Shadow and then link to their tutorials for more detailed instructions, if available.

changed milestone to %Tor: 0.2.5.x-final

added SponsorF20131031 component::core tor/tor milestone::Tor: 0.2.5.x-final priority::medium resolution::fixed status::closed tor-relay type::enhancement labels

Trac:
Milestone: N/A to Tor: 0.2.5.x-final
Keywords: SponsorF20131031 deleted, SponsorF20131031 tor-relay added

Suggested new text for https://trac.torproject.org/projects/tor/wiki/doc/TorFAQ#HowdoIsetupmyownprivateTornetwork

How do I set up my own private Tor network?

If you want to experiment locally with your own network, or you're cut
off from the Internet and want to be able to mess with Tor still, then
you may want to set up your own separate Tor network.

To set up your own Tor network, you need to run your own authoritative
directory servers, and your clients and relays must be configured so
they know about your directory servers rather than the default public
ones.

Apart from the somewhat tedious method of manually configuring a
couple of directory authorities, relays and clients there are two
separate tools that could help. One is Chutney, the other is Shadow.

[Chutney](https://gitweb.torproject.org/chutney.git) is a tool for
configuring, controlling and running tests on a testing Tor
network. It requires that you have Tor and Python (2.5 or later)
installed on your system. You can use Chutney to create a testing
network by generating Tor configuration files (torrc) and necssary
keys (for the directory authorities). Then you can let Chutney start
your Tor authorities, relays and clients and wait for the network to
bootstrap. Finally, you can have Chutney run tests on your network to
see which things work and which do not. Chutney is typically used for
running a testing network with about 10 instances of Tor. Every
instance of Tor binds to one or two ports on localhost (127.0.0.1) and
all Tor communication is done over the loopback interface. The
[https://gitweb.torproject.org/chutney.git/blob/HEAD:/README Chutney
README] is a good starting point for getting it up and running.

[Shadow](https://github.com/shadow/shadow) is a network simulator that
can run Tor through its Scallion plug-in. It's typically used for
running load and performance tests on substantially larger Tor test
networks than what's feasible with Chutney. A large Shadow network is
on the size of thousands of instances of Tor. Also, Shadow controls
the time of the simulation with the effect that time consuming tests
can be done more efficiently than in an ordinary testing network. The
[Shadow README](https://github.com/shadow/shadow/blob/master/README)
is a good starting point for getting started.

Trac:
Status: new to needs_review

Sounds like a useful starting point for people trying to mess with private Tor networks. Nick, Rob, is there anything you'd want to add? If not, I'd say, let's copy this text to the wiki page and call the task done. (Thanks!)

Trac:
Cc: N/A to nickm, robgjansen

I would change the Shadow part to the following:

Shadow is a network simulator that can run Tor through its Scallion plug-in. Although it's typically used for running load and performance tests on substantially larger Tor test networks than what's feasible with Chutney, it also makes for an excellent debugging tool since you can run completely deterministic experiments. A large Shadow network is on the size of thousands of instances of Tor, and you can run experiments out of the box using one of Shadow's several included scallion experiment configurations. Shadow can be run on any linux machine without root, and can also run on EC2 using a pre-configured image. Also, Shadow controls the time of the simulation with the effect that time consuming tests can be done more efficiently than in an ordinary testing network. The Shadow wiki and Shadow website, are good places to get started.

https://trac.torproject.org/projects/tor/wiki/doc/TorFAQ#HowdoIsetupmyownprivateTornetwork updated. Thanks Rob!

Trac:
Resolution: N/A to fixed
Status: needs_review to closed

What advantages does Chutney have over Shadow? From what I can gather from the explanation on this ticket, Shadow scales better, allows for deterministic tests... what does Chutney do better?

Trac:
Username: obvio171

A closed ticket is the wrong place to have such a conversation. But in a single sentence: Chutney allows you to run the unchanged tor executable whereas Shadow adds in another abstraction level that might unintentionally break stuff. There are probably more aspects. But again, this conversation shouldn't be on this ticket, but probably on a mailing list.

Got it. Thanks!

Trac:
Username: obvio171

closed

moved to tpo/core/tor#8533 (closed)