1TOR(1) General Commands Manual TOR(1)
2
6 tor - The second-generation onion router
7
9 tor [OPTION value]...
10
12 tor is a connection-oriented anonymizing communication service. Users
13 choose a source-routed path through a set of nodes, and negotiate a
14 "virtual circuit" through the network, in which each node knows its
15 predecessor and successor, but no others. Traffic flowing down the cir‐
16 cuit is unwrapped by a symmetric key at each node, which reveals the
17 downstream node.
18 Basically tor provides a distributed network of servers ("onion
20 routers"). Users bounce their TCP streams -- web traffic, ftp, ssh, etc
21 -- around the routers, and recipients, observers, and even the routers
22 themselves have difficulty tracking the source of the stream.
23
25 -h, -help Display a short help message and exit.
26 -f FILE
28 FILE contains further "option value" pairs. (Default:
29 /etc/tor/torrc)
30 --hash-password
32 Generates a hashed password for control port access.
33 --list-fingerprint
35 Generate your keys and output your nickname and fingerprint.
36 --verify-config
38 Verify the configuration file is valid.
39 --nt-service
41 --service [install|remove|start|stop] Manage the Tor Windows
42 NT/2000/XP service. Current instructions can be found at
43 http://wiki.noreply.org/noreply/TheOnionRouter/TorFAQ#WinNTSer‐
44 vice
45 --list-torrc-options
47 List all valid options.
48 --version
50 Display Tor version.
51 Other options can be specified either on the command-line (--option
53 value), or in the configuration file (option value). Options
54 are case-insensitive.
55 BandwidthRate N bytes|KB|MB|GB|TB
57 A token bucket limits the average incoming bandwidth usage on
58 this node to the specified number of bytes per second, and the
59 average outgoing bandwidth usage to that same value. (Default: 3
60 MB)
61 BandwidthBurst N bytes|KB|MB|GB|TB
63 Limit the maximum token bucket size (also known as the burst) to
64 the given number of bytes in each direction. This value should
65 be at least twice your BandwidthRate. (Default: 6 MB)
66 MaxAdvertisedBandwidth N bytes|KB|MB|GB|TB
68 If set, we will not advertise more than this amount of bandwidth
69 for our BandwidthRate. Server operators who want to reduce the
70 number of clients who ask to build circuits through them (since
71 this is proportional to advertised bandwidth rate) can thus
72 reduce the CPU demands on their server without impacting network
73 performance.
74 ConnLimit NUM
76 The minimum number of file descriptors that must be available to
77 the Tor process before it will start. Tor will ask the OS for as
78 many file descriptors as the OS will allow (you can find this by
79 "ulimit -H -n"). If this number is less than ConnLimit, then Tor
80 will refuse to start.
81 You probably don't need to adjust this. It has no effect on Win‐
83 dows since that platform lacks getrlimit(). (Default: 1000)
84 ControlPort Port
86 If set, Tor will accept connections on this port and allow those
87 connections to control the Tor process using the Tor Control
88 Protocol (described in control-spec.txt). Note: unless you also
89 specify one of HashedControlPassword or CookieAuthentication,
90 setting this option will cause Tor to allow any process on the
91 local host to control it. This option is required for many Tor
92 controllers; most use the value of 9051.
93 ControlListenAddress IP[:PORT]
95 Bind the controller listener to this address. If you specify a
96 port, bind to this port rather than the one specified in Con‐
97 trolPort. We strongly recommend that you leave this alone unless
98 you know what you're doing, since giving attackers access to
99 your control listener is really dangerous. (Default: 127.0.0.1)
100 This directive can be specified multiple times to bind to multi‐
101 ple addresses/ports.
102 HashedControlPassword hashed_password
104 Don't allow any connections on the control port except when the
105 other process knows the password whose one-way hash is
106 hashed_password. You can compute the hash of a password by run‐
107 ning "tor --hash-password password".
108 CookieAuthentication 0|1
110 If this option is set to 1, don't allow any connections on the
111 control port except when the connecting process knows the con‐
112 tents of a file named "control_auth_cookie", which Tor will cre‐
113 ate in its data directory. This authentication methods should
114 only be used on systems with good filesystem security. (Default:
115 0)
116 DataDirectory DIR
118 Store working data in DIR (Default: /var/lib/tor)
119 DirServer [nickname] [flags] address:port fingerprint
121 Use a nonstandard authoritative directory server at the provided
122 address and port, with the specified key fingerprint. This
123 option can be repeated many times, for multiple authoritative
124 directory servers. Flags are separated by spaces, and determine
125 what kind of an authority this directory is. By default, every
126 authority is authoritative for current ("v2")-style directories,
127 unless the "no-v2" flag is given. If the "v1" flags is pro‐
128 vided, Tor will use this server as an authority for old-style
129 (v1) directories as well. (Only directory mirrors care about
130 this.) Tor will use this server as an authority for hidden ser‐
131 vice information if the "hs" flag is set, or if the "v1" flag is
132 set and the "no-hs" flag is not set. If a flag "orport=port" is
133 given, Tor will use the given port when opening encrypted tun‐
134 nels to the dirserver. If no dirserver line is given, Tor will
135 use the default directory servers. NOTE: this option is
136 intended for setting up a private Tor network with its own
137 directory authorities. If you use it, you will be distinguish‐
138 able from other users, because you won't believe the same
139 authorities they do.
140 FetchHidServDescriptors 0|1
142 If set to 0, Tor will never fetch any hidden service descriptors
143 from the rendezvous directories. This option is only useful if
144 you're using a Tor controller that handles hidserv fetches for
145 you. (Default: 1)
146 FetchServerDescriptors 0|1
148 If set to 0, Tor will never fetch any network status summaries
149 or server descriptors from the directory servers. This option is
150 only useful if you're using a Tor controller that handles direc‐
151 tory fetches for you. (Default: 1)
152 FetchUselessDescriptors 0|1
154 If set to 1, Tor will fetch every non-obsolete descriptor from
155 the authorities that it hears about. Otherwise, it will avoid
156 fetching useless descriptors, for example for routers that are
157 not running. This option is useful if you're using the contrib‐
158 uted "exitlist" script to enumerate Tor nodes that exit to cer‐
159 tain addresses. (Default: 0)
160 Group GID
162 On startup, setgid to this group.
163 HttpProxy host[:port]
165 Tor will make all its directory requests through this host:port
166 (or host:80 if port is not specified), rather than connecting
167 directly to any directory servers.
168 HttpProxyAuthenticator username:password
170 If defined, Tor will use this username:password for Basic Http
171 proxy authentication, as in RFC 2617. This is currently the only
172 form of Http proxy authentication that Tor supports; feel free
173 to submit a patch if you want it to support others.
174 HttpsProxy host[:port]
176 Tor will make all its OR (SSL) connections through this
177 host:port (or host:443 if port is not specified), via HTTP CON‐
178 NECT rather than connecting directly to servers. You may want
179 to set FascistFirewall to restrict the set of ports you might
180 try to connect to, if your Https proxy only allows connecting to
181 certain ports.
182 HttpsProxyAuthenticator username:password
184 If defined, Tor will use this username:password for Basic Https
185 proxy authentication, as in RFC 2617. This is currently the only
186 form of Https proxy authentication that Tor supports; feel free
187 to submit a patch if you want it to support others.
188 KeepalivePeriod NUM
190 To keep firewalls from expiring connections, send a padding
191 keepalive cell every NUM seconds on open connections that are in
192 use. If the connection has no open circuits, it will instead be
193 closed after NUM seconds of idleness. (Default: 5 minutes)
194 Log minSeverity[-maxSeverity] stderr|stdout|syslog
196 Send all messages between minSeverity and maxSeverity to the
197 standard output stream, the standard error stream, or to the
198 system log. (The "syslog" value is only supported on Unix.)
199 Recognized severity levels are debug, info, notice, warn, and
200 err. We advise using "notice" in most cases, since anything
201 more verbose may provide sensitive information to an attacker
202 who obtains the logs. If only one severity level is given, all
203 messages of that level or higher will be sent to the listed des‐
204 tination.
205 Log minSeverity[-maxSeverity] file FILENAME
207 As above, but send log messages to the listed filename. The
208 "Log" option may appear more than once in a configuration file.
209 Messages are sent to all the logs that match their severity
210 level.
211 OutboundBindAddress IP
213 Make all outbound connections originate from the IP address
214 specified. This is only useful when you have multiple network
215 interfaces, and you want all of Tor's outgoing connections to
216 use a single one.
217 PidFile FILE
219 On startup, write our PID to FILE. On clean shutdown, remove
220 FILE.
221 ProtocolWarnings 0|1
223 If 1, Tor will log with severity 'warn' various cases of other
224 parties not following the Tor specification. Otherwise, they are
225 logged with severity 'info'. (Default: 0)
226 RunAsDaemon 0|1
228 If 1, Tor forks and daemonizes to the background. This option
229 has no effect on Windows; instead you should use the --service
230 command-line option. (Default: 0)
231 SafeLogging 0|1
233 If 1, Tor replaces potentially sensitive strings in the logs
234 (e.g. addresses) with the string [scrubbed]. This way logs can
235 still be useful, but they don't leave behind personally identi‐
236 fying information about what sites a user might have visited.
237 (Default: 1)
238 User UID
240 On startup, setuid to this user.
241 HardwareAccel 0|1
243 If non-zero, try to use crypto hardware acceleration when avail‐
244 able. This is untested and probably buggy. (Default: 0)
245 AvoidDiskWrites 0|1
247 If non-zero, try to write to disk less frequently than we would
248 otherwise. This is useful when running on flash memory or other
249 media that support only a limited number of writes. (Default:
250 0)
251 TunnelDirConns 0|1
253 If non-zero, when a directory server we contact supports it, we
254 will build a one-hop circuit and make an encrypted connection
255 via its ORPort. (Default: 0)
256 PreferTunneledDirConns 0|1
258 If non-zero, we will avoid directory servers that don't support
259 tunneled directory connections, when possible. (Default: 0)
260
263 The following options are useful only for clients (that is, if Sock‐
264 sPort is non-zero):
265 AllowInvalidNodes entry|exit|middle|introduction|rendezvous|...
267 If some Tor servers are obviously not working right, the direc‐
268 tory authorities can manually mark them as invalid, meaning that
269 it's not recommended you use them for entry or exit positions in
270 your circuits. You can opt to use them in some circuit posi‐
271 tions, though. The default is "middle,rendezvous", and other
272 choices are not advised.
273 CircuitBuildTimeout NUM
275 Try for at most NUM seconds when building circuits. If the cir‐
276 cuit isn't open in that time, give up on it. (Default: 1
277 minute.)
278 CircuitIdleTimeout NUM
280 If we have keept a clean (never used) circuit around for NUM
281 seconds, then close it. This way when the Tor client is entirely
282 idle, it can expire all of its circuits, and then expire its TLS
283 connections. Also, if we end up making a circuit that is not
284 useful for exiting any of the requests we're receiving, it won't
285 forever take up a slot in the circuit list. (Default: 1 hour.)
286 ClientOnly 0|1
288 If set to 1, Tor will under no circumstances run as a server.
289 The default is to run as a client unless ORPort is configured.
290 (Usually, you don't need to set this; Tor is pretty smart at
291 figuring out whether you are reliable and high-bandwidth enough
292 to be a useful server.) (Default: 0)
293 ExcludeNodes nickname,nickname,...
295 A list of nodes to never use when building a circuit.
296 EntryNodes nickname,nickname,...
298 A list of preferred nodes to use for the first hop in the cir‐
299 cuit. These are treated only as preferences unless StrictEn‐
300 tryNodes (see below) is also set.
301 ExitNodes nickname,nickname,...
303 A list of preferred nodes to use for the last hop in the cir‐
304 cuit. These are treated only as preferences unless StrictExitN‐
305 odes (see below) is also set.
306 StrictEntryNodes 0|1
308 If 1, Tor will never use any nodes besides those listed in
309 "EntryNodes" for the first hop of a circuit.
310 StrictExitNodes 0|1
312 If 1, Tor will never use any nodes besides those listed in
313 "ExitNodes" for the last hop of a circuit.
314 FascistFirewall 0|1
316 If 1, Tor will only create outgoing connections to ORs running
317 on ports that your firewall allows (defaults to 80 and 443; see
318 FirewallPorts). This will allow you to run Tor as a client
319 behind a firewall with restrictive policies, but will not allow
320 you to run as a server behind such a firewall. This option is
321 deprecated; use ReachableAddresses instead.
322 FirewallPorts PORTS
324 A list of ports that your firewall allows you to connect to.
325 Only used when FascistFirewall is set. This option is depre‐
326 cated; use ReachableAddresses instead. (Default: 80, 443)
327 ReachableAddresses ADDR[/MASK][:PORT]...
329 A comma-separated list of IP addresses and ports that your fire‐
330 wall allows you to connect to. The format is as for the
331 addresses in ExitPolicy, except that "accept" is understood
332 unless "reject" is explicitly provided. For example, 'Reach‐
333 ableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept *:80'
334 means that your firewall allows connections to everything inside
335 net 99, rejects port 80 connections to net 18, and accepts con‐
336 nections to port 80 otherwise. (Default: 'accept *:*'.)
337 ReachableDirAddresses ADDR[/MASK][:PORT]...
339 Like ReachableAddresses, a list of addresses and ports. Tor
340 will obey these restrictions when fetching directory informa‐
341 tion, using standard HTTP GET requests. If not set explicitly
342 then the value of ReachableAddresses is used. If HttpProxy is
343 set then these connections will go through that proxy.
344 ReachableORAddresses ADDR[/MASK][:PORT]...
346 Like ReachableAddresses, a list of addresses and ports. Tor
347 will obey these restrictions when connecting to Onion Routers,
348 using TLS/SSL. If not set explicitly then the value of Reach‐
349 ableAddresses is used. If HttpsProxy is set then these connec‐
350 tions will go through that proxy.
351 The separation between ReachableORAddresses and ReachableDirAd‐
353 dresses is only interesting when you are connecting through
354 proxies (see HttpProxy and HttpsProxy). Most proxies limit TLS
355 connections (which Tor uses to connect to Onion Routers) to port
356 443, and some limit HTTP GET requests (which Tor uses for fetch‐
357 ing directory information) to port 80.
358 LongLivedPorts PORTS
360 A list of ports for services that tend to have long-running con‐
361 nections (e.g. chat and interactive shells). Circuits for
362 streams that use these ports will contain only high-uptime
363 nodes, to reduce the chance that a node will go down before the
364 stream is finished. (Default: 21, 22, 706, 1863, 5050, 5190,
365 5222, 5223, 6667, 6697, 8300)
366 MapAddress address newaddress
368 When a request for address arrives to Tor, it will rewrite it to
369 newaddress before processing it. For example, if you always want
370 connections to www.indymedia.org to exit via torserver (where
371 torserver is the nickname of the server), use "MapAddress
372 www.indymedia.org www.indymedia.org.torserver.exit".
373 NewCircuitPeriod NUM
375 Every NUM seconds consider whether to build a new circuit.
376 (Default: 30 seconds)
377 MaxCircuitDirtiness NUM
379 Feel free to reuse a circuit that was first used at most NUM
380 seconds ago, but never attach a new stream to a circuit that is
381 too old. (Default: 10 minutes)
382 EnforceDistinctSubnets 0|1
384 If 1, Tor will not put two servers whose IP addresses are "too
385 close" on the same circuit. Currently, two addresses are "too
386 close" if they lie in the same /16 range. (Default: 1)
387 RendNodes nickname,nickname,...
390 A list of preferred nodes to use for the rendezvous point, if
391 possible.
392 RendExcludeNodes nickname,nickname,...
394 A list of nodes to never use when choosing a rendezvous point.
395 SocksPort PORT
397 Advertise this port to listen for connections from Socks-speak‐
398 ing applications. Set this to 0 if you don't want to allow
399 application connections. (Default: 9050)
400 SocksListenAddress IP[:PORT]
402 Bind to this address to listen for connections from Socks-speak‐
403 ing applications. (Default: 127.0.0.1) You can also specify a
404 port (e.g. 192.168.0.1:9100). This directive can be specified
405 multiple times to bind to multiple addresses/ports.
406 SocksPolicy policy,policy,...
408 Set an entrance policy for this server, to limit who can connect
409 to the Socks ports. The policies have the same form as exit
410 policies below.
411 SocksTimeout NUM
413 Let a socks connection wait NUM seconds handshaking, and NUM
414 seconds unattached waiting for an appropriate circuit, before we
415 fail it. (Default: 2 minutes.)
416 TestVia nickname,nickname,...
418 A list of nodes to prefer for your middle hop when building
419 testing circuits. This option is mainly for debugging reachabil‐
420 ity problems.
421 TrackHostExits host,.domain,...
423 For each value in the comma separated list, Tor will track
424 recent connections to hosts that match this value and attempt to
425 reuse the same exit node for each. If the value is prepended
426 with a '.', it is treated as matching an entire domain. If one
427 of the values is just a '.', it means match everything. This
428 option is useful if you frequently connect to sites that will
429 expire all your authentication cookies (ie log you out) if your
430 IP address changes. Note that this option does have the disad‐
431 vantage of making it more clear that a given history is associ‐
432 ated with a single user. However, most people who would wish to
433 observe this will observe it through cookies or other protocol-
434 specific means anyhow.
435 TrackHostExitsExpire NUM
437 Since exit servers go up and down, it is desirable to expire the
438 association between host and exit server after NUM seconds. The
439 default is 1800 seconds (30 minutes).
440 UseEntryGuards 0|1
442 If this option is set to 1, we pick a few long-term entry
443 servers, and try to stick with them. This is desirable because
444 constantly changing servers increases the odds that an adversary
445 who owns some servers will observe a fraction of your paths.
446 (Defaults to 1.)
447 NumEntryGuards NUM
449 If UseEntryGuards is set to 1, we will try to pick a total of
450 NUM routers as long-term entries for our circuits. (Defaults to
451 3.)
452 SafeSocks 0|1
454 When this option is enabled, Tor will reject application connec‐
455 tions that use unsafe variants of the socks protocol -- ones
456 that only provide an IP address, meaning the application is
457 doing a DNS resolve first. Specifically, these are socks4 and
458 socks5 when not doing remote DNS. (Defaults to 0.)
459 TestSocks 0|1
461 When this option is enabled, Tor will make a notice-level log
462 entry for each connection to the Socks port indicating whether
463 the request used a safe socks protocol or an unsafe one (see
464 above entry on SafeSocks). This helps to determine whether an
465 application using Tor is possibly leaking DNS requests.
466 (Default: 0)
467 VirtualAddrNetwork Address/bits
469 When a controller asks for a virtual (unused) address with the
470 MAPADDRESS command, Tor picks an unassigned address from this
471 range. (Default: 127.192.0.0/10)
472 When providing proxy server service to a network of computers
474 using a tool like dns-proxy-tor, change this address to
475 "10.192.0.0/10" or "172.16.0.0/12". The default VirtualAddrNet‐
476 work address range on a properly configured machine will route
477 to the loopback interface. For local use, no change to the
478 default VirtualAddrNetwork setting is needed.
479 AllowNonRFC953Hostnames 0|1
481 When this option is disabled, Tor blocks hostnames containing
482 illegal characters (like @ and :) rather than sending them to an
483 exit node to be resolved. This helps trap accidental attempts
484 to resolve URLs and so on. (Default: 0)
485 FastFirstHopPK 0|1
487 When this option is enabled and we aren't running as a server,
488 Tor skips the public key step for the first hop of creating cir‐
489 cuits. This is safe since we have already used TLS to authenti‐
490 cate the server and to establish forward-secure keys. Turning
491 this option off makes circuit building slower. (Default: 1)
492 TransPort PORT
494 If non-zero, enables transparent proxy support on PORT (by con‐
495 vention, 9040). Requires OS support for transparent proxies,
496 such as BSDs' pf or Linux's IPTables. If you're planning to use
497 Tor as a transparent proxy for a network, you'll want to examine
498 and change VirtualAddrNetwork from the default setting. You'll
499 also want to set the TransListenAddress option for the network
500 you'd like to proxy. (Default: 0).
501 TransListenAddress IP[:PORT]
503 Bind to this address to listen for transparent proxy connec‐
504 tions. (Default: 127.0.0.1). This is useful for exporting a
505 transparent proxy server to an entire network.
506 NATDPort PORT
508 Allow old versions of ipfw (as included in old versions of Free‐
509 BSD, etc.) to send connections through Tor using the NATD proto‐
510 col. This option is only for people who cannot use TransPort.
511 NATDListenAddress IP[:PORT]
513 Bind to this address to listen for NATD connections. (Default:
514 127.0.0.1).
515 SERVER OPTIONS
517 The following options are useful only for servers (that is, if ORPort
519 is non-zero):
520 Address address
522 The IP or fqdn of this server (e.g. moria.mit.edu). You can
523 leave this unset, and Tor will guess your IP.
524 AssumeReachable 0|1
526 This option is used when bootstrapping a new Tor network. If set
527 to 1, don't do self-reachability testing; just upload your
528 server descriptor immediately. If AuthoritativeDirectory is also
529 set, this option instructs the dirserver to bypass remote reach‐
530 ability testing too and list all connected servers as running.
531 ContactInfo email_address
533 Administrative contact information for server. This line might
534 get picked up by spam harvesters, so you may want to obscure the
535 fact that it's an email address.
536 ExitPolicy policy,policy,...
538 Set an exit policy for this server. Each policy is of the form
539 "accept|reject ADDR[/MASK][:PORT]". If /MASK is omitted then
540 this policy just applies to the host given. Instead of giving a
541 host or network you can also use "*" to denote the universe
542 (0.0.0.0/0). PORT can be a single port number, an interval of
543 ports "FROM_PORT-TO_PORT", or "*". If PORT is omitted, that
544 means "*".
545 For example, "accept 18.7.22.69:*,reject 18.0.0.0/8:*,accept
547 *:*" would reject any traffic destined for MIT except for
548 web.mit.edu, and accept anything else.
549 To specify all internal and link-local networks (including
551 0.0.0.0/8, 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16,
552 10.0.0.0/8, and 172.16.0.0/12), you can use the "private" alias
553 instead of an address. These addresses are rejected by default
554 (at the beginning of your exit policy) unless you set the Exit‐
555 PolicyRejectPrivate config option to 0. For example, once you've
556 done that, you could allow HTTP to 127.0.0.1 and block all other
557 connections to internal networks with "accept
558 127.0.0.1:80,reject private:*". See RFC 1918 and RFC 3330 for
559 more details about internal and reserved IP address space.
560 This directive can be specified multiple times so you don't have
562 to put it all on one line.
563 Policies are considered first to last, and the first match wins.
565 If you want to _replace_ the default exit policy, end your exit
566 policy with either a reject *:* or an accept *:*. Otherwise,
567 you're _augmenting_ (prepending to) the default exit policy. The
568 default exit policy is:
569 reject *:25
570 reject *:119
571 reject *:135-139
572 reject *:445
573 reject *:465
574 reject *:563
575 reject *:587
576 reject *:1214
577 reject *:4661-4666
578 reject *:6346-6429
579 reject *:6699
580 reject *:6881-6999
581 accept *:*
582 ExitPolicyRejectPrivate 0|1
584 Reject all private (local) networks at the beginning of your
585 exit policy. See above entry on ExitPolicy. (Default: 1)
586 MaxOnionsPending NUM
588 If you have more than this number of onionskins queued for
589 decrypt, reject new ones. (Default: 100)
590 MyFamily nickname,nickname,...
592 Declare that this Tor server is controlled or administered by a
593 group or organization identical or similar to that of the other
594 named servers. When two servers both declare that they are in
595 the same 'family', Tor clients will not use them in the same
596 circuit. (Each server only needs to list the other servers in
597 its family; it doesn't need to list itself, but it won't hurt.)
598 Nickname name
600 Set the server's nickname to 'name'. Nicknames must be between 1
601 and 19 characters inclusive, and must contain only the charac‐
602 ters [a-zA-Z0-9].
603 NumCPUs num
605 How many processes to use at once for decrypting onionskins.
606 (Default: 1)
607 ORPort PORT
609 Advertise this port to listen for connections from Tor clients
610 and servers.
611 ORListenAddress IP[:PORT]
613 Bind to this IP address to listen for connections from Tor
614 clients and servers. If you specify a port, bind to this port
615 rather than the one specified in ORPort. (Default: 0.0.0.0) This
616 directive can be specified multiple times to bind to multiple
617 addresses/ports.
618 PublishServerDescriptor 0|1
620 If set to 0, Tor will act as a server if you have an ORPort
621 defined, but it will not publish its descriptor to the
622 dirservers. This option is useful if you're testing out your
623 server, or if you're using a Tor controller that handles direc‐
624 tory publishing for you. (Default: 1)
625 RedirectExit pattern target
627 Whenever an outgoing connection tries to connect to one of a
628 given set of addresses, connect to target (an address:port pair)
629 instead. The address pattern is given in the same format as for
630 an exit policy. The address translation applies after exit
631 policies are applied. Multiple RedirectExit options can be
632 used: once any one has matched successfully, no subsequent rules
633 are considered. You can specify that no redirection is to be
634 performed on a given set of addresses by using the special tar‐
635 get string "pass", which prevents subsequent rules from being
636 considered.
637 ShutdownWaitLength NUM
639 When we get a SIGINT and we're a server, we begin shutting down:
640 we close listeners and start refusing new circuits. After NUM
641 seconds, we exit. If we get a second SIGINT, we exit immedi‐
642 ately. (Default: 30 seconds)
643 AccountingMax N bytes|KB|MB|GB|TB
645 Never send more than the specified number of bytes in a given
646 accounting period, or receive more than that number in the
647 period. For example, with AccountingMax set to 1 GB, a server
648 could send 900 MB and receive 800 MB and continue running. It
649 will only hibernate once one of the two reaches 1 GB. When the
650 number of bytes is exhausted, Tor will hibernate until some time
651 in the next accounting period. To prevent all servers from wak‐
652 ing at the same time, Tor will also wait until a random point in
653 each period before waking up. If you have bandwidth cost
654 issues, enabling hibernation is preferable to setting a low
655 bandwidth, since it provides users with a collection of fast
656 servers that are up some of the time, which is more useful than
657 a set of slow servers that are always "available".
658 AccountingStart day|week|month [day] HH:MM
660 Specify how long accounting periods last. If month is given,
661 each accounting period runs from the time HH:MM on the dayth day
662 of one month to the same day and time of the next. (The day
663 must be between 1 and 28.) If week is given, each accounting
664 period runs from the time HH:MM of the dayth day of one week to
665 the same day and time of the next week, with Monday as day 1 and
666 Sunday as day 7. If day is given, each accounting period runs
667 from the time HH:MM each day to the same time on the next day.
668 All times are local, and given in 24-hour time. (Defaults to
669 "month 1 0:00".)
670 ServerDNSResolvConfFile filename
672 Overrides the default DNS configuration with the configuration
673 in filename. The file format is the same as the standard Unix
674 "resolv.conf" file (7). This option, like all other ServerDNS
675 options, only affects name lookup that your server does on
676 behalf of clients. Also, it only takes effect if Tor was built
677 with eventdns support. (Defaults to use the system DNS configu‐
678 ration.)
679 ServerDNSSearchDomains 0|1
681 If set to 1, then we will search for addresses in the local
682 search domain. For example, if this system is configured to
683 believe it is in "example.com", and a client tries to connect to
684 "www", the client will be connected to "www.example.com". This
685 option only affects name lookup that your server does on behalf
686 of clients, and only takes effect if Tor was build with eventdns
687 support. (Defaults to "0".)
688 ServerDNSDetectHijacking 0|1
690 When this option is set to 1, we will test periodically to
691 determine whether our local nameservers have been configured to
692 hijack failing DNS requests (usually to an advertising site).
693 If they are, we will attempt to correct this. This option only
694 affects name lookup that your server does on behalf of clients,
695 and only takes effect if Tor was build with eventdns support.
696 (Defaults to "1".)
697 ServerDNSTestAddresses address,address,...
699 When we're detecting DNS hijacking, make sure that these valid
700 addresses aren't getting redirected. If they are, then our DNS
701 is completely useless, and we'll reset our exit policy to
702 "reject *:*". This option only affects name lookup that your
703 server does on behalf of clients, and only takes effect if Tor
704 was build with eventdns support. (Defaults to "www.google.com,
705 www.mit.edu, www.yahoo.com, www.slashdot.org".)
706 ServerDNSAllowNonRFC953Hostnames 0|1
708 When this option is disabled, Tor does not try to resolve host‐
709 names containing illegal characters (like @ and :) rather than
710 sending them to an exit node to be resolved. This helps trap
711 accidental attempts to resolve URLs and so on. This option only
712 affects name lookup that your server does on behalf of clients,
713 and only takes effect if Tor was build with eventdns support.
714 (Default: 0)
715
718 The following options are useful only for directory servers (that is,
719 if DirPort is non-zero):
720 AuthoritativeDirectory 0|1
722 When this option is set to 1, Tor operates as an authoritative
723 directory server. Instead of caching the directory, it gener‐
724 ates its own list of good servers, signs it, and sends that to
725 the clients. Unless the clients already have you listed as a
726 trusted directory, you probably do not want to set this option.
727 Please coordinate with the other admins at tor-ops@freehaven.net
728 if you think you should be a directory.
729 V1AuthoritativeDirectory 0|1
731 When this option is set in addition to AuthoritativeDirectory,
732 Tor also generates a version 1 directory (for Tor clients up to
733 0.1.0.x). (As of Tor 0.1.1.12 every (v2) authoritative direc‐
734 tory still provides most of the v1 directory functionality, even
735 without this option set to 1. This however is expected to
736 change in the future.)
737 VersioningAuthoritativeDirectory 0|1
739 When this option is set to 1, Tor adds information on which ver‐
740 sions of Tor are still believed safe for use to the published
741 directory. Each version 1 authority is automatically a version‐
742 ing authority; version 2 authorities provide this service
743 optionally. See RecommendedVersions, RecommendedClientVersions,
744 and RecommendedServerVersions.
745 NamingAuthoritativeDirectory 0|1
747 When this option is set to 1, then the server advertises that it
748 has opinions about nickname-to-fingerprint bindings. It will
749 include these opinions in its published network-status pages, by
750 listing servers with the flag "Named" if a correct binding
751 between that nickname and fingerprint has been registered with
752 the dirserver. Naming dirservers will refuse to accept or pub‐
753 lish descriptors that contradict a registered binding. See
754 approved-routers in the FILES section below.
755 HSAuthoritativeDir 0|1
757 When this option is set in addition to AuthoritativeDirectory,
758 Tor also accepts and serves hidden service descriptors.
759 (Default: 0)
760 DirPort PORT
762 Advertise the directory service on this port.
763 DirListenAddress IP[:PORT]
765 Bind the directory service to this address. If you specify a
766 port, bind to this port rather than the one specified in Dir‐
767 Port. (Default: 0.0.0.0) This directive can be specified multi‐
768 ple times to bind to multiple addresses/ports.
769 DirPolicy policy,policy,...
771 Set an entrance policy for this server, to limit who can connect
772 to the directory ports. The policies have the same form as exit
773 policies above.
774 RecommendedVersions STRING
776 STRING is a comma-separated list of Tor versions currently
777 believed to be safe. The list is included in each directory, and
778 nodes which pull down the directory learn whether they need to
779 upgrade. This option can appear multiple times: the values from
780 multiple lines are spliced together. When this is set then Ver‐
781 sioningAuthoritativeDirectory should be set too.
782 RecommendedClientVersions STRING
784 STRING is a comma-separated list of Tor versions currently
785 believed to be safe for clients to use. This information is
786 included in version 2 directories. If this is not set then the
787 value of RecommendedVersions is used. When this is set then
788 VersioningAuthoritativeDirectory should be set too.
789 RecommendedServerVersions STRING
791 STRING is a comma-separated list of Tor versions currently
792 believed to be safe for servers to use. This information is
793 included in version 2 directories. If this is not set then the
794 value of RecommendedVersions is used. When this is set then
795 VersioningAuthoritativeDirectory should be set too.
796 DirAllowPrivateAddresses 0|1
798 If set to 1, Tor will accept router descriptors with arbitrary
799 "Address" elements. Otherwise, if the address is not an IP or is
800 a private IP, it will reject the router descriptor. Defaults to
801 0.
802 AuthDirBadExit AddressPattern...
804 Authoritative directories only. A set of address patterns for
805 servers that will be listed as bad exits in any network status
806 document this authority publishes, if AuthDirListBadExits is
807 set.
808 AuthDirInvalid AddressPattern...
810 Authoritative directories only. A set of address patterns for
811 servers that will never be listed as "valid" in any network sta‐
812 tus document that this authority publishes.
813 AuthDirReject AddressPattern...
815 Authoritative directories only. A set of address patterns for
816 servers that will never be listed at all in any network status
817 document that this authority publishes, or accepted as an OR
818 address in any descriptor submitted for publication by this
819 authority.
820 AuthDirListBadExits 0|1
822 Authoritative directories only. If set to 1, this directory has
823 some opinion about which nodes are unsuitable as exit nodes.
824 (Do not set this to 1 unless you plan to list nonfunctioning
825 exits as bad; otherwise, you are effectively voting in favor of
826 every declared exit as an exit.)
827 AuthDirRejectUnlisted 0|1
829 Authoritative directories only. If set to 1, the directory
830 server rejects all uploaded server descriptors that aren't
831 explicitly listed in the fingerprints file. This acts as a
832 "panic button" if we get Sybiled. (Default: 0)
833
836 The following options are used to configure a hidden service.
837 HiddenServiceDir DIRECTORY
839 Store data files for a hidden service in DIRECTORY. Every hid‐
840 den service must have a separate directory. You may use this
841 option multiple times to specify multiple services.
842 HiddenServicePort VIRTPORT [TARGET]
844 Configure a virtual port VIRTPORT for a hidden service. You may
845 use this option multiple times; each time applies to the service
846 using the most recent hiddenservicedir. By default, this option
847 maps the virtual port to the same port on 127.0.0.1. You may
848 override the target port, address, or both by specifying a tar‐
849 get of addr, port, or addr:port.
850 HiddenServiceNodes nickname,nickname,...
852 If possible, use the specified nodes as introduction points for
853 the hidden service. If this is left unset, Tor will be smart and
854 pick some reasonable ones; most people can leave this unset.
855 HiddenServiceExcludeNodes nickname,nickname,...
857 Do not use the specified nodes as introduction points for the
858 hidden service. In normal use there is no reason to set this.
859 PublishHidServDescriptors 0|1
861 If set to 0, Tor will run any hidden services you configure, but
862 it won't advertise them to the rendezvous directory. This option
863 is only useful if you're using a Tor controller that handles
864 hidserv publishing for you. (Default: 1)
865 RendPostPeriod N seconds|minutes|hours|days|weeks
867 Every time the specified period elapses, Tor uploads any ren‐
868 dezvous service descriptors to the directory servers. This
869 information is also uploaded whenever it changes. (Default: 20
870 minutes)
871
875 Tor catches the following signals:
876 SIGTERM
878 Tor will catch this, clean up and sync to disk if necessary, and
879 exit.
880 SIGINT Tor clients behave as with SIGTERM; but Tor servers will do a
882 controlled slow shutdown, closing listeners and waiting 30 sec‐
883 onds before exiting. (The delay can be configured with the
884 ShutdownWaitLength config option.)
885 SIGHUP The signal instructs Tor to reload its configuration (including
887 closing and reopening logs), fetch a new directory, and kill and
888 restart its helper processes if applicable.
889 SIGUSR1
891 Log statistics about current connections, past connections, and
892 throughput.
893 SIGUSR2
895 Switch all logs to loglevel debug. You can go back to the old
896 loglevels by sending a SIGHUP.
897 SIGCHLD
899 Tor receives this signal when one of its helper processes has
900 exited, so it can clean up.
901 SIGPIPE
903 Tor catches this signal and ignores it.
904 SIGXFSZ
906 If this signal exists on your platform, Tor catches and ignores
907 it.
908
911 /etc/tor/torrc
912 The configuration file, which contains "option value" pairs.
913 /var/lib/tor/
915 The tor process stores keys and other data here.
916 DataDirectory/cached-status/*
918 The most recently downloaded network status document for each
919 authority. Each file holds one such document; the filenames are
920 the hexadecimal identity key fingerprints of the directory
921 authorities.
922 DataDirectory/cached-routers and cached-routers.new
924 These files hold downloaded router statuses. Some routers may
925 appear more than once; if so, the most recently published
926 descriptor is used. The ".new" file is an append-only journal;
927 when it gets too large, all entries are merged into a new
928 cached-routers file.
929 DataDirectory/state
931 A set of persistent key-value mappings. These are documented in
932 the file. These include:
933 - The current entry guards and their status.
934 - The current bandwidth accounting values (unused so far; see
935 below).
936 - When the file was last written
937 - What version of Tor generated the state file
938 - A short history of bandwidth usage, as produced in the router
939 descriptors.
940 DataDirectory/bw_accounting
942 Used to track bandwidth accounting values (when the current
943 period starts and ends; how much has been read and written so
944 far this period). This file is obsolete, and the data is now
945 stored in the 'state' file as well. Only used when bandwidth
946 accounting is enabled.
947 DataDirectory/control_auth_cookie
949 Used for cookie authentication with the controller. Regenerated
950 on startup. See control-spec.txt for details. Only used when
951 cookie authentication is enabled.
952 DataDirectory/keys/*
954 Only used by servers. Holds identity keys and onion keys.
955 DataDirectory/fingerprint
957 Only used by servers. Holds the fingerprint of the server's
958 identity key.
959 DataDirectory/approved-routers
961 Only for naming authoritative directory servers (see NamingAu‐
962 thoritativeDirectory). This file lists nickname to identity
963 bindings. Each line lists a nickname and a fingerprint sepa‐
964 rated by whitespace. See your fingerprint file in the DataDi‐
965 rectory for an example line. If the nickname is !reject then
966 descriptors from the given identity (fingerprint) are rejected
967 by this server. If it is !invalid then descriptors are accepted
968 but marked in the directory as not valid, that is, not recom‐
969 mended.
970 HiddenServiceDirectory/hostname
972 The <base32-encoded-fingerprint>.onion domain name for this hid‐
973 den service.
974 HiddenServiceDirectory/private_key
976 The private key for this hidden service.
977
979 privoxy(1), tsocks(1), torify(1)
980 http://tor.eff.org/
982
985 Plenty, probably. Tor is still in development. Please report them.
986
988 Roger Dingledine <arma@mit.edu>, Nick Mathewson <nickm@alum.mit.edu>.
989TOR January 2006 TOR(1)