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:

• Privacy in web browsing -- both from the remote website (so it can't track and sell your behavior), and similarly from your local ISP.
• Safety in web browsing: if your local government doesn't approve of its citizens visiting certain websites, they may monitor the sites and put readers on a list of suspicious persons.
• Circumvention of local censorship: connect to resources (news sites, instant messaging, etc) that are restricted from your ISP/school/company/government.
• Socially sensitive communication: chat rooms and web forums for rape and abuse survivors, or people with illnesses.

Journalists and NGOs need Tor for safety:

• Allowing dissidents and whistleblowers to communicate more safely.
• Censorship-resistant publication, such as making available your home-made movie anonymously via a Tor hidden service; and reading, e.g. of news sites not permitted in some countries.
• Allowing your workers to check back with your home website while they're in a foreign country, without notifying everybody nearby that they're working with your organization.

Companies need Tor for business security:

• Competitive analysis: browse the competition's website safely.
• Protecting collaborations of sensitive business units or partners.
• Protecting procurement suppliers or patterns.
• Putting the "P" back in "VPN": traditional VPNs reveal the exact amount and frequency of communication. Which locations have employees working late? Which locations have employees consulting job-hunting websites? Which research groups are communicating with your company's patent lawyers?

Governments need Tor for traffic-analysis-resistant communication:

• Open source intelligence gathering (hiding individual analysts is not enough -- the organization itself may be sensitive).
• Defense in depth on open and classified networks -- networks with a million users (even if they're all cleared) can't be made safe just by hardening them to external threat.
• Dynamic and semi-trusted international coalitions: the network can be shared without revealing the existence or amount of communication between all parties.
• Networks partially under known hostile control: to block communications, the enemy must take down the whole network.
• Politically sensitive negotiations.
• Road warriors.
• Protecting procurement patterns.
• Anonymous tips.

Law enforcement needs Tor for safety:

• Allowing anonymous tips or crime reporting
• Allowing agents to observe websites without notifying them that they're being observed (or, more broadly, without having it be an official visit from law enforcement).
• Surveillance and honeypots (sting operations)

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 your computer doesn't have a routable IP address or you're using a modem, 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, depending on its capacity and its rate limiting configuration.)

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:

• Clients are generally limited to 100KB/s (and in practice, sometimes much less), whereas servers can inject or receive as much traffic as they want.
• You may get stronger anonymity, since your destination can't know whether connections relayed through your computer originated at your computer or not.
• You can also get stronger anonymity by configuring your Tor clients to use your Tor server for entry or for exit.
• You're helping me with development and scalability testing.
• You're helping your fellow Internet users by providing a larger network. Also, having servers in many different pieces of the Internet gives users more robustness against curious telcos and brute force attacks.

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.9.tar.gz; cd tor-0.0.9. 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 20 kilobytes/s each way. If you frequently have a lot of packet loss or really high latency, we can't handle your server yet. Otherwise, please help out!

Other things to note:

• Tor has built-in support for rate limiting; see BandwidthRate and BandwidthBurst config options. Further, if you have lots of capacity but don't want to spend that many bytes per month, check out the Accounting and Hibernation features. See the FAQ for details.
• It's fine if the server goes offline sometimes. The directories notice this quickly and stop advertising the server. Just try to make sure it's not too often, since connections through the server when it disconnects will break.
• We can handle servers with dynamic IPs just fine, as long as the server itself knows its IP. If your server is behind a NAT and it doesn't know its own IP (e.g. it has an IP of 192.168.x.y), then we can't use it as a server yet. (If you want to set your Address config option to dyndns DNS voodoo and port forward to get around this, feel free. If you write a howto, even better.)
• Your server will passively estimate and publish its recent capacity. Client paths are chosen weighted by this capacity, so high-bandwidth servers will attract more paths than low-bandwidth ones. That's why having even low-bandwidth servers is useful too.

To set up a Tor server, do the following steps after installing Tor. (These instructions are Unix-centric; if you're excited about working with us to get a Tor server working on Windows, let us know and we'll work with you to fix whatever bugs come up.)

• 1. Copy torrc.sample to torrc (in the default configuration this means copy /usr/local/etc/tor/torrc.sample to /usr/local/etc/tor/torrc), and edit the bottom 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.
• 2. Run tor to generate keys and then exit: tor --list-fingerprint. Send mail to tor-ops@freehaven.net including a) this key fingerprint, b) who you are, so we know whom to contact if there's any problem, and c) what kind of connectivity the new server will have. If possible, PGP sign your mail.
• 3. If you are using a firewall, open a hole in your firewall so incoming connections can reach the ports you configured (i.e. ORPort, plus DirPort if you enabled it). Make sure outgoing connections can reach at least ports 80, 443, and 9001-9033 (to get to other onion routers), plus any other addresses or ports your exit policy allows.
• 4. Start your server: tor. If it logs any warnings, address them.

• 1. Make a separate user to run the server. If you installed the deb or the rpm, this is already done. Otherwise, you can do it by hand. (The Tor server doesn't need to be run as root, so it's good practice to not run it as root. Running as a 'tor' user avoids issues with identd and other services that detect user name. If you're the paranoid sort, feel free to put Tor into a chroot jail.)
• 2. Decide what exit policy you want. By default your server allows access to many popular services, but we restrict some (such as port 25) due to abuse potential. You might want an exit policy that is either less restrictive or more restrictive; edit your torrc appropriately. If you choose a particularly open exit policy, you might want to make sure your upstream or ISP is ok with that choice.
• 3. You may find the initscripts in contrib/tor.sh or contrib/torctl useful if you want to set up Tor to start at boot. Let us know which script you find more useful.
• 4. Consider setting your hostname to 'anonymous' or 'proxy' or 'tor-proxy' if you can, so when other people see the address in their web logs or whatever, they will more quickly understand what's going on.
• 5. If you're not running anything else on port 80 or port 443, please consider setting up port-forwarding and advertising these low-numbered ports as your Tor server. This will help allow users behind particularly restrictive firewalls to access the Tor network. See section 4 of the FAQ for details of how to set this up.

You can click here or here and look at the router-status line to see if your server is part of the network. It will be listed by nickname once we have added your server to the list of known servers; otherwise it is listed only by its fingerprint.

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 middle 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 configure each client and server so it knows about your directory servers rather than the default ones.

• 1: Grab the latest release. Use at least 0.0.9.
• 2: For each directory server you want,
  • 2a: Set it up as a server (see "setting up a server" above), with a least ORPort, DirPort, DataDirectory, and Nickname defined. Set "AuthoritativeDirectory 1".
  • 2b: Set "RecommendedVersions" to a comma-separated list of acceptable versions of the code for clients and servers to be running.
  • 2c: Run it: tor --list-fingerprint if your torrc is in the default place, or tor -f torrc --list-fingerprint to specify one. This will generate your keys and output a fingerprint line.
• 3: Now you need to teach clients and servers to use the new dirservers. For each fingerprint, add a line like
  DirServer 18.244.0.114:80 719B E45D E224 B607 C537 07D0 E214 3E2D 423E 74CF
  to the torrc of each client and server who will be using your network.
• 4: Create a file called approved-routers in the DataDirectory of each directory server. Collect the 'fingerprint' lines from each server (including directory servers), and include them (one per line) in each approved-routers file. You can hup the tor process for each directory server to reload the approved-routers file (so you don't have to restart the process).