tor-doc.html 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386
  1. <html>
  2. <head>
  3. <title>Tor Documentation</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://tor.freehaven.net/">Tor</a> documentation</h1>
  11. <p>Tor provides a distributed network of servers ("onion routers"). Users
  12. bounce their communications (web requests, IM, IRC, SSH, etc.) around
  13. the routers. This makes it hard for recipients, observers, and even the
  14. onion routers themselves to track the source of the stream.</p>
  15. <a name="why"></a>
  16. <h2>Why should I use Tor?</h2>
  17. <p>Individuals need Tor for privacy:
  18. <ul>
  19. <li>Privacy in web browsing -- both from the remote website (so it can't
  20. track and sell your behavior), and similarly from your local ISP.
  21. <li>Safety in web browsing: if your local government doesn't approve
  22. of its citizens visiting certain websites, they may monitor the sites
  23. and put readers on a list of suspicious persons.
  24. <li>Circumvention of local censorship: connect to resources (news
  25. sites, instant messaging, etc) that are restricted from your
  26. ISP/school/company/government.
  27. <li>Socially sensitive communication: chat rooms and web forums for
  28. rape and abuse survivors, or people with illnesses.
  29. </ul>
  30. <p>Journalists and NGOs need Tor for safety:
  31. <ul>
  32. <li>Allowing dissidents and whistleblowers to communicate more safely.
  33. <li>Censorship-resistant publication, such as making available your
  34. home-made movie anonymously via a Tor <a href="#hidden-service">hidden
  35. service</a>; and reading, e.g. of news sites not permitted in some
  36. countries.
  37. <li>Allowing your workers to check back with your home website while
  38. they're in a foreign country, without notifying everybody nearby that
  39. they're working with your organization.
  40. </ul>
  41. <p>Companies need Tor for business security:
  42. <ul>
  43. <li>Competitive analysis: browse the competition's website safely.
  44. <li>Protecting collaborations of sensitive business units or partners.
  45. <li>Protecting procurement suppliers or patterns.
  46. <li>Putting the "P" back in "VPN": traditional VPNs reveal the exact
  47. amount and frequency of communication. Which locations have employees
  48. working late? Which locations have employees consulting job-hunting
  49. websites? Which research groups are communicating with your company's
  50. patent lawyers?
  51. </ul>
  52. <p>Governments need Tor for traffic-analysis-resistant communication:
  53. <ul>
  54. <li>Open source intelligence gathering (hiding individual analysts is
  55. not enough -- the organization itself may be sensitive).
  56. <li>Defense in depth on open <em>and classified</em> networks -- networks
  57. with a million users (even if they're all cleared) can't be made safe just
  58. by hardening them to external threat.
  59. <li>Dynamic and semi-trusted international coalitions: the network can
  60. be shared without revealing the existence or amount of communication
  61. between all parties.
  62. <li>Networks partially under known hostile control: to block
  63. communications, the enemy must take down the whole network.
  64. <li>Politically sensitive negotiations.
  65. <li>Road warriors.
  66. <li>Protecting procurement patterns.
  67. <li>Anonymous tips.
  68. </ul>
  69. <p>Law enforcement needs Tor for safety:
  70. <ul>
  71. <li>Allowing anonymous tips or crime reporting
  72. <li>Allowing agents to observe websites without notifying them that
  73. they're being observed (or, more broadly, without having it be an
  74. official visit from law enforcement).
  75. <li>Surveillance and honeypots (sting operations)
  76. </ul>
  77. <p>Does the idea of sharing the Tor network with
  78. all of these groups bother you? It shouldn't -- <a
  79. href="http://freehaven.net/doc/fc03/econymics.pdf">you need them for
  80. your security</a>.</p>
  81. <a name="client-or-server"></a>
  82. <h2>Should I run a client or a server?</h2>
  83. <p>You can run Tor in either client mode or server mode. By default,
  84. everybody is a <i>client</i>. This means you don't relay traffic for
  85. anybody but yourself.</p>
  86. <p>If your computer doesn't have a routable IP address or you're using
  87. a modem, you should stay a client. Otherwise, please consider being
  88. a server, to help out the network. (Currently each server uses 20-500
  89. gigabytes of traffic per month, depending on its capacity and its rate
  90. limiting configuration.)</p>
  91. <p>Note that you can be a server without allowing users to make
  92. connections from your computer to the outside world. This is called being
  93. a middleman server.</p>
  94. <p> Benefits of running a server include:
  95. <ul>
  96. <li>You may get stronger anonymity, since your destination can't know
  97. whether connections relayed through your computer originated at your
  98. computer or not.
  99. <li>You can also get stronger anonymity by configuring your Tor clients
  100. to use your Tor server for entry or for exit.
  101. <li>You're helping the Tor staff with development and scalability testing.
  102. <li>You're helping your fellow Internet users by providing a larger
  103. network. Also, having servers in many different pieces of the Internet
  104. gives users more robustness against curious telcos and brute force
  105. attacks.
  106. </ul>
  107. <p>Other things to note:
  108. <ul>
  109. <li>Tor has built-in support for rate limiting; see BandwidthRate
  110. and BandwidthBurst config options. Further, if you have
  111. lots of capacity but don't want to spend that many bytes per
  112. month, check out the Accounting and Hibernation features. See <a
  113. href="http://wiki.noreply.org/wiki/TheOnionRouter/TorFAQ">the FAQ</a>
  114. for details.</li>
  115. <li>It's fine if the server goes offline sometimes. The directories
  116. notice this quickly and stop advertising the server. Just try to make
  117. sure it's not too often, since connections using the server when it
  118. disconnects will break.</li>
  119. <li>We can handle servers with dynamic IPs just fine, as long as the
  120. server itself knows its IP. If your server is behind a NAT and it doesn't
  121. know its public IP (e.g. it has an IP of 192.168.x.y), then we can't use it
  122. as a server yet. (If you want to port forward and set your Address
  123. config option to use dyndns DNS voodoo to get around this, feel free. If
  124. you write a howto, <a href="mailto:tor-volunteer@freehaven.net">even
  125. better</a>.)</li>
  126. <li>Your server will passively estimate and advertise its recent
  127. bandwidth capacity.
  128. Clients choose paths weighted by this capacity, so high-bandwidth
  129. servers will attract more paths than low-bandwidth ones. That's why
  130. having even low-bandwidth servers is useful too.</li>
  131. </ul>
  132. </p>
  133. <p>You can read more about setting up Tor as a
  134. server <a href="#server">below</a>.</p>
  135. <a name="installing"></a>
  136. <h2>Installing Tor</h2>
  137. <p>Win32 users can use our Tor installer. See <a
  138. href="tor-doc-win32.html">these instructions</a> for help with
  139. installing, configuring, and using Tor on Win32.
  140. </p>
  141. <p>You can get the latest releases <a
  142. href="http://tor.freehaven.net/dist/">here</a>.</p>
  143. <p>If you got Tor from a tarball, unpack it: <tt>tar xzf
  144. tor-0.0.9.1.tar.gz; cd tor-0.0.9.1</tt>. Run <tt>./configure</tt>, then
  145. <tt>make</tt>, and then <tt>make install</tt> (as root if necessary). Then
  146. you can launch tor from the command-line by running <tt>tor</tt>.
  147. Otherwise, if you got it prepackaged (e.g. in the <a
  148. href="http://packages.debian.org/tor">Debian package</a> or <a
  149. href="http://packages.gentoo.org/packages/?category=net-misc;name=tor">Gentoo
  150. package</a>), these steps are already done for you, and you may
  151. even already have Tor started in the background (logging to
  152. /var/log/something).</p>
  153. <p>In any case, see the <a href="#client">next section</a> for what to
  154. <i>do</i> with it now that you've got it running.</p>
  155. <a name="client"></a>
  156. <h2>Configuring a client</h2>
  157. <p>Tor comes configured as a client by default. It uses a built-in
  158. default configuration file, and most people won't need to change any of
  159. the settings.</p>
  160. <p>After installing Tor, you should install <a
  161. href="http://www.privoxy.org/">privoxy</a>, which is a filtering web
  162. proxy that integrates well with Tor. Add the line <br>
  163. <tt>forward-socks4a / localhost:9050 .</tt><br>
  164. (don't forget the dot) to privoxy's config file (you can just add it to the
  165. top). Then change your browser to http proxy at localhost port 8118.
  166. (In Mozilla, this is in Edit|Preferences|Advanced|Proxies.)
  167. You should also set your SSL proxy to the same
  168. thing, to hide your SSL traffic. Using privoxy is <b>necessary</b> because
  169. <a href="http://tor.freehaven.net/cvs/tor/doc/CLIENTS">Mozilla leaks your
  170. DNS requests when it uses a SOCKS proxy directly</a>. Privoxy also gives
  171. you good html scrubbing.</p>
  172. <p>To test if it's working, go to <a
  173. href="http://peertech.org/privacy-knoppix/">this site</a> and see
  174. what IP it says you're coming from. (If it's down, you can try the
  175. <a href="http://www.junkbusters.com/cgi-bin/privacy">junkbusters</a>
  176. site instead.)</p>
  177. <p>
  178. If you have a personal firewall, be sure to allow local connections to
  179. port 8118 and port 9050. If your firewall blocks outgoing connections,
  180. punch a hole so it can connect to TCP ports 80, 443, and 9001-9033.
  181. <!--If you're
  182. using Safari as your browser, keep in mind that OS X before 10.3 claims
  183. to support SOCKS but does not. -->
  184. For more troubleshooting suggestions, see <a
  185. href="http://wiki.noreply.org/wiki/TheOnionRouter/TorFAQ">the FAQ</a>.
  186. </p>
  187. <p>To Torify an application that supports http, just point it at Privoxy
  188. (that is, localhost port 8118). To use SOCKS directly (for example, for
  189. instant messaging, Jabber, IRC, etc), point your application directly at
  190. Tor (localhost port 9050). For applications that support neither SOCKS
  191. nor http, you should look at
  192. using <a href="http://tsocks.sourceforge.net/">tsocks</a>
  193. to dynamically replace the system calls in your program to
  194. route through Tor. If you want to use SOCKS 4A, consider using <a
  195. href="http://www.dest-unreach.org/socat/">socat</a> (specific instructions
  196. are on <a href="http://6sxoyfb3h2nvok2d.onion/tor/SocatHelp">this hidden
  197. service url</a>).</p>
  198. <p>(Windows doesn't have tsocks; see the bottom of the
  199. <a href="tor-doc-win32.html">Win32 instructions</a> for alternatives.)
  200. </p>
  201. <a name="server"></a>
  202. <h2>Configuring a server</h2>
  203. <p>We're looking for people with reasonably reliable Internet connections,
  204. that have at least 20 kilobytes/s each way. If you frequently have a
  205. lot of packet loss or really high latency, we can't handle your server
  206. yet. Otherwise, please help out!
  207. </p>
  208. <p>
  209. To read more about whether you should be a server, check out <a
  210. href="#client-or-server">the section above</a>.
  211. </p>
  212. <p>To set up a Tor server, do the following steps after installing Tor.
  213. (These instructions are Unix-centric; if you're excited about working
  214. with the Tor developers to get a Tor server working on Windows, let us
  215. know and we'll work with you to fix whatever bugs come up -- currently
  216. there are some known bugs that keep Tor from working as a server on
  217. native Win32.)
  218. </p>
  219. <ul>
  220. <li>1. Edit the bottom part of your torrc (if you installed from source,
  221. you will need to copy torrc.sample to torrc first. Look for them in
  222. /usr/local/etc/tor/). Create the DataDirectory if necessary, and make
  223. sure it's owned by the uid/gid that will be running tor. Fix your system
  224. clock so it's not too far off. Make sure name resolution works.
  225. <!--Make sure each
  226. process can get to 1024 file descriptors (this should be already done
  227. for everybody but some BSD folks). -->
  228. <li>2. If you are using a firewall, open a hole in your firewall so
  229. incoming connections can reach the ports you configured (i.e. ORPort,
  230. plus DirPort if you enabled it). Make sure outgoing connections can reach
  231. at least ports 80, 443, and 9001-9033 (to get to other onion routers),
  232. plus any other addresses or ports your exit policy allows.
  233. <li>3. Start your server: if you installed from source you can just
  234. run <tt>tor</tt>, whereas packages typically launch Tor from their
  235. initscripts. If it logs any warnings, address them. (By default Tor
  236. logs to stdout, but some packages log to /var/log/tor/ instead.)
  237. <li>4. One of the files generated in your DataDirectory is called
  238. 'fingerprint'. Send mail to tor-ops@freehaven.net including a)
  239. this key fingerprint, b) who you are, so we know whom to contact if
  240. there's any problem, and c) what kind of connectivity the new server
  241. will have. If possible, PGP sign your mail.
  242. </ul>
  243. <p>
  244. Optionally, we recommend the following steps as well:
  245. </p>
  246. <ul>
  247. <li>5. Make a separate user to run the server. If you
  248. installed the deb or the rpm, this is already done. Otherwise,
  249. you can do it by hand. (The Tor server doesn't need to be run as
  250. root, so it's good practice to not run it as root. Running as a
  251. 'tor' user avoids issues with identd and other services that
  252. detect user name. If you're the paranoid sort, feel free to <a
  253. href="http://wiki.noreply.org/wiki/TheOnionRouter/TorInChroot">put Tor
  254. into a chroot jail</a>.)
  255. <li>6. Decide what exit policy you want. By default your server allows
  256. access to many popular services, but we restrict some (such as port 25)
  257. due to abuse potential. You might want an exit policy that is
  258. less restrictive or more restrictive; edit your torrc appropriately.
  259. If you choose a particularly open exit policy, you might want to make
  260. sure your upstream or ISP is ok with that choice.
  261. <li>7. You may find the initscripts in contrib/tor.sh or
  262. contrib/torctl useful if you want to set up Tor to start at boot. Let
  263. the Tor developers know which script you find more useful.
  264. <li>8. Consider setting your hostname to 'anonymous' or
  265. 'proxy' or 'tor-proxy' if you can, so when other people see the address
  266. in their web logs or whatever, they will more quickly understand what's
  267. going on.
  268. <li>9. If you're not running anything else on port 80 or port 443,
  269. please consider setting up port-forwarding and advertising these
  270. low-numbered ports as your Tor server. This will help allow users behind
  271. particularly restrictive firewalls to access the Tor network. See <a
  272. href="http://wiki.noreply.org/wiki/TheOnionRouter/TorFAQ#ServerForFirewalledClients">the
  273. FAQ</a> for details of how to set this up.
  274. </ul>
  275. <p>You can click <a href="http://moria.seul.org:9031/">here</a> or <a
  276. href="http://62.116.124.106:9030/">here</a> and look at the router-status
  277. line to see if your server is part of the network. It will be listed by
  278. nickname once we have added your server to the list of known servers;
  279. otherwise it is listed only by its fingerprint.</p>
  280. <a name="hidden-service"></a>
  281. <h2>Configuring a hidden service</h2>
  282. <p>Tor allows clients and servers to offer <em>hidden services</em>. That
  283. is, you can offer an apache, sshd, etc, without revealing your IP to its
  284. users. This works via Tor's rendezvous point design: both sides build
  285. a Tor circuit out, and they meet in the middle.</p>
  286. <p>If you're using Tor and <a href="http://www.privoxy.org/">Privoxy</a>,
  287. you can <a href="http://6sxoyfb3h2nvok2d.onion/">go to the hidden wiki</a>
  288. to see hidden services in action.</p>
  289. <p>To set up a hidden service, copy torrc.sample to torrc (by default it's
  290. in /usr/local/etc/tor/), and edit the middle part. Then run Tor. It will
  291. create each HiddenServiceDir you have configured, and it will create a
  292. 'hostname' file which specifies the url (xyz.onion) for that service. You
  293. can tell people the url, and they can connect to it via their Tor client,
  294. assuming they're using a proxy (such as Privoxy) that speaks SOCKS 4A.</p>
  295. <a name="own-network"></a>
  296. <h2>Setting up your own network</h2>
  297. <p>
  298. If you want to experiment locally with your own network, or you're cut
  299. off from the Internet and want to be able to mess with Tor still, then
  300. you may want to set up your own separate Tor network.
  301. <p>
  302. To set up your own Tor network, you need to run your own directory
  303. servers, and you need to configure each client and server so it knows
  304. about your directory servers rather than the default ones.
  305. <ul>
  306. <li>1: Grab the latest release. Use at least 0.0.9.
  307. <li>2: For each directory server you want,
  308. <ul>
  309. <li>2a: Set it up as a server (see <a href="#server">"setting up a
  310. server"</a> above), with a least ORPort, DirPort, DataDirectory, and Nickname
  311. defined. Set "AuthoritativeDirectory 1".
  312. <li>2b: Set "RecommendedVersions" to a comma-separated list of acceptable
  313. versions of the code for clients and servers to be running.
  314. <li>2c: Run it: <tt>tor --list-fingerprint</tt> if your torrc is in
  315. the default place, or <tt>tor -f torrc --list-fingerprint</tt> to
  316. specify one. This will generate your keys and output a fingerprint
  317. line.
  318. </ul>
  319. <li>3: Now you need to teach clients and servers to use the new
  320. dirservers. For each fingerprint, add a line like<br>
  321. <tt>DirServer 18.244.0.114:80 719B E45D E224 B607 C537 07D0 E214 3E2D 423E 74CF</tt><br>
  322. to the torrc of each client and server who will be using your network.
  323. <li>4: Create a file called approved-routers in the DataDirectory
  324. of each directory server. Collect the 'fingerprint' lines from
  325. each server (including directory servers), and include them (one per
  326. line) in each approved-routers file. You can hup the tor process for
  327. each directory server to reload the approved-routers file (so you don't
  328. have to restart the process).
  329. </ul>
  330. <!--<h2>Other doc resources</h2>
  331. <ul>
  332. <li>Design paper
  333. <li>Spec and rend-spec
  334. <li>others
  335. </ul> -->
  336. </body>
  337. </html>