tor-doc.html 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346
  1. <html>
  2. <head>
  3. <title>Tor: an anonymizing overlay network for TCP</title>
  4. <meta name="Author" content="Roger Dingledine">
  5. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  6. <meta http-equiv="Content-Style-Type" content="text/css">
  7. <link rel="stylesheet" type="text/css" href="tor-doc.css">
  8. </head>
  9. <body>
  10. <h1><a href="http://freehaven.net/tor/">Tor</a> documentation</h1>
  11. <p>The simple version: Tor provides a distributed network of servers
  12. ("onion routers"). Users bounce their TCP streams (web traffic, FTP, SSH,
  13. etc.) around the routers. This makes it hard for recipients, observers, and
  14. even the onion routers themselves to track the source of the stream.</p>
  15. <p>The complex version: Onion Routing is a connection-oriented anonymizing
  16. communication service. Users choose a source-routed path through a set of
  17. nodes, and negotiate a "virtual circuit" through the network, in which
  18. each node knows its predecessor and successor, but no others. Traffic
  19. flowing down the circuit is unwrapped by a symmetric key at each node,
  20. which reveals the downstream node.</p>
  21. <a name="why"></a>
  22. <h2>Why should I use Tor?</h2>
  23. <p>Individuals need Tor for privacy:
  24. <ul>
  25. <li>Privacy in web browsing -- both from the remote website (so it can't
  26. track and sell your behavior), and similarly from your local ISP.
  27. <li>Safety in web browsing: if your local government doesn't approve
  28. of its citizens visiting certain websites, they may monitor the sites
  29. and put readers on a list of suspicious persons.
  30. <li>Circumvention of local censorship: connect to resources (news
  31. sites, instant messaging, etc) that are restricted from your
  32. ISP/school/company/government.
  33. <li>Socially sensitive communication: chat rooms and web forums for
  34. rape and abuse survivors, or people with illnesses.
  35. </ul>
  36. <p>Journalists and NGOs need Tor for safety:
  37. <ul>
  38. <li>Allowing dissidents and whistleblowers to communicate more safely.
  39. <li>Censorship-resistant publication, such as making available your
  40. home-made movie anonymously via a Tor <a href="#hidden-service">hidden
  41. service</a>; and reading, e.g. of news sites not permitted in some
  42. countries.
  43. <li>Allowing your workers to check back with your home website while
  44. they're in a foreign country, without notifying everybody nearby that
  45. they're working with your organization.
  46. </ul>
  47. <p>Companies need Tor for business security:
  48. <ul>
  49. <li>Competitive analysis: browse the competition's website safely.
  50. <li>Protecting collaborations of sensitive business units or partners.
  51. <li>Protecting procurement suppliers or patterns.
  52. <li>Putting the "P" back in "VPN": traditional VPNs reveal the exact
  53. amount and frequency of communication. Which locations have employees
  54. working late? Which locations have employees consulting job-hunting
  55. websites? Which research groups are communicating with your company's
  56. patent lawyers?
  57. </ul>
  58. <p>Governments need Tor for traffic-analysis-resistant communication:
  59. <ul>
  60. <li>Open source intelligence gathering (hiding individual analysts is
  61. not enough -- the organization itself may be sensitive).
  62. <li>Defense in depth on open <em>and classified</em> networks -- networks
  63. with a million users (even if they're all cleared) can't be made safe just
  64. by hardening them to external threat.
  65. <li>Dynamic and semi-trusted international coalitions: the network can
  66. be shared without revealing the existence or amount of communication
  67. between all parties.
  68. <li>Networks partially under known hostile control: to block
  69. communications, the enemy must take down the whole network.
  70. <li>Politically sensitive negotiations.
  71. <li>Road warriors.
  72. <li>Protecting procurement patterns.
  73. <li>Anonymous tips.
  74. </ul>
  75. <p>Law enforcement needs Tor for safety:
  76. <ul>
  77. <li>Allowing anonymous tips or crime reporting
  78. <li>Allowing agents to observe websites without notifying them that
  79. they're being observed (or, more broadly, without having it be an
  80. official visit from law enforcement).
  81. <li>Surveillance and honeypots (sting operations)
  82. </ul>
  83. <p>Does the idea of sharing the Tor network with
  84. all of these groups bother you? It shouldn't -- <a
  85. href="http://freehaven.net/doc/fc03/econymics.pdf">you need them for
  86. your security</a>.</p>
  87. <a name="client-or-server"></a>
  88. <h2>Should I run a client or a server?</h2>
  89. <p>You can run Tor in either client mode or server mode. By default,
  90. everybody is a <i>client</i>. This means you don't relay traffic for
  91. anybody but yourself.</p>
  92. <p>If you have less than 1Mbit in both directions, you should stay
  93. a client. Otherwise, please consider being a server, to help out the
  94. network. (Currently each server uses 20-30 gigabytes of traffic
  95. per month; but that may go up.)</p>
  96. <p>Note that you can be a server without allowing users to make
  97. connections from your computer to the outside world. This is called being
  98. a middleman server.</p>
  99. <p> Benefits of running a server include:
  100. <ul>
  101. <li>Clients are generally limited to 100KB/s, whereas servers can inject
  102. or receive as much traffic as they want.
  103. <li>You may get stronger anonymity, since your destination can't know
  104. whether connections relayed through your computer originated at your
  105. computer or not.
  106. <li>You can also get stronger anonymity by configuring your Tor clients
  107. to use your Tor server for entry or for exit.
  108. <li>You're helping me with development and scalability testing.
  109. <li>You're helping your fellow Internet users by providing a larger
  110. network. Also, having servers in many different pieces of the Internet
  111. gives users more robustness against curious telcos and brute force
  112. attacks.
  113. </ul>
  114. <p>You can read more about setting up Tor as a
  115. server <a href="#server">below</a>.</p>
  116. <a name="installing"></a>
  117. <h2>Installing Tor</h2>
  118. <p>You can get the latest releases <a
  119. href="http://freehaven.net/tor/dist/">here</a>.</p>
  120. <p>If you got Tor from a tarball, unpack it: <tt>tar xzf
  121. tor-0.0.7.tar.gz; cd tor-0.0.7</tt>. Run <tt>./configure</tt>, then
  122. <tt>make</tt>, and then <tt>make install</tt> (as root if necessary). Then
  123. you can launch tor from the command-line by running <tt>tor</tt>.</p>
  124. <p>If you got Tor from the Win32 .exe file, you
  125. can just click-click it (you may need to install <a
  126. href="http://www.slproweb.com/products/Win32OpenSSL.html">OpenSSL
  127. 0.9.7</a> first, if you get an error about missing
  128. libeay32.dll.) You might also want to run Tor in a dos window,
  129. so you can see its logs, and see its error messages if it
  130. crashes. If you don't want the default configuration, fetch the <a
  131. href="http://freehaven.net/tor/doc/torrc.sample">torrc</a>, edit it,
  132. and use <tt>tor.exe -f torrc</tt>.</p>
  133. <p>Otherwise, if you got it prepackaged (e.g. in the <a
  134. href="http://packages.debian.org/tor">Debian package</a> or <a
  135. href="http://packages.gentoo.org/packages/?category=net-misc;name=tor">Gentoo
  136. package</a>), these steps are already done for you, and you may
  137. even already have Tor started in the background (logging to
  138. /var/log/something).</p>
  139. <p>In any case, see the next section for what to <i>do</i> with it now that
  140. you've got it running.</p>
  141. <a name="client"></a>
  142. <h2>Configuring a client</h2>
  143. <p>Tor comes configured as a client by default. It uses a built-in
  144. default configuration file, and most people won't need to change any of
  145. the settings.</p>
  146. <p>The only setting you might need to change is "SocksBindAddress".
  147. By default, your Tor client only listens for applications that connect
  148. from localhost. Connections from other computers are refused. If you
  149. want to torify applications on different computers than the Tor client,
  150. you should copy torrc.sample to torrc (it's installed by default
  151. to /usr/local/etc/tor/), change the SocksBindAddress line to
  152. 0.0.0.0, and then hup or restart Tor.</p>
  153. <p>To test if it's working, point your browser
  154. to socks4 or socks5 proxy at localhost port 9050. In
  155. Mozilla, this is in edit|preferences|advanced|proxies. Go to <a
  156. href="http://www.junkbusters.com/cgi-bin/privacy">http://www.junkbusters.com/cgi-bin/privacy</a>
  157. and see what IP it says you're coming from. (If you have a personal
  158. firewall, be sure to allow local connections to port 9050. If your
  159. firewall blocks outgoing connections, punch a hole so it can connect to
  160. TCP *:9001-9004 and *:9030-9033. If you're using Safari as your browser,
  161. keep in mind that OS X before 10.3 claims to support socks but does
  162. not.)</p>
  163. <p>Once you've tested that it works, you should install <a
  164. href="http://www.privoxy.org/">privoxy</a>, which is a filtering web
  165. proxy that integrates well with Tor. Add the line <br>
  166. <tt>forward-socks4a / localhost:9050 .</tt><br>
  167. (don't forget the dot) to its config file (you can just add it to the
  168. top). Then change your mozilla to http proxy at localhost port 8118
  169. (and no socks proxy). You should also set your SSL proxy to the same
  170. thing, to hide your https traffic. Using privoxy is necessary because
  171. <a href="http://freehaven.net/tor/cvs/doc/CLIENTS">Mozilla leaks your
  172. DNS requests when it uses a socks proxy directly</a>. Privoxy also gives
  173. you good html scrubbing.</p>
  174. <p>You might want to use Tor with an application that doesn't
  175. support socks directly. In this case, you should look at
  176. using <a href="http://tsocks.sourceforge.net/">tsocks</a>
  177. to dynamically replace the system calls in your program to
  178. route through Tor. If you want to use socks4a, consider using <a
  179. href="http://www.dest-unreach.org/socat/">socat</a> (specific instructions
  180. are on <a href="http://6sxoyfb3h2nvok2d.onion/tor/SocatHelp">this hidden
  181. service url</a>).</p>
  182. <p>(Windows doesn't have tsocks; instead, you can try
  183. <a
  184. href="http://www.socks.permeo.com/Download/SocksCapDownload/index.asp">SocksCap</a>
  185. or the <a href="http://www.hummingbird.com/products/nc/socks/index.html?cks=y">Hummingbird</a>
  186. SOCKS client.)</p>
  187. <a name="server"></a>
  188. <h2>Configuring a server</h2>
  189. <p>We're looking for people with reasonably reliable Internet connections,
  190. that have at least 1Mbit each way. Currently we don't use all of that,
  191. but we want it available for burst traffic.</p>
  192. <p>(The Tor server doesn't need to be run as root, and doesn't
  193. need any special system permissions or kernel mods. You should probably
  194. run it as its own user though, especially if you run an identd service
  195. too. If you're the paranoid sort, feel free to <a
  196. href="http://wiki.noreply.org/wiki/TheOnionRouter/TorInChroot">put it
  197. into a chroot jail</a>.)</p>
  198. <p>First, copy torrc.sample to torrc (by default it's in
  199. /usr/local/etc/tor/), and edit the middle part. Create the DataDirectory,
  200. and make sure it's owned by the uid/gid that will be running tor. Fix your system
  201. clock so it's not too far off. Make sure name resolution works. Open a
  202. hole in your firewall so outsiders can connect to your ORPort.</p>
  203. <p>Then run tor to generate keys: <tt>tor</tt>. One of the files generated
  204. in your DataDirectory is your 'fingerprint' file. Mail it to
  205. tor-ops@freehaven.net.</p>
  206. <p>In that mail, be sure to tell us who you are, so we know whom to contact
  207. if there's any problem. Also describe what kind of connectivity the new
  208. server will have. If possible, PGP sign your mail.</p>
  209. <p>Once your fingerprint has been approved, you can click <a
  210. href="http://moria.seul.org:9031/">here</a> or <a
  211. href="http://62.116.124.106:9030/">here</a> and look at the
  212. running-routers line to see if your server is part of the network.</p>
  213. <p>You may find the initscript in contrib/tor.sh useful if you
  214. want to set up Tor to start at boot.</p>
  215. <a name="hidden-service"></a>
  216. <h2>Configuring a hidden service</h2>
  217. <p>Tor allows clients and servers to offer <em>hidden services</em>. That
  218. is, you can offer an apache, sshd, etc, without revealing your IP to its
  219. users. This works via Tor's rendezvous point design: both sides build
  220. a Tor circuit out, and they meet in the middle.</p>
  221. <p>If you're using Tor and <a href="http://www.privoxy.org/">Privoxy</a>,
  222. you can <a href="http://6sxoyfb3h2nvok2d.onion/">go to the hidden wiki</a>
  223. to see hidden services in action.</p>
  224. <p>To set up a hidden service, copy torrc.sample to torrc (by default it's
  225. in /usr/local/etc/tor/), and edit the bottom part. Then run Tor. It will
  226. create each HiddenServiceDir you have configured, and it will create a
  227. 'hostname' file which specifies the url (xyz.onion) for that service. You
  228. can tell people the url, and they can connect to it via their Tor client,
  229. assuming they're using a proxy (such as Privoxy) that speaks socks4a.</p>
  230. <a name="own-network"></a>
  231. <h2>Setting up your own network</h2>
  232. <p>
  233. If you want to experiment locally with your own network, or you're cut
  234. off from the Internet and want to be able to mess with Tor still, then
  235. you may want to set up your own separate Tor network.
  236. <p>
  237. To set up your own Tor network, you need to run your own directory
  238. servers, and you need to change the tarball so it points to your directory
  239. servers rather than the default ones.
  240. <ul>
  241. <li>1: Grab the latest release.
  242. <li>2: For each directory server you want,
  243. <ul>
  244. <li>2a: Set it up as a server (see <a href="#server">"setting up a
  245. server"</a> above), with a least ORPort, DataDirectory, and Nickname
  246. defined.
  247. <li>2b: Set "DirPort" to the intended port for serving directories.
  248. <li>2c: Set "RecommendedVersions" to a comma-separated list of acceptable
  249. versions of the code for clients and servers to be running (see step
  250. 4c below).
  251. <!-- <li>2d: Create a file called approved-routers in your DataDirectory:
  252. <tt>touch approved-routers</tt>. It will be empty for now. We'll fill it in
  253. step 5. -->
  254. <li>2d: Create an empty dirservers file (<tt>touch dirservers</tt>). Point
  255. RouterFile at it in your torrc.
  256. <li>2e: Run it: <tt>tor -f torrc</tt>. This will generate your keys and a
  257. router.desc (router descriptor) file. It will then exit with a complaint
  258. that it can't open the fingerprint file; that's fine.
  259. </ul>
  260. <li>3: Create the new dirservers file. You do this by concatenating the
  261. "router.desc" files from each dirserver's DataDirectory: <tt>cat router1.desc
  262. router2.desc ... &gt; dirservers</tt>
  263. <li>4: Now you need to teach clients and servers to use the new
  264. dirservers file. First, check out the tor cvs repository (instructions <a
  265. href="http://freehaven.net/tor/">here</a> -- be sure to check out the
  266. tag that matches the version of the code you intend to use; and note that
  267. the latest cvs version may not compile or work right). Then:
  268. <ul>
  269. <li>4a: Edit src/or/config.c and change the default_dirservers_string array
  270. so that it reflects the contents of the new dirservers file instead
  271. of the old one. Be sure to get the quotes and newlines and semicolons
  272. right. (This step sucks. We plan to have it solved by the release of 0.0.9.)
  273. <li>4b: Replace the dirservers file in your sandbox (in src/config/)
  274. with the one from step 3.
  275. <li>4c: edit configure.in, change the AM_INIT_AUTOMAKE(tor, 0.0.8)
  276. line so that it specifies a version that is specific to you, such as
  277. 0.0.8-arma. This will help you keep from being confused later. Be sure
  278. to update the RecommendedVersions lines to include this version.
  279. <li>4d: run <tt>./autogen.sh</tt> (you'll need a new enough set of auto* tools),
  280. then <tt>make dist</tt>.
  281. </ul>
  282. <li>5: Create a file called approved-routers in the DataDirectory
  283. of each directory server. Collect the 'fingerprint' lines from the
  284. DataDirectory of each server (including directory servers), and include
  285. them (one per line) in each approved-routers file. You can hup the tor
  286. process for each directory server to reload the approved-routers file
  287. (so you don't have to restart the process).
  288. </ul>
  289. <!--<h2>Other doc resources</h2>
  290. <ul>
  291. <li>Design paper
  292. <li>Spec and rend-spec
  293. <li>others
  294. </ul> -->
  295. </body>
  296. </html>