Tor documentation

The simple version: Tor provides a distributed network of servers ("onion routers"). Users bounce their TCP streams (web traffic, FTP, SSH, etc.) around the routers. This makes it hard for recipients, observers, and even the onion routers themselves to track the source of the stream.

The complex version: Onion Routing is a connection-oriented anonymizing communication service. Users choose a source-routed path through a set of nodes, and negotiate a "virtual circuit" through the network, in which each node knows its predecessor and successor, but no others. Traffic flowing down the circuit is unwrapped by a symmetric key at each node, which reveals the downstream node.

Why should I use Tor?

Individuals need Tor for privacy:

Journalists and NGOs need Tor for safety:

Companies need Tor for business security:

Governments need Tor for traffic-analysis-resistant communication:

Law enforcement needs Tor for safety:

Does the idea of sharing the Tor network with all of these groups bother you? It shouldn't -- you need them for your security.

Should I run a client or a server?

You can run Tor in either client mode or server mode. By default, everybody is a client. This means you don't relay traffic for anybody but yourself.

If you have less than 1Mbit in both directions, you should stay a client. Otherwise, please consider being a server, to help out the network. (Currently each server uses 20-150 gigabytes of traffic per month; but that may go up.)

Note that you can be a server without allowing users to make connections from your computer to the outside world. This is called being a middleman server.

Benefits of running a server include:

You can read more about setting up Tor as a server below.

Installing Tor

You can get the latest releases here.

If you got Tor from a tarball, unpack it: tar xzf tor-0.0.7.tar.gz; cd tor-0.0.7. Run ./configure, then make, and then make install (as root if necessary). Then you can launch tor from the command-line by running tor.

If you got Tor from the Win32 .exe file, you can just click-click it (you may need to install OpenSSL 0.9.7 first, if you get an error about missing libeay32.dll.) You might also want to run Tor in a dos window, so you can see its logs, and see its error messages if it crashes. If you don't want the default configuration, fetch the torrc, edit it, and use tor.exe -f torrc.

Otherwise, if you got it prepackaged (e.g. in the Debian package or Gentoo package), these steps are already done for you, and you may even already have Tor started in the background (logging to /var/log/something).

In any case, see the next section for what to do with it now that you've got it running.

Configuring a client

Tor comes configured as a client by default. It uses a built-in default configuration file, and most people won't need to change any of the settings.

The only setting you might need to change is "SocksBindAddress". By default, your Tor client only listens for applications that connect from localhost. Connections from other computers are refused. If you want to torify applications on different computers than the Tor client, you should copy torrc.sample to torrc (it's installed by default to /usr/local/etc/tor/), change the SocksBindAddress line to 0.0.0.0, and then hup or restart Tor.

To test if it's working, point your browser to socks4 or socks5 proxy at localhost port 9050. In Mozilla, this is in edit|preferences|advanced|proxies. Go to http://www.junkbusters.com/cgi-bin/privacy and see what IP it says you're coming from. (If you have a personal firewall, be sure to allow local connections to port 9050. If your firewall blocks outgoing connections, punch a hole so it can connect to TCP *:9001-9004 and *:9030-9033. If you're using Safari as your browser, keep in mind that OS X before 10.3 claims to support socks but does not.)

Once you've tested that it works, you should install privoxy, which is a filtering web proxy that integrates well with Tor. Add the line
forward-socks4a / localhost:9050 .
(don't forget the dot) to its config file (you can just add it to the top). Then change your mozilla to http proxy at localhost port 8118 (and no socks proxy). You should also set your SSL proxy to the same thing, to hide your https traffic. Using privoxy is necessary because Mozilla leaks your DNS requests when it uses a socks proxy directly. Privoxy also gives you good html scrubbing.

You might want to use Tor with an application that doesn't support socks directly. In this case, you should look at using tsocks to dynamically replace the system calls in your program to route through Tor. If you want to use socks4a, consider using socat (specific instructions are on this hidden service url).

(Windows doesn't have tsocks; instead, you can try SocksCap or the Hummingbird SOCKS client.)

Configuring a server

We're looking for people with reasonably reliable Internet connections, that have at least 1Mbit each way. Currently we don't use all of that, but we want it available for burst traffic.

(The Tor server doesn't need to be run as root, and doesn't need any special system permissions or kernel mods. You should probably run it as its own user though, especially if you run an identd service too. If you're the paranoid sort, feel free to put it into a chroot jail.)

First, copy torrc.sample to torrc (by default it's in /usr/local/etc/tor/), and edit the middle part. Create the DataDirectory, and make sure it's owned by the uid/gid that will be running tor. Fix your system clock so it's not too far off. Make sure name resolution works. Open a hole in your firewall so outsiders can connect to your ORPort.

Then run tor to generate keys: tor. One of the files generated in your DataDirectory is your 'fingerprint' file. Mail it to tor-ops@freehaven.net.

In that mail, be sure to tell us who you are, so we know whom to contact if there's any problem. Also describe what kind of connectivity the new server will have. If possible, PGP sign your mail.

Once your fingerprint has been approved, you can click here or here and look at the running-routers line to see if your server is part of the network.

You may find the initscript in contrib/tor.sh useful if you want to set up Tor to start at boot.

Configuring a hidden service

Tor allows clients and servers to offer hidden services. That is, you can offer an apache, sshd, etc, without revealing your IP to its users. This works via Tor's rendezvous point design: both sides build a Tor circuit out, and they meet in the middle.

If you're using Tor and Privoxy, you can go to the hidden wiki to see hidden services in action.

To set up a hidden service, copy torrc.sample to torrc (by default it's in /usr/local/etc/tor/), and edit the bottom part. Then run Tor. It will create each HiddenServiceDir you have configured, and it will create a 'hostname' file which specifies the url (xyz.onion) for that service. You can tell people the url, and they can connect to it via their Tor client, assuming they're using a proxy (such as Privoxy) that speaks socks4a.

Setting up your own 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 directory servers, and you need to change the tarball so it points to your directory servers rather than the default ones.