1 // Copyright (c) The Tor Project, Inc.
2 // See LICENSE for licensing information
3 // This is an asciidoc file used to generate the manpage/html reference.
4 // Learn asciidoc on http://www.methods.co.nz/asciidoc/userguide.html
10 tor - The second-generation onion router
15 **tor** [__OPTION__ __value__]...
19 __tor__ is a connection-oriented anonymizing communication
20 service. Users choose a source-routed path through a set of nodes, and
21 negotiate a "virtual circuit" through the network, in which each node
22 knows its predecessor and successor, but no others. Traffic flowing down
23 the circuit is unwrapped by a symmetric key at each node, which reveals
24 the downstream node. +
26 Basically __tor__ provides a distributed network of servers ("onion routers").
27 Users bounce their TCP streams -- web traffic, ftp, ssh, etc -- around the
28 routers, and recipients, observers, and even the routers themselves have
29 difficulty tracking the source of the stream.
34 Display a short help message and exit.
37 FILE contains further "option value" pairs. (Default: @CONFDIR@/torrc)
40 Generates a hashed password for control port access.
42 **--list-fingerprint**::
43 Generate your keys and output your nickname and fingerprint.
46 Verify the configuration file is valid.
49 **--service [install|remove|start|stop]** Manage the Tor Windows
50 NT/2000/XP service. Current instructions can be found at
51 https://wiki.torproject.org/noreply/TheOnionRouter/TorFAQ#WinNTService
53 **--list-torrc-options**::
54 List all valid options.
57 Display Tor version and exit.
60 Do not start Tor with a console log unless explicitly requested to do so.
61 (By default, Tor starts out logging messages at level "notice" or higher to
62 the console, until it has parsed its configuration.)
64 Other options can be specified either on the command-line (--option
65 value), or in the configuration file (option value or option "value").
66 Options are case-insensitive. C-style escaped characters are allowed inside
67 quoted values. Options on the command line take precedence over
68 options found in the configuration file, except indicated otherwise. To
69 split one configuration entry into multiple lines, use a single \ before
70 the end of the line. Comments can be used in such multiline entries, but
71 they must start at the beginning of a line.
73 **BandwidthRate** __N__ **bytes**|**KB**|**MB**|**GB**::
74 A token bucket limits the average incoming bandwidth usage on this node to
75 the specified number of bytes per second, and the average outgoing
76 bandwidth usage to that same value. If you want to run a relay in the
77 public network, this needs to be _at the very least_ 20 KB (that is,
78 20480 bytes). (Default: 5 MB)
80 **BandwidthBurst** __N__ **bytes**|**KB**|**MB**|**GB**::
81 Limit the maximum token bucket size (also known as the burst) to the given
82 number of bytes in each direction. (Default: 10 MB)
84 **MaxAdvertisedBandwidth** __N__ **bytes**|**KB**|**MB**|**GB**::
85 If set, we will not advertise more than this amount of bandwidth for our
86 BandwidthRate. Server operators who want to reduce the number of clients
87 who ask to build circuits through them (since this is proportional to
88 advertised bandwidth rate) can thus reduce the CPU demands on their server
89 without impacting network performance.
91 **RelayBandwidthRate** __N__ **bytes**|**KB**|**MB**|**GB**::
92 If not 0, a separate token bucket limits the average incoming bandwidth
93 usage for \_relayed traffic_ on this node to the specified number of bytes
94 per second, and the average outgoing bandwidth usage to that same value.
95 Relayed traffic currently is calculated to include answers to directory
96 requests, but that may change in future versions. (Default: 0)
98 **RelayBandwidthBurst** __N__ **bytes**|**KB**|**MB**|**GB**::
99 If not 0, limit the maximum token bucket size (also known as the burst) for
100 \_relayed traffic_ to the given number of bytes in each direction.
103 **PerConnBWRate** __N__ **bytes**|**KB**|**MB**|**GB**::
104 If set, do separate rate limiting for each connection from a non-relay.
105 You should never need to change this value, since a network-wide value is
106 published in the consensus and your relay will use that value. (Default: 0)
108 **PerConnBWBurst** __N__ **bytes**|**KB**|**MB**|**GB**::
109 If set, do separate rate limiting for each connection from a non-relay.
110 You should never need to change this value, since a network-wide value is
111 published in the consensus and your relay will use that value. (Default: 0)
113 **ConnLimit** __NUM__::
114 The minimum number of file descriptors that must be available to the Tor
115 process before it will start. Tor will ask the OS for as many file
116 descriptors as the OS will allow (you can find this by "ulimit -H -n").
117 If this number is less than ConnLimit, then Tor will refuse to start. +
119 You probably don't need to adjust this. It has no effect on Windows
120 since that platform lacks getrlimit(). (Default: 1000)
122 **ConstrainedSockets** **0**|**1**::
123 If set, Tor will tell the kernel to attempt to shrink the buffers for all
124 sockets to the size specified in **ConstrainedSockSize**. This is useful for
125 virtual servers and other environments where system level TCP buffers may
126 be limited. If you're on a virtual server, and you encounter the "Error
127 creating network socket: No buffer space available" message, you are
128 likely experiencing this problem. +
130 The preferred solution is to have the admin increase the buffer pool for
131 the host itself via /proc/sys/net/ipv4/tcp_mem or equivalent facility;
132 this configuration option is a second-resort. +
134 The DirPort option should also not be used if TCP buffers are scarce. The
135 cached directory requests consume additional sockets which exacerbates
138 You should **not** enable this feature unless you encounter the "no buffer
139 space available" issue. Reducing the TCP buffers affects window size for
140 the TCP stream and will reduce throughput in proportion to round trip
141 time on long paths. (Default: 0.)
143 **ConstrainedSockSize** __N__ **bytes**|**KB**::
144 When **ConstrainedSockets** is enabled the receive and transmit buffers for
145 all sockets will be set to this limit. Must be a value between 2048 and
146 262144, in 1024 byte increments. Default of 8192 is recommended.
148 **ControlPort** __PORT__|**auto**::
149 If set, Tor will accept connections on this port and allow those
150 connections to control the Tor process using the Tor Control Protocol
151 (described in control-spec.txt). Note: unless you also specify one of
152 **HashedControlPassword** or **CookieAuthentication**, setting this
154 cause Tor to allow any process on the local host to control it. This
155 option is required for many Tor controllers; most use the value of 9051.
156 Set it to "auto" to have Tor pick a port for you. (Default: 0).
158 **ControlListenAddress** __IP__[:__PORT__]::
159 Bind the controller listener to this address. If you specify a port, bind
160 to this port rather than the one specified in ControlPort. We strongly
161 recommend that you leave this alone unless you know what you're doing,
162 since giving attackers access to your control listener is really
163 dangerous. (Default: 127.0.0.1) This directive can be specified multiple
164 times to bind to multiple addresses/ports.
166 **ControlSocket** __Path__::
167 Like ControlPort, but listens on a Unix domain socket, rather than a TCP
168 socket. (Unix and Unix-like systems only.)
170 **ControlSocketsGroupWritable** **0**|**1**::
171 If this option is set to 0, don't allow the filesystem group to read and
172 write unix sockets (e.g. ControlSocket). If the option is set to 1, make
173 the control socket readable and writable by the default GID. (Default: 0)
175 **HashedControlPassword** __hashed_password__::
176 Don't allow any connections on the control port except when the other
177 process knows the password whose one-way hash is __hashed_password__. You
178 can compute the hash of a password by running "tor --hash-password
179 __password__". You can provide several acceptable passwords by using more
180 than one HashedControlPassword line.
182 **CookieAuthentication** **0**|**1**::
183 If this option is set to 1, don't allow any connections on the control port
184 except when the connecting process knows the contents of a file named
185 "control_auth_cookie", which Tor will create in its data directory. This
186 authentication method should only be used on systems with good filesystem
187 security. (Default: 0)
189 **CookieAuthFile** __Path__::
190 If set, this option overrides the default location and file name
191 for Tor's cookie file. (See CookieAuthentication above.)
193 **CookieAuthFileGroupReadable** **0**|**1**|__Groupname__::
194 If this option is set to 0, don't allow the filesystem group to read the
195 cookie file. If the option is set to 1, make the cookie file readable by
196 the default GID. [Making the file readable by other groups is not yet
197 implemented; let us know if you need this for some reason.] (Default: 0).
199 **ControlPortWriteToFile** __Path__::
200 If set, Tor writes the address and port of any control port it opens to
201 this address. Usable by controllers to learn the actual control port
202 when ControlPort is set to "auto".
204 **ControlPortFileGroupReadable** **0**|**1**::
205 If this option is set to 0, don't allow the filesystem group to read the
206 control port file. If the option is set to 1, make the control port
207 file readable by the default GID. (Default: 0).
209 **DataDirectory** __DIR__::
210 Store working data in DIR (Default: @LOCALSTATEDIR@/lib/tor)
212 **DirServer** [__nickname__] [**flags**] __address__:__port__ __fingerprint__::
213 Use a nonstandard authoritative directory server at the provided address
214 and port, with the specified key fingerprint. This option can be repeated
215 many times, for multiple authoritative directory servers. Flags are
216 separated by spaces, and determine what kind of an authority this directory
217 is. By default, every authority is authoritative for current ("v2")-style
218 directories, unless the "no-v2" flag is given. If the "v1" flags is
219 provided, Tor will use this server as an authority for old-style (v1)
220 directories as well. (Only directory mirrors care about this.) Tor will
221 use this server as an authority for hidden service information if the "hs"
222 flag is set, or if the "v1" flag is set and the "no-hs" flag is **not** set.
223 Tor will use this authority as a bridge authoritative directory if the
224 "bridge" flag is set. If a flag "orport=**port**" is given, Tor will use the
225 given port when opening encrypted tunnels to the dirserver. Lastly, if a
226 flag "v3ident=**fp**" is given, the dirserver is a v3 directory authority
227 whose v3 long-term signing key has the fingerprint **fp**. +
229 If no **dirserver** line is given, Tor will use the default directory
230 servers. NOTE: this option is intended for setting up a private Tor
231 network with its own directory authorities. If you use it, you will be
232 distinguishable from other users, because you won't believe the same
235 **AlternateDirAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__ +
237 **AlternateHSAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__ +
239 **AlternateBridgeAuthority** [__nickname__] [**flags**] __address__:__port__ __ fingerprint__::
240 As DirServer, but replaces less of the default directory authorities. Using
241 AlternateDirAuthority replaces the default Tor directory authorities, but
242 leaves the hidden service authorities and bridge authorities in place.
243 Similarly, Using AlternateHSAuthority replaces the default hidden service
244 authorities, but not the directory or bridge authorities.
246 **DisableAllSwap** **0**|**1**::
247 If set to 1, Tor will attempt to lock all current and future memory pages,
248 so that memory cannot be paged out. Windows, OS X and Solaris are currently
249 not supported. We believe that this feature works on modern Gnu/Linux
250 distributions, and that it should work on *BSD systems (untested). This
251 option requires that you start your Tor as root, and you should use the
252 **User** option to properly reduce Tor's privileges. (Default: 0)
254 **FetchDirInfoEarly** **0**|**1**::
255 If set to 1, Tor will always fetch directory information like other
256 directory caches, even if you don't meet the normal criteria for fetching
257 early. Normal users should leave it off. (Default: 0)
259 **FetchDirInfoExtraEarly** **0**|**1**::
260 If set to 1, Tor will fetch directory information before other directory
261 caches. It will attempt to download directory information closer to the
262 start of the consensus period. Normal users should leave it off.
265 **FetchHidServDescriptors** **0**|**1**::
266 If set to 0, Tor will never fetch any hidden service descriptors from the
267 rendezvous directories. This option is only useful if you're using a Tor
268 controller that handles hidden service fetches for you. (Default: 1)
270 **FetchServerDescriptors** **0**|**1**::
271 If set to 0, Tor will never fetch any network status summaries or server
272 descriptors from the directory servers. This option is only useful if
273 you're using a Tor controller that handles directory fetches for you.
276 **FetchUselessDescriptors** **0**|**1**::
277 If set to 1, Tor will fetch every non-obsolete descriptor from the
278 authorities that it hears about. Otherwise, it will avoid fetching useless
279 descriptors, for example for routers that are not running. This option is
280 useful if you're using the contributed "exitlist" script to enumerate Tor
281 nodes that exit to certain addresses. (Default: 0)
283 **HTTPProxy** __host__[:__port__]::
284 Tor will make all its directory requests through this host:port (or host:80
285 if port is not specified), rather than connecting directly to any directory
288 **HTTPProxyAuthenticator** __username:password__::
289 If defined, Tor will use this username:password for Basic HTTP proxy
290 authentication, as in RFC 2617. This is currently the only form of HTTP
291 proxy authentication that Tor supports; feel free to submit a patch if you
292 want it to support others.
294 **HTTPSProxy** __host__[:__port__]::
295 Tor will make all its OR (SSL) connections through this host:port (or
296 host:443 if port is not specified), via HTTP CONNECT rather than connecting
297 directly to servers. You may want to set **FascistFirewall** to restrict
298 the set of ports you might try to connect to, if your HTTPS proxy only
299 allows connecting to certain ports.
301 **HTTPSProxyAuthenticator** __username:password__::
302 If defined, Tor will use this username:password for Basic HTTPS proxy
303 authentication, as in RFC 2617. This is currently the only form of HTTPS
304 proxy authentication that Tor supports; feel free to submit a patch if you
305 want it to support others.
307 **Socks4Proxy** __host__[:__port__]::
308 Tor will make all OR connections through the SOCKS 4 proxy at host:port
309 (or host:1080 if port is not specified).
311 **Socks5Proxy** __host__[:__port__]::
312 Tor will make all OR connections through the SOCKS 5 proxy at host:port
313 (or host:1080 if port is not specified).
315 **Socks5ProxyUsername** __username__ +
317 **Socks5ProxyPassword** __password__::
318 If defined, authenticate to the SOCKS 5 server using username and password
319 in accordance to RFC 1929. Both username and password must be between 1 and
322 **KeepalivePeriod** __NUM__::
323 To keep firewalls from expiring connections, send a padding keepalive cell
324 every NUM seconds on open connections that are in use. If the connection
325 has no open circuits, it will instead be closed after NUM seconds of
326 idleness. (Default: 5 minutes)
328 **Log** __minSeverity__[-__maxSeverity__] **stderr**|**stdout**|**syslog**::
329 Send all messages between __minSeverity__ and __maxSeverity__ to the standard
330 output stream, the standard error stream, or to the system log. (The
331 "syslog" value is only supported on Unix.) Recognized severity levels are
332 debug, info, notice, warn, and err. We advise using "notice" in most cases,
333 since anything more verbose may provide sensitive information to an
334 attacker who obtains the logs. If only one severity level is given, all
335 messages of that level or higher will be sent to the listed destination.
337 **Log** __minSeverity__[-__maxSeverity__] **file** __FILENAME__::
338 As above, but send log messages to the listed filename. The
339 "Log" option may appear more than once in a configuration file.
340 Messages are sent to all the logs that match their severity
343 **Log** **[**__domain__,...**]**__minSeverity__[-__maxSeverity__] ... **file** __FILENAME__ +
345 **Log** **[**__domain__,...**]**__minSeverity__[-__maxSeverity__] ... **stderr**|**stdout**|**syslog**::
346 As above, but select messages by range of log severity __and__ by a
347 set of "logging domains". Each logging domain corresponds to an area of
348 functionality inside Tor. You can specify any number of severity ranges
349 for a single log statement, each of them prefixed by a comma-separated
350 list of logging domains. You can prefix a domain with $$~$$ to indicate
351 negation, and use * to indicate "all domains". If you specify a severity
352 range without a list of domains, it matches all domains. +
354 This is an advanced feature which is most useful for debugging one or two
355 of Tor's subsystems at a time. +
357 The currently recognized domains are: general, crypto, net, config, fs,
358 protocol, mm, http, app, control, circ, rend, bug, dir, dirserv, or, edge,
359 acct, hist, and handshake. Domain names are case-insensitive. +
361 For example, "`Log [handshake]debug [~net,~mm]info notice stdout`" sends
362 to stdout: all handshake messages of any severity, all info-and-higher
363 messages from domains other than networking and memory management, and all
364 messages of severity notice or higher.
366 **LogMessageDomains** **0**|**1**::
367 If 1, Tor includes message domains with each log message. Every log
368 message currently has at least one domain; most currently have exactly
369 one. This doesn't affect controller log messages. (Default: 0)
371 **OutboundBindAddress** __IP__::
372 Make all outbound connections originate from the IP address specified. This
373 is only useful when you have multiple network interfaces, and you want all
374 of Tor's outgoing connections to use a single one. This setting will be
375 ignored for connections to the loopback addresses (127.0.0.0/8 and ::1).
377 **PidFile** __FILE__::
378 On startup, write our PID to FILE. On clean shutdown, remove
381 **ProtocolWarnings** **0**|**1**::
382 If 1, Tor will log with severity \'warn' various cases of other parties not
383 following the Tor specification. Otherwise, they are logged with severity
384 \'info'. (Default: 0)
386 **RunAsDaemon** **0**|**1**::
387 If 1, Tor forks and daemonizes to the background. This option has no effect
388 on Windows; instead you should use the --service command-line option.
392 **SafeLogging** **0**|**1**|**relay**::
393 Tor can scrub potentially sensitive strings from log messages (e.g.
394 addresses) by replacing them with the string [scrubbed]. This way logs can
395 still be useful, but they don't leave behind personally identifying
396 information about what sites a user might have visited. +
398 If this option is set to 0, Tor will not perform any scrubbing, if it is
399 set to 1, all potentially sensitive strings are replaced. If it is set to
400 relay, all log messages generated when acting as a relay are sanitized, but
401 all messages generated when acting as a client are not. (Default: 1)
404 On startup, setuid to this user and setgid to their primary group.
406 **HardwareAccel** **0**|**1**::
407 If non-zero, try to use built-in (static) crypto hardware acceleration when
408 available. (Default: 0)
410 **AccelName** __NAME__::
411 When using OpenSSL hardware crypto acceleration attempt to load the dynamic
412 engine of this name. This must be used for any dynamic hardware engine.
413 Names can be verified with the openssl engine command.
415 **AccelDir** __DIR__::
416 Specify this option if using dynamic hardware acceleration and the engine
417 implementation library resides somewhere other than the OpenSSL default.
419 **AvoidDiskWrites** **0**|**1**::
420 If non-zero, try to write to disk less frequently than we would otherwise.
421 This is useful when running on flash memory or other media that support
422 only a limited number of writes. (Default: 0)
424 **TunnelDirConns** **0**|**1**::
425 If non-zero, when a directory server we contact supports it, we will build
426 a one-hop circuit and make an encrypted connection via its ORPort.
429 **PreferTunneledDirConns** **0**|**1**::
430 If non-zero, we will avoid directory servers that don't support tunneled
431 directory connections, when possible. (Default: 1)
433 **CircuitPriorityHalflife** __NUM1__::
434 If this value is set, we override the default algorithm for choosing which
435 circuit's cell to deliver or relay next. When the value is 0, we
436 round-robin between the active circuits on a connection, delivering one
437 cell from each in turn. When the value is positive, we prefer delivering
438 cells from whichever connection has the lowest weighted cell count, where
439 cells are weighted exponentially according to the supplied
440 CircuitPriorityHalflife value (in seconds). If this option is not set at
441 all, we use the behavior recommended in the current consensus
442 networkstatus. This is an advanced option; you generally shouldn't have
443 to mess with it. (Default: not set.)
448 The following options are useful only for clients (that is, if
449 **SocksPort** is non-zero):
451 **AllowInvalidNodes** **entry**|**exit**|**middle**|**introduction**|**rendezvous**|**...**::
452 If some Tor servers are obviously not working right, the directory
453 authorities can manually mark them as invalid, meaning that it's not
454 recommended you use them for entry or exit positions in your circuits. You
455 can opt to use them in some circuit positions, though. The default is
456 "middle,rendezvous", and other choices are not advised.
458 **ExcludeSingleHopRelays** **0**|**1**::
459 This option controls whether circuits built by Tor will include relays with
460 the AllowSingleHopExits flag set to true. If ExcludeSingleHopRelays is set
461 to 0, these relays will be included. Note that these relays might be at
462 higher risk of being seized or observed, so they are not normally
463 included. Also note that relatively few clients turn off this option,
464 so using these relays might make your client stand out.
467 **Bridge** __IP__:__ORPort__ [fingerprint]::
468 When set along with UseBridges, instructs Tor to use the relay at
469 "IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint"
470 is provided (using the same format as for DirServer), we will verify that
471 the relay running at that location has the right fingerprint. We also use
472 fingerprint to look up the bridge descriptor at the bridge authority, if
473 it's provided and if UpdateBridgesFromAuthority is set too.
475 **LearnCircuitBuildTimeout** **0**|**1**::
476 If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1)
478 **CircuitBuildTimeout** __NUM__::
480 Try for at most NUM seconds when building circuits. If the circuit isn't
481 open in that time, give up on it. If LearnCircuitBuildTimeout is 1, this
482 value serves as the initial value to use before a timeout is learned. If
483 LearnCircuitBuildTimeout is 0, this value is the only value used.
484 (Default: 60 seconds.)
486 **CircuitIdleTimeout** __NUM__::
487 If we have kept a clean (never used) circuit around for NUM seconds, then
488 close it. This way when the Tor client is entirely idle, it can expire all
489 of its circuits, and then expire its TLS connections. Also, if we end up
490 making a circuit that is not useful for exiting any of the requests we're
491 receiving, it won't forever take up a slot in the circuit list. (Default: 1
494 **CircuitStreamTimeout** __NUM__::
495 If non-zero, this option overrides our internal timeout schedule for how
496 many seconds until we detach a stream from a circuit and try a new circuit.
497 If your network is particularly slow, you might want to set this to a
498 number like 60. (Default: 0)
500 **ClientOnly** **0**|**1**::
501 If set to 1, Tor will under no circumstances run as a server or serve
502 directory requests. The default is to run as a client unless ORPort is
503 configured. (Usually, you don't need to set this; Tor is pretty smart at
504 figuring out whether you are reliable and high-bandwidth enough to be a
505 useful server.) (Default: 0)
507 **ExcludeNodes** __node__,__node__,__...__::
508 A list of identity fingerprints, nicknames, country codes and address
509 patterns of nodes to avoid when building a circuit.
511 ExcludeNodes SlowServer, $ EFFFFFFFFFFFFFFF, \{cc}, 255.254.0.0/8) +
513 By default, this option is treated as a preference that Tor is allowed
514 to override in order to keep working.
515 For example, if you try to connect to a hidden service,
516 but you have excluded all of the hidden service's introduction points,
517 Tor will connect to one of them anyway. If you do not want this
518 behavior, set the StrictNodes option (documented below). +
520 Note also that if you are a relay, this (and the other node selection
521 options below) only affects your own circuits that Tor builds for you.
522 Clients can still build circuits through you to any node. Controllers
523 can tell Tor to build circuits through any node.
526 **ExcludeExitNodes** __node__,__node__,__...__::
527 A list of identity fingerprints, nicknames, country codes and address
528 patterns of nodes to never use when picking an exit node---that is, a
529 node that delivers traffic for you outside the Tor network. Note that any
530 node listed in ExcludeNodes is automatically considered to be part of this
531 list too. See also the caveats on the "ExitNodes" option below.
534 **ExitNodes** __node__,__node__,__...__::
535 A list of identity fingerprints, nicknames, country codes and address
536 patterns of nodes to use as exit node---that is, a
537 node that delivers traffic for you outside the Tor network. +
539 Note that if you list too few nodes here, or if you exclude too many exit
540 nodes with ExcludeExitNodes, you can degrade functionality. For example,
541 if none of the exits you list allows traffic on port 80 or 443, you won't
542 be able to browse the web. +
544 Note also that not every circuit is used to deliver traffic outside of
545 the Tor network. It is normal to see non-exit circuits (such as those
546 used to connect to hidden services, those that do directory fetches,
547 those used for relay reachability self-tests, and so on) that end
548 at a non-exit node. To
549 keep a node from being used entirely, see ExcludeNodes and StrictNodes. +
551 The ExcludeNodes option overrides this option: any node listed in both
552 ExitNodes and ExcludeNodes is treated as excluded. +
554 The .exit address notation, if enabled via AllowDotExit, overrides
557 **EntryNodes** __node__,__node__,__...__::
558 A list of identity fingerprints and nicknames of nodes
559 to use for the first hop in your normal circuits. (Country codes and
560 address patterns are not yet supported.) Normal circuits include all
561 circuits except for direct connections to directory servers. The Bridge
562 option overrides this option; if you have configured bridges and
563 UseBridges is 1, the Bridges are used as your entry nodes. +
565 The ExcludeNodes option overrides this option: any node listed in both
566 EntryNodes and ExcludeNodes is treated as excluded.
568 **StrictNodes** **0**|**1**::
569 If StrictNodes is set to 1, Tor will treat the ExcludeNodes option as a
570 requirement to follow for all the circuits you generate, even if doing so
571 will break functionality for you. If StrictNodes is set to 0, Tor will
572 still try to avoid nodes in the ExcludeNodes list, but it will err on the
573 side of avoiding unexpected errors. Specifically, StrictNodes 0 tells
574 Tor that it is okay to use an excluded node when it is *necessary* to
575 perform relay reachability self-tests, connect to
576 a hidden service, provide a hidden service to a client, fulfill a .exit
577 request, upload directory information, or download directory information.
580 **FascistFirewall** **0**|**1**::
581 If 1, Tor will only create outgoing connections to ORs running on ports
582 that your firewall allows (defaults to 80 and 443; see **FirewallPorts**).
583 This will allow you to run Tor as a client behind a firewall with
584 restrictive policies, but will not allow you to run as a server behind such
585 a firewall. If you prefer more fine-grained control, use
586 ReachableAddresses instead.
588 **FirewallPorts** __PORTS__::
589 A list of ports that your firewall allows you to connect to. Only used when
590 **FascistFirewall** is set. This option is deprecated; use ReachableAddresses
591 instead. (Default: 80, 443)
593 **HidServAuth** __onion-address__ __auth-cookie__ [__service-name__]::
594 Client authorization for a hidden service. Valid onion addresses contain 16
595 characters in a-z2-7 plus ".onion", and valid auth cookies contain 22
596 characters in A-Za-z0-9+/. The service name is only used for internal
597 purposes, e.g., for Tor controllers. This option may be used multiple times
598 for different hidden services. If a hidden service uses authorization and
599 this option is not set, the hidden service is not accessible. Hidden
600 services can be configured to require authorization using the
601 **HiddenServiceAuthorizeClient** option.
603 **ReachableAddresses** __ADDR__[/__MASK__][:__PORT__]...::
604 A comma-separated list of IP addresses and ports that your firewall allows
605 you to connect to. The format is as for the addresses in ExitPolicy, except
606 that "accept" is understood unless "reject" is explicitly provided. For
607 example, \'ReachableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept
608 \*:80' means that your firewall allows connections to everything inside net
609 99, rejects port 80 connections to net 18, and accepts connections to port
610 80 otherwise. (Default: \'accept \*:*'.)
612 **ReachableDirAddresses** __ADDR__[/__MASK__][:__PORT__]...::
613 Like **ReachableAddresses**, a list of addresses and ports. Tor will obey
614 these restrictions when fetching directory information, using standard HTTP
615 GET requests. If not set explicitly then the value of
616 **ReachableAddresses** is used. If **HTTPProxy** is set then these
617 connections will go through that proxy.
619 **ReachableORAddresses** __ADDR__[/__MASK__][:__PORT__]...::
620 Like **ReachableAddresses**, a list of addresses and ports. Tor will obey
621 these restrictions when connecting to Onion Routers, using TLS/SSL. If not
622 set explicitly then the value of **ReachableAddresses** is used. If
623 **HTTPSProxy** is set then these connections will go through that proxy. +
625 The separation between **ReachableORAddresses** and
626 **ReachableDirAddresses** is only interesting when you are connecting
627 through proxies (see **HTTPProxy** and **HTTPSProxy**). Most proxies limit
628 TLS connections (which Tor uses to connect to Onion Routers) to port 443,
629 and some limit HTTP GET requests (which Tor uses for fetching directory
630 information) to port 80.
632 **LongLivedPorts** __PORTS__::
633 A list of ports for services that tend to have long-running connections
634 (e.g. chat and interactive shells). Circuits for streams that use these
635 ports will contain only high-uptime nodes, to reduce the chance that a node
636 will go down before the stream is finished. (Default: 21, 22, 706, 1863,
637 5050, 5190, 5222, 5223, 6667, 6697, 8300)
639 **MapAddress** __address__ __newaddress__::
640 When a request for address arrives to Tor, it will rewrite it to newaddress
641 before processing it. For example, if you always want connections to
642 www.indymedia.org to exit via __torserver__ (where __torserver__ is the
643 nickname of the server), use "MapAddress www.indymedia.org
644 www.indymedia.org.torserver.exit".
646 **NewCircuitPeriod** __NUM__::
647 Every NUM seconds consider whether to build a new circuit. (Default: 30
650 **MaxCircuitDirtiness** __NUM__::
651 Feel free to reuse a circuit that was first used at most NUM seconds ago,
652 but never attach a new stream to a circuit that is too old. (Default: 10
655 **NodeFamily** __node__,__node__,__...__::
656 The Tor servers, defined by their identity fingerprints or nicknames,
657 constitute a "family" of similar or co-administered servers, so never use
658 any two of them in the same circuit. Defining a NodeFamily is only needed
659 when a server doesn't list the family itself (with MyFamily). This option
660 can be used multiple times.
662 **EnforceDistinctSubnets** **0**|**1**::
663 If 1, Tor will not put two servers whose IP addresses are "too close" on
664 the same circuit. Currently, two addresses are "too close" if they lie in
665 the same /16 range. (Default: 1)
667 **SocksPort** __PORT__|**auto**::
668 Advertise this port to listen for connections from Socks-speaking
669 applications. Set this to 0 if you don't want to allow application
670 connections via SOCKS. Set it to "auto" to have Tor pick a port for
673 **SocksListenAddress** __IP__[:__PORT__]::
674 Bind to this address to listen for connections from Socks-speaking
675 applications. (Default: 127.0.0.1) You can also specify a port (e.g.
676 192.168.0.1:9100). This directive can be specified multiple times to bind
677 to multiple addresses/ports.
679 **SocksPolicy** __policy__,__policy__,__...__::
680 Set an entrance policy for this server, to limit who can connect to the
681 SocksPort and DNSPort ports. The policies have the same form as exit
684 **SocksTimeout** __NUM__::
685 Let a socks connection wait NUM seconds handshaking, and NUM seconds
686 unattached waiting for an appropriate circuit, before we fail it. (Default:
689 **TrackHostExits** __host__,__.domain__,__...__::
690 For each value in the comma separated list, Tor will track recent
691 connections to hosts that match this value and attempt to reuse the same
692 exit node for each. If the value is prepended with a \'.\', it is treated as
693 matching an entire domain. If one of the values is just a \'.', it means
694 match everything. This option is useful if you frequently connect to sites
695 that will expire all your authentication cookies (i.e. log you out) if
696 your IP address changes. Note that this option does have the disadvantage
697 of making it more clear that a given history is associated with a single
698 user. However, most people who would wish to observe this will observe it
699 through cookies or other protocol-specific means anyhow.
701 **TrackHostExitsExpire** __NUM__::
702 Since exit servers go up and down, it is desirable to expire the
703 association between host and exit server after NUM seconds. The default is
704 1800 seconds (30 minutes).
706 **UpdateBridgesFromAuthority** **0**|**1**::
707 When set (along with UseBridges), Tor will try to fetch bridge descriptors
708 from the configured bridge authorities when feasible. It will fall back to
709 a direct request if the authority responds with a 404. (Default: 0)
711 **UseBridges** **0**|**1**::
712 When set, Tor will fetch descriptors for each bridge listed in the "Bridge"
713 config lines, and use these relays as both entry guards and directory
716 **UseEntryGuards** **0**|**1**::
717 If this option is set to 1, we pick a few long-term entry servers, and try
718 to stick with them. This is desirable because constantly changing servers
719 increases the odds that an adversary who owns some servers will observe a
720 fraction of your paths. (Defaults to 1.)
722 **NumEntryGuards** __NUM__::
723 If UseEntryGuards is set to 1, we will try to pick a total of NUM routers
724 as long-term entries for our circuits. (Defaults to 3.)
726 **SafeSocks** **0**|**1**::
727 When this option is enabled, Tor will reject application connections that
728 use unsafe variants of the socks protocol -- ones that only provide an IP
729 address, meaning the application is doing a DNS resolve first.
730 Specifically, these are socks4 and socks5 when not doing remote DNS.
733 **TestSocks** **0**|**1**::
734 When this option is enabled, Tor will make a notice-level log entry for
735 each connection to the Socks port indicating whether the request used a
736 safe socks protocol or an unsafe one (see above entry on SafeSocks). This
737 helps to determine whether an application using Tor is possibly leaking
738 DNS requests. (Default: 0)
740 **WarnUnsafeSocks** **0**|**1**::
741 When this option is enabled, Tor will warn whenever a request is
742 received that only contains an IP address instead of a hostname. Allowing
743 applications to do DNS resolves themselves is usually a bad idea and
744 can leak your location to attackers. (Default: 1)
746 **VirtualAddrNetwork** __Address__/__bits__::
747 When Tor needs to assign a virtual (unused) address because of a MAPADDRESS
748 command from the controller or the AutomapHostsOnResolve feature, Tor
749 picks an unassigned address from this range. (Default:
752 When providing proxy server service to a network of computers using a tool
753 like dns-proxy-tor, change this address to "10.192.0.0/10" or
754 "172.16.0.0/12". The default **VirtualAddrNetwork** address range on a
755 properly configured machine will route to the loopback interface. For
756 local use, no change to the default VirtualAddrNetwork setting is needed.
758 **AllowNonRFC953Hostnames** **0**|**1**::
759 When this option is disabled, Tor blocks hostnames containing illegal
760 characters (like @ and :) rather than sending them to an exit node to be
761 resolved. This helps trap accidental attempts to resolve URLs and so on.
764 **AllowDotExit** **0**|**1**::
765 If enabled, we convert "www.google.com.foo.exit" addresses on the
766 SocksPort/TransPort/NATDPort into "www.google.com" addresses that exit from
767 the node "foo". Disabled by default since attacking websites and exit
768 relays can use it to manipulate your path selection. (Default: 0)
770 **FastFirstHopPK** **0**|**1**::
771 When this option is disabled, Tor uses the public key step for the first
772 hop of creating circuits. Skipping it is generally safe since we have
773 already used TLS to authenticate the relay and to establish forward-secure
774 keys. Turning this option off makes circuit building slower. +
776 Note that Tor will always use the public key step for the first hop if it's
777 operating as a relay, and it will never use the public key step if it
778 doesn't yet know the onion key of the first hop. (Default: 1)
780 **TransPort** __PORT__|**auto**::
781 If non-zero, enables transparent proxy support on __PORT__ (by convention,
782 9040). Requires OS support for transparent proxies, such as BSDs' pf or
783 Linux's IPTables. If you're planning to use Tor as a transparent proxy for
784 a network, you'll want to examine and change VirtualAddrNetwork from the
785 default setting. You'll also want to set the TransListenAddress option for
786 the network you'd like to proxy. Set it to "auto" to have Tor pick a
787 port for you. (Default: 0).
789 **TransListenAddress** __IP__[:__PORT__]::
790 Bind to this address to listen for transparent proxy connections. (Default:
791 127.0.0.1). This is useful for exporting a transparent proxy server to an
794 **NATDPort** __PORT__|**auto**::
795 Allow old versions of ipfw (as included in old versions of FreeBSD, etc.)
796 to send connections through Tor using the NATD protocol. This option is
797 only for people who cannot use TransPort. Set it to "auto" to have Tor
798 pick a port for you. (Default: 0)
800 **NATDListenAddress** __IP__[:__PORT__]::
801 Bind to this address to listen for NATD connections. (Default: 127.0.0.1).
803 **AutomapHostsOnResolve** **0**|**1**::
804 When this option is enabled, and we get a request to resolve an address
805 that ends with one of the suffixes in **AutomapHostsSuffixes**, we map an
806 unused virtual address to that address, and return the new virtual address.
807 This is handy for making ".onion" addresses work with applications that
808 resolve an address and then connect to it. (Default: 0).
810 **AutomapHostsSuffixes** __SUFFIX__,__SUFFIX__,__...__::
811 A comma-separated list of suffixes to use with **AutomapHostsOnResolve**.
812 The "." suffix is equivalent to "all addresses." (Default: .exit,.onion).
814 **DNSPort** __PORT__|**auto**::
815 If non-zero, Tor listens for UDP DNS requests on this port and resolves
816 them anonymously. Set it to "auto" to have Tor pick a port for
819 **DNSListenAddress** __IP__[:__PORT__]::
820 Bind to this address to listen for DNS connections. (Default: 127.0.0.1).
822 **ClientDNSRejectInternalAddresses** **0**|**1**::
823 If true, Tor does not believe any anonymously retrieved DNS answer that
824 tells it that an address resolves to an internal address (like 127.0.0.1 or
825 192.168.0.1). This option prevents certain browser-based attacks; don't
826 turn it off unless you know what you're doing. (Default: 1).
828 **ClientRejectInternalAddresses** **0**|**1**::
829 If true, Tor does not try to fulfill requests to connect to an internal
830 address (like 127.0.0.1 or 192.168.0.1) __unless a exit node is
831 specifically requested__ (for example, via a .exit hostname, or a
832 controller request). (Default: 1).
834 **DownloadExtraInfo** **0**|**1**::
835 If true, Tor downloads and caches "extra-info" documents. These documents
836 contain information about servers other than the information in their
837 regular router descriptors. Tor does not use this information for anything
838 itself; to save bandwidth, leave this option turned off. (Default: 0).
840 **FallbackNetworkstatusFile** __FILENAME__::
841 If Tor doesn't have a cached networkstatus file, it starts out using this
842 one instead. Even if this file is out of date, Tor can still use it to
843 learn about directory mirrors, so it doesn't need to put load on the
844 authorities. (Default: None).
846 **WarnPlaintextPorts** __port__,__port__,__...__::
847 Tells Tor to issue a warnings whenever the user tries to make an anonymous
848 connection to one of these ports. This option is designed to alert users
849 to services that risk sending passwords in the clear. (Default:
852 **RejectPlaintextPorts** __port__,__port__,__...__::
853 Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor
854 will instead refuse to make the connection. (Default: None).
856 **AllowSingleHopCircuits** **0**|**1**::
857 When this option is set, the attached Tor controller can use relays
858 that have the **AllowSingleHopExits** option turned on to build
859 one-hop Tor connections. (Default: 0)
864 The following options are useful only for servers (that is, if ORPort
867 **Address** __address__::
868 The IP address or fully qualified domain name of this server (e.g.
869 moria.mit.edu). You can leave this unset, and Tor will guess your IP
870 address. This IP address is the one used to tell clients and other
871 servers where to find your Tor server; it doesn't affect the IP that your
872 Tor client binds to. To bind to a different address, use the
873 *ListenAddress and OutboundBindAddress options.
875 **AllowSingleHopExits** **0**|**1**::
876 This option controls whether clients can use this server as a single hop
877 proxy. If set to 1, clients can use this server as an exit even if it is
878 the only hop in the circuit. Note that most clients will refuse to use
879 servers that set this option, since most clients have
880 ExcludeSingleHopRelays set. (Default: 0)
882 **AssumeReachable** **0**|**1**::
883 This option is used when bootstrapping a new Tor network. If set to 1,
884 don't do self-reachability testing; just upload your server descriptor
885 immediately. If **AuthoritativeDirectory** is also set, this option
886 instructs the dirserver to bypass remote reachability testing too and list
887 all connected servers as running.
889 **BridgeRelay** **0**|**1**::
890 Sets the relay to act as a "bridge" with respect to relaying connections
891 from bridge users to the Tor network. It mainly causes Tor to publish a
892 server descriptor to the bridge database, rather than publishing a relay
893 descriptor to the public directory authorities.
895 **ContactInfo** __email_address__::
896 Administrative contact information for server. This line might get picked
897 up by spam harvesters, so you may want to obscure the fact that it's an
900 **ExitPolicy** __policy__,__policy__,__...__::
901 Set an exit policy for this server. Each policy is of the form
902 "**accept**|**reject** __ADDR__[/__MASK__][:__PORT__]". If /__MASK__ is
903 omitted then this policy just applies to the host given. Instead of giving
904 a host or network you can also use "\*" to denote the universe (0.0.0.0/0).
905 __PORT__ can be a single port number, an interval of ports
906 "__FROM_PORT__-__TO_PORT__", or "\*". If __PORT__ is omitted, that means
909 For example, "accept 18.7.22.69:\*,reject 18.0.0.0/8:\*,accept \*:\*" would
910 reject any traffic destined for MIT except for web.mit.edu, and accept
913 To specify all internal and link-local networks (including 0.0.0.0/8,
914 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16, 10.0.0.0/8, and
915 172.16.0.0/12), you can use the "private" alias instead of an address.
916 These addresses are rejected by default (at the beginning of your exit
917 policy), along with your public IP address, unless you set the
918 ExitPolicyRejectPrivate config option to 0. For example, once you've done
919 that, you could allow HTTP to 127.0.0.1 and block all other connections to
920 internal networks with "accept 127.0.0.1:80,reject private:\*", though that
921 may also allow connections to your own computer that are addressed to its
922 public (external) IP address. See RFC 1918 and RFC 3330 for more details
923 about internal and reserved IP address space. +
925 This directive can be specified multiple times so you don't have to put it
928 Policies are considered first to last, and the first match wins. If you
929 want to \_replace_ the default exit policy, end your exit policy with
930 either a reject \*:* or an accept \*:*. Otherwise, you're \_augmenting_
931 (prepending to) the default exit policy. The default exit policy is: +
945 **ExitPolicyRejectPrivate** **0**|**1**::
946 Reject all private (local) networks, along with your own public IP address,
947 at the beginning of your exit policy. See above entry on ExitPolicy.
950 **MaxOnionsPending** __NUM__::
951 If you have more than this number of onionskins queued for decrypt, reject
952 new ones. (Default: 100)
954 **MyFamily** __node__,__node__,__...__::
955 Declare that this Tor server is controlled or administered by a group or
956 organization identical or similar to that of the other servers, defined by
957 their identity fingerprints or nicknames. When two servers both declare
958 that they are in the same \'family', Tor clients will not use them in the
959 same circuit. (Each server only needs to list the other servers in its
960 family; it doesn't need to list itself, but it won't hurt.)
962 **Nickname** __name__::
963 Set the server's nickname to \'name'. Nicknames must be between 1 and 19
964 characters inclusive, and must contain only the characters [a-zA-Z0-9].
966 **NumCPUs** __num__::
967 How many processes to use at once for decrypting onionskins. (Default: 1)
969 **ORPort** __PORT__|**auto**::
970 Advertise this port to listen for connections from Tor clients and
971 servers. This option is required to be a Tor server.
972 Set it to "auto" to have Tor pick a port for you. (Default: 0).
974 **ORListenAddress** __IP__[:__PORT__]::
975 Bind to this IP address to listen for connections from Tor clients and
976 servers. If you specify a port, bind to this port rather than the one
977 specified in ORPort. (Default: 0.0.0.0) This directive can be specified
978 multiple times to bind to multiple addresses/ports.
980 **PublishServerDescriptor** **0**|**1**|**v1**|**v2**|**v3**|**bridge**,**...**::
981 This option specifies which descriptors Tor will publish when acting as
983 choose multiple arguments, separated by commas.
985 If this option is set to 0, Tor will not publish its
986 descriptors to any directories. (This is useful if you're testing
987 out your server, or if you're using a Tor controller that handles directory
988 publishing for you.) Otherwise, Tor will publish its descriptors of all
989 type(s) specified. The default is "1",
990 which means "if running as a server, publish the
991 appropriate descriptors to the authorities".
993 **ShutdownWaitLength** __NUM__::
994 When we get a SIGINT and we're a server, we begin shutting down:
995 we close listeners and start refusing new circuits. After **NUM**
996 seconds, we exit. If we get a second SIGINT, we exit immedi-
997 ately. (Default: 30 seconds)
1000 **AccountingMax** __N__ **bytes**|**KB**|**MB**|**GB**|**TB**::
1001 Never send more than the specified number of bytes in a given accounting
1002 period, or receive more than that number in the period. For example, with
1003 AccountingMax set to 1 GB, a server could send 900 MB and receive 800 MB
1004 and continue running. It will only hibernate once one of the two reaches 1
1005 GB. When the number of bytes gets low, Tor will stop accepting new
1006 connections and circuits. When the number of bytes
1007 is exhausted, Tor will hibernate until some
1008 time in the next accounting period. To prevent all servers from waking at
1009 the same time, Tor will also wait until a random point in each period
1010 before waking up. If you have bandwidth cost issues, enabling hibernation
1011 is preferable to setting a low bandwidth, since it provides users with a
1012 collection of fast servers that are up some of the time, which is more
1013 useful than a set of slow servers that are always "available".
1015 **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__::
1016 Specify how long accounting periods last. If **month** is given, each
1017 accounting period runs from the time __HH:MM__ on the __dayth__ day of one
1018 month to the same day and time of the next. (The day must be between 1 and
1019 28.) If **week** is given, each accounting period runs from the time __HH:MM__
1020 of the __dayth__ day of one week to the same day and time of the next week,
1021 with Monday as day 1 and Sunday as day 7. If **day** is given, each
1022 accounting period runs from the time __HH:MM__ each day to the same time on
1023 the next day. All times are local, and given in 24-hour time. (Defaults to
1026 **RefuseUnknownExits** **0**|**1**|**auto**::
1027 Prevent nodes that don't appear in the consensus from exiting using this
1028 relay. If the option is 1, we always block exit attempts from such
1029 nodes; if it's 0, we never do, and if the option is "auto", then we do
1030 whatever the authorities suggest in the consensus. (Defaults to auto.)
1032 **ServerDNSResolvConfFile** __filename__::
1033 Overrides the default DNS configuration with the configuration in
1034 __filename__. The file format is the same as the standard Unix
1035 "**resolv.conf**" file (7). This option, like all other ServerDNS options,
1036 only affects name lookups that your server does on behalf of clients.
1037 (Defaults to use the system DNS configuration.)
1039 **ServerDNSAllowBrokenConfig** **0**|**1**::
1040 If this option is false, Tor exits immediately if there are problems
1041 parsing the system DNS configuration or connecting to nameservers.
1042 Otherwise, Tor continues to periodically retry the system nameservers until
1043 it eventually succeeds. (Defaults to "1".)
1045 **ServerDNSSearchDomains** **0**|**1**::
1046 If set to 1, then we will search for addresses in the local search domain.
1047 For example, if this system is configured to believe it is in
1048 "example.com", and a client tries to connect to "www", the client will be
1049 connected to "www.example.com". This option only affects name lookups that
1050 your server does on behalf of clients. (Defaults to "0".)
1052 **ServerDNSDetectHijacking** **0**|**1**::
1053 When this option is set to 1, we will test periodically to determine
1054 whether our local nameservers have been configured to hijack failing DNS
1055 requests (usually to an advertising site). If they are, we will attempt to
1056 correct this. This option only affects name lookups that your server does
1057 on behalf of clients. (Defaults to "1".)
1059 **ServerDNSTestAddresses** __address__,__address__,__...__::
1060 When we're detecting DNS hijacking, make sure that these __valid__ addresses
1061 aren't getting redirected. If they are, then our DNS is completely useless,
1062 and we'll reset our exit policy to "reject *:*". This option only affects
1063 name lookups that your server does on behalf of clients. (Defaults to
1064 "www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org".)
1066 **ServerDNSAllowNonRFC953Hostnames** **0**|**1**::
1067 When this option is disabled, Tor does not try to resolve hostnames
1068 containing illegal characters (like @ and :) rather than sending them to an
1069 exit node to be resolved. This helps trap accidental attempts to resolve
1070 URLs and so on. This option only affects name lookups that your server does
1071 on behalf of clients. (Default: 0)
1073 **BridgeRecordUsageByCountry** **0**|**1**::
1074 When this option is enabled and BridgeRelay is also enabled, and we have
1075 GeoIP data, Tor keeps a keep a per-country count of how many client
1076 addresses have contacted it so that it can help the bridge authority guess
1077 which countries have blocked access to it. (Default: 1)
1079 **ServerDNSRandomizeCase** **0**|**1**::
1080 When this option is set, Tor sets the case of each character randomly in
1081 outgoing DNS requests, and makes sure that the case matches in DNS replies.
1082 This so-called "0x20 hack" helps resist some types of DNS poisoning attack.
1083 For more information, see "Increased DNS Forgery Resistance through
1084 0x20-Bit Encoding". This option only affects name lookups that your server
1085 does on behalf of clients. (Default: 1)
1087 **GeoIPFile** __filename__::
1088 A filename containing GeoIP data, for use with BridgeRecordUsageByCountry.
1090 **CellStatistics** **0**|**1**::
1091 When this option is enabled, Tor writes statistics on the mean time that
1092 cells spend in circuit queues to disk every 24 hours. (Default: 0)
1094 **DirReqStatistics** **0**|**1**::
1095 When this option is enabled, Tor writes statistics on the number and
1096 response time of network status requests to disk every 24 hours.
1099 **EntryStatistics** **0**|**1**::
1100 When this option is enabled, Tor writes statistics on the number of
1101 directly connecting clients to disk every 24 hours. (Default: 0)
1103 **ExitPortStatistics** **0**|**1**::
1104 When this option is enabled, Tor writes statistics on the number of relayed
1105 bytes and opened stream per exit port to disk every 24 hours. (Default: 0)
1107 **ExtraInfoStatistics** **0**|**1**::
1108 When this option is enabled, Tor includes previously gathered statistics in
1109 its extra-info documents that it uploads to the directory authorities.
1112 DIRECTORY SERVER OPTIONS
1113 ------------------------
1115 The following options are useful only for directory servers (that is,
1116 if DirPort is non-zero):
1118 **AuthoritativeDirectory** **0**|**1**::
1119 When this option is set to 1, Tor operates as an authoritative directory
1120 server. Instead of caching the directory, it generates its own list of
1121 good servers, signs it, and sends that to the clients. Unless the clients
1122 already have you listed as a trusted directory, you probably do not want
1123 to set this option. Please coordinate with the other admins at
1124 tor-ops@torproject.org if you think you should be a directory.
1126 **DirPortFrontPage** __FILENAME__::
1127 When this option is set, it takes an HTML file and publishes it as "/" on
1128 the DirPort. Now relay operators can provide a disclaimer without needing
1129 to set up a separate webserver. There's a sample disclaimer in
1130 contrib/tor-exit-notice.html.
1132 **V1AuthoritativeDirectory** **0**|**1**::
1133 When this option is set in addition to **AuthoritativeDirectory**, Tor
1134 generates version 1 directory and running-routers documents (for legacy
1135 Tor clients up to 0.1.0.x).
1137 **V2AuthoritativeDirectory** **0**|**1**::
1138 When this option is set in addition to **AuthoritativeDirectory**, Tor
1139 generates version 2 network statuses and serves descriptors, etc as
1140 described in doc/spec/dir-spec-v2.txt (for Tor clients and servers running
1141 0.1.1.x and 0.1.2.x).
1143 **V3AuthoritativeDirectory** **0**|**1**::
1144 When this option is set in addition to **AuthoritativeDirectory**, Tor
1145 generates version 3 network statuses and serves descriptors, etc as
1146 described in doc/spec/dir-spec.txt (for Tor clients and servers running at
1149 **VersioningAuthoritativeDirectory** **0**|**1**::
1150 When this option is set to 1, Tor adds information on which versions of
1151 Tor are still believed safe for use to the published directory. Each
1152 version 1 authority is automatically a versioning authority; version 2
1153 authorities provide this service optionally. See **RecommendedVersions**,
1154 **RecommendedClientVersions**, and **RecommendedServerVersions**.
1156 **NamingAuthoritativeDirectory** **0**|**1**::
1157 When this option is set to 1, then the server advertises that it has
1158 opinions about nickname-to-fingerprint bindings. It will include these
1159 opinions in its published network-status pages, by listing servers with
1160 the flag "Named" if a correct binding between that nickname and fingerprint
1161 has been registered with the dirserver. Naming dirservers will refuse to
1162 accept or publish descriptors that contradict a registered binding. See
1163 **approved-routers** in the **FILES** section below.
1165 **HSAuthoritativeDir** **0**|**1**::
1166 When this option is set in addition to **AuthoritativeDirectory**, Tor also
1167 accepts and serves v0 hidden service descriptors,
1168 which are produced and used by Tor 0.2.1.x and older. (Default: 0)
1170 **HidServDirectoryV2** **0**|**1**::
1171 When this option is set, Tor accepts and serves v2 hidden service
1172 descriptors. Setting DirPort is not required for this, because clients
1173 connect via the ORPort by default. (Default: 1)
1175 **BridgeAuthoritativeDir** **0**|**1**::
1176 When this option is set in addition to **AuthoritativeDirectory**, Tor
1177 accepts and serves router descriptors, but it caches and serves the main
1178 networkstatus documents rather than generating its own. (Default: 0)
1180 **MinUptimeHidServDirectoryV2** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
1181 Minimum uptime of a v2 hidden service directory to be accepted as such by
1182 authoritative directories. (Default: 24 hours)
1184 **DirPort** __PORT__|**auto**::
1185 If this option is nonzero, advertise the directory service on this port.
1186 Set it to "auto" to have Tor pick a port for you. (Default: 0)
1188 **DirListenAddress** __IP__[:__PORT__]::
1189 Bind the directory service to this address. If you specify a port, bind to
1190 this port rather than the one specified in DirPort. (Default: 0.0.0.0)
1191 This directive can be specified multiple times to bind to multiple
1194 **DirPolicy** __policy__,__policy__,__...__::
1195 Set an entrance policy for this server, to limit who can connect to the
1196 directory ports. The policies have the same form as exit policies above.
1198 **FetchV2Networkstatus** **0**|**1**::
1199 If set, we try to fetch the (obsolete, unused) version 2 network status
1200 consensus documents from the directory authorities. No currently
1201 supported Tor version uses them. (Default: 0.)
1204 DIRECTORY AUTHORITY SERVER OPTIONS
1205 ----------------------------------
1207 **RecommendedVersions** __STRING__::
1208 STRING is a comma-separated list of Tor versions currently believed to be
1209 safe. The list is included in each directory, and nodes which pull down the
1210 directory learn whether they need to upgrade. This option can appear
1211 multiple times: the values from multiple lines are spliced together. When
1212 this is set then **VersioningAuthoritativeDirectory** should be set too.
1214 **RecommendedClientVersions** __STRING__::
1215 STRING is a comma-separated list of Tor versions currently believed to be
1216 safe for clients to use. This information is included in version 2
1217 directories. If this is not set then the value of **RecommendedVersions**
1218 is used. When this is set then **VersioningAuthoritativeDirectory** should
1221 **RecommendedServerVersions** __STRING__::
1222 STRING is a comma-separated list of Tor versions currently believed to be
1223 safe for servers to use. This information is included in version 2
1224 directories. If this is not set then the value of **RecommendedVersions**
1225 is used. When this is set then **VersioningAuthoritativeDirectory** should
1228 **ConsensusParams** __STRING__::
1229 STRING is a space-separated list of key=value pairs that Tor will include
1230 in the "params" line of its networkstatus vote.
1232 **DirAllowPrivateAddresses** **0**|**1**::
1233 If set to 1, Tor will accept router descriptors with arbitrary "Address"
1234 elements. Otherwise, if the address is not an IP address or is a private IP
1235 address, it will reject the router descriptor. Defaults to 0.
1237 **AuthDirBadDir** __AddressPattern...__::
1238 Authoritative directories only. A set of address patterns for servers that
1239 will be listed as bad directories in any network status document this
1240 authority publishes, if **AuthDirListBadDirs** is set.
1242 **AuthDirBadExit** __AddressPattern...__::
1243 Authoritative directories only. A set of address patterns for servers that
1244 will be listed as bad exits in any network status document this authority
1245 publishes, if **AuthDirListBadExits** is set.
1247 **AuthDirInvalid** __AddressPattern...__::
1248 Authoritative directories only. A set of address patterns for servers that
1249 will never be listed as "valid" in any network status document that this
1250 authority publishes.
1252 **AuthDirReject** __AddressPattern__...::
1253 Authoritative directories only. A set of address patterns for servers that
1254 will never be listed at all in any network status document that this
1255 authority publishes, or accepted as an OR address in any descriptor
1256 submitted for publication by this authority.
1258 **AuthDirListBadDirs** **0**|**1**::
1259 Authoritative directories only. If set to 1, this directory has some
1260 opinion about which nodes are unsuitable as directory caches. (Do not set
1261 this to 1 unless you plan to list non-functioning directories as bad;
1262 otherwise, you are effectively voting in favor of every declared
1265 **AuthDirListBadExits** **0**|**1**::
1266 Authoritative directories only. If set to 1, this directory has some
1267 opinion about which nodes are unsuitable as exit nodes. (Do not set this to
1268 1 unless you plan to list non-functioning exits as bad; otherwise, you are
1269 effectively voting in favor of every declared exit as an exit.)
1271 **AuthDirRejectUnlisted** **0**|**1**::
1272 Authoritative directories only. If set to 1, the directory server rejects
1273 all uploaded server descriptors that aren't explicitly listed in the
1274 fingerprints file. This acts as a "panic button" if we get hit with a Sybil
1275 attack. (Default: 0)
1277 **AuthDirMaxServersPerAddr** __NUM__::
1278 Authoritative directories only. The maximum number of servers that we will
1279 list as acceptable on a single IP address. Set this to "0" for "no limit".
1282 **AuthDirMaxServersPerAuthAddr** __NUM__::
1283 Authoritative directories only. Like AuthDirMaxServersPerAddr, but applies
1284 to addresses shared with directory authorities. (Default: 5)
1286 **BridgePassword** __Password__::
1287 If set, contains an HTTP authenticator that tells a bridge authority to
1288 serve all requested bridge information. Used for debugging. (Default:
1291 **V3AuthVotingInterval** __N__ **minutes**|**hours**::
1292 V3 authoritative directories only. Configures the server's preferred voting
1293 interval. Note that voting will __actually__ happen at an interval chosen
1294 by consensus from all the authorities' preferred intervals. This time
1295 SHOULD divide evenly into a day. (Default: 1 hour)
1297 **V3AuthVoteDelay** __N__ **minutes**|**hours**::
1298 V3 authoritative directories only. Configures the server's preferred delay
1299 between publishing its vote and assuming it has all the votes from all the
1300 other authorities. Note that the actual time used is not the server's
1301 preferred time, but the consensus of all preferences. (Default: 5 minutes.)
1303 **V3AuthDistDelay** __N__ **minutes**|**hours**::
1304 V3 authoritative directories only. Configures the server's preferred delay
1305 between publishing its consensus and signature and assuming it has all the
1306 signatures from all the other authorities. Note that the actual time used
1307 is not the server's preferred time, but the consensus of all preferences.
1308 (Default: 5 minutes.)
1310 **V3AuthNIntervalsValid** __NUM__::
1311 V3 authoritative directories only. Configures the number of VotingIntervals
1312 for which each consensus should be valid for. Choosing high numbers
1313 increases network partitioning risks; choosing low numbers increases
1314 directory traffic. Note that the actual number of intervals used is not the
1315 server's preferred number, but the consensus of all preferences. Must be at
1316 least 2. (Default: 3.)
1318 **V3BandwidthsFile** __FILENAME__::
1319 V3 authoritative directories only. Configures the location of the
1320 bandiwdth-authority generated file storing information on relays' measured
1321 bandwidth capacities. (Default: unset.)
1323 **V3AuthUseLegacyKey** **0**|**1**::
1324 If set, the directory authority will sign consensuses not only with its
1325 own signing key, but also with a "legacy" key and certificate with a
1326 different identity. This feature is used to migrate directory authority
1327 keys in the event of a compromise. (Default: 0.)
1329 **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
1330 Tells an authority, or other node tracking node reliability and history,
1331 that fine-grained information about nodes can be discarded when it hasn't
1332 changed for a given amount of time. (Default: 24 hours)
1334 HIDDEN SERVICE OPTIONS
1335 ----------------------
1337 The following options are used to configure a hidden service.
1339 **HiddenServiceDir** __DIRECTORY__::
1340 Store data files for a hidden service in DIRECTORY. Every hidden service
1341 must have a separate directory. You may use this option multiple times to
1342 specify multiple services. DIRECTORY must be an existing directory.
1344 **HiddenServicePort** __VIRTPORT__ [__TARGET__]::
1345 Configure a virtual port VIRTPORT for a hidden service. You may use this
1346 option multiple times; each time applies to the service using the most
1347 recent hiddenservicedir. By default, this option maps the virtual port to
1348 the same port on 127.0.0.1. You may override the target port, address, or
1349 both by specifying a target of addr, port, or addr:port. You may also have
1350 multiple lines with the same VIRTPORT: when a user connects to that
1351 VIRTPORT, one of the TARGETs from those lines will be chosen at random.
1353 **PublishHidServDescriptors** **0**|**1**::
1354 If set to 0, Tor will run any hidden services you configure, but it won't
1355 advertise them to the rendezvous directory. This option is only useful if
1356 you're using a Tor controller that handles hidserv publishing for you.
1359 **HiddenServiceVersion** __version__,__version__,__...__::
1360 A list of rendezvous service descriptor versions to publish for the hidden
1361 service. Currently, only version 2 is supported. (Default: 2)
1363 **HiddenServiceAuthorizeClient** __auth-type__ __client-name__,__client-name__,__...__::
1364 If configured, the hidden service is accessible for authorized clients
1365 only. The auth-type can either be \'basic' for a general-purpose
1366 authorization protocol or \'stealth' for a less scalable protocol that also
1367 hides service activity from unauthorized clients. Only clients that are
1368 listed here are authorized to access the hidden service. Valid client names
1369 are 1 to 19 characters long and only use characters in A-Za-z0-9+-_ (no
1370 spaces). If this option is set, the hidden service is not accessible for
1371 clients without authorization any more. Generated authorization data can be
1372 found in the hostname file. Clients need to put this authorization data in
1373 their configuration file using **HidServAuth**.
1375 **RendPostPeriod** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
1376 Every time the specified period elapses, Tor uploads any rendezvous
1377 service descriptors to the directory servers. This information is also
1378 uploaded whenever it changes. (Default: 1 hour)
1380 TESTING NETWORK OPTIONS
1381 -----------------------
1383 The following options are used for running a testing Tor network.
1385 **TestingTorNetwork** **0**|**1**::
1386 If set to 1, Tor adjusts default values of the configuration options below,
1387 so that it is easier to set up a testing Tor network. May only be set if
1388 non-default set of DirServers is set. Cannot be unset while Tor is running.
1391 ServerDNSAllowBrokenConfig 1
1392 DirAllowPrivateAddresses 1
1393 EnforceDistinctSubnets 0
1395 AuthDirMaxServersPerAddr 0
1396 AuthDirMaxServersPerAuthAddr 0
1397 ClientDNSRejectInternalAddresses 0
1398 ClientRejectInternalAddresses 0
1399 ExitPolicyRejectPrivate 0
1400 V3AuthVotingInterval 5 minutes
1401 V3AuthVoteDelay 20 seconds
1402 V3AuthDistDelay 20 seconds
1403 MinUptimeHidServDirectoryV2 0 seconds
1404 TestingV3AuthInitialVotingInterval 5 minutes
1405 TestingV3AuthInitialVoteDelay 20 seconds
1406 TestingV3AuthInitialDistDelay 20 seconds
1407 TestingAuthDirTimeToLearnReachability 0 minutes
1408 TestingEstimatedDescriptorPropagationTime 0 minutes
1410 **TestingV3AuthInitialVotingInterval** __N__ **minutes**|**hours**::
1411 Like V3AuthVotingInterval, but for initial voting interval before the first
1412 consensus has been created. Changing this requires that
1413 **TestingTorNetwork** is set. (Default: 30 minutes)
1415 **TestingV3AuthInitialVoteDelay** __N__ **minutes**|**hours**::
1416 Like TestingV3AuthInitialVoteDelay, but for initial voting interval before
1417 the first consensus has been created. Changing this requires that
1418 **TestingTorNetwork** is set. (Default: 5 minutes)
1420 **TestingV3AuthInitialDistDelay** __N__ **minutes**|**hours**::
1421 Like TestingV3AuthInitialDistDelay, but for initial voting interval before
1422 the first consensus has been created. Changing this requires that
1423 **TestingTorNetwork** is set. (Default: 5 minutes)
1425 **TestingAuthDirTimeToLearnReachability** __N__ **minutes**|**hours**::
1426 After starting as an authority, do not make claims about whether routers
1427 are Running until this much time has passed. Changing this requires
1428 that **TestingTorNetwork** is set. (Default: 30 minutes)
1430 **TestingEstimatedDescriptorPropagationTime** __N__ **minutes**|**hours**::
1431 Clients try downloading router descriptors from directory caches after this
1432 time. Changing this requires that **TestingTorNetwork** is set. (Default:
1438 Tor catches the following signals:
1441 Tor will catch this, clean up and sync to disk if necessary, and exit.
1444 Tor clients behave as with SIGTERM; but Tor servers will do a controlled
1445 slow shutdown, closing listeners and waiting 30 seconds before exiting.
1446 (The delay can be configured with the ShutdownWaitLength config option.)
1449 The signal instructs Tor to reload its configuration (including closing and
1450 reopening logs), and kill and restart its helper processes if applicable.
1453 Log statistics about current connections, past connections, and throughput.
1456 Switch all logs to loglevel debug. You can go back to the old loglevels by
1460 Tor receives this signal when one of its helper processes has exited, so it
1464 Tor catches this signal and ignores it.
1467 If this signal exists on your platform, Tor catches and ignores it.
1472 **@CONFDIR@/torrc**::
1473 The configuration file, which contains "option value" pairs.
1475 **@LOCALSTATEDIR@/lib/tor/**::
1476 The tor process stores keys and other data here.
1478 __DataDirectory__**/cached-status/**::
1479 The most recently downloaded network status document for each authority.
1480 Each file holds one such document; the filenames are the hexadecimal
1481 identity key fingerprints of the directory authorities.
1483 __DataDirectory__**/cached-descriptors** and **cached-descriptors.new**::
1484 These files hold downloaded router statuses. Some routers may appear more
1485 than once; if so, the most recently published descriptor is used. Lines
1486 beginning with @-signs are annotations that contain more information about
1487 a given router. The ".new" file is an append-only journal; when it gets
1488 too large, all entries are merged into a new cached-descriptors file.
1490 __DataDirectory__**/cached-routers** and **cached-routers.new**::
1491 Obsolete versions of cached-descriptors and cached-descriptors.new. When
1492 Tor can't find the newer files, it looks here instead.
1494 __DataDirectory__**/state**::
1495 A set of persistent key-value mappings. These are documented in
1496 the file. These include:
1497 - The current entry guards and their status.
1498 - The current bandwidth accounting values (unused so far; see
1500 - When the file was last written
1501 - What version of Tor generated the state file
1502 - A short history of bandwidth usage, as produced in the router
1505 __DataDirectory__**/bw_accounting**::
1506 Used to track bandwidth accounting values (when the current period starts
1507 and ends; how much has been read and written so far this period). This file
1508 is obsolete, and the data is now stored in the \'state' file as well. Only
1509 used when bandwidth accounting is enabled.
1511 __DataDirectory__**/control_auth_cookie**::
1512 Used for cookie authentication with the controller. Location can be
1513 overridden by the CookieAuthFile config option. Regenerated on startup. See
1514 control-spec.txt for details. Only used when cookie authentication is
1517 __DataDirectory__**/keys/***::
1518 Only used by servers. Holds identity keys and onion keys.
1520 __DataDirectory__**/fingerprint**::
1521 Only used by servers. Holds the fingerprint of the server's identity key.
1523 __DataDirectory__**/approved-routers**::
1524 Only for naming authoritative directory servers (see
1525 **NamingAuthoritativeDirectory**). This file lists nickname to identity
1526 bindings. Each line lists a nickname and a fingerprint separated by
1527 whitespace. See your **fingerprint** file in the __DataDirectory__ for an
1528 example line. If the nickname is **!reject** then descriptors from the
1529 given identity (fingerprint) are rejected by this server. If it is
1530 **!invalid** then descriptors are accepted but marked in the directory as
1531 not valid, that is, not recommended.
1533 __DataDirectory__**/router-stability**::
1534 Only used by authoritative directory servers. Tracks measurements for
1535 router mean-time-between-failures so that authorities have a good idea of
1536 how to set their Stable flags.
1538 __HiddenServiceDirectory__**/hostname**::
1539 The <base32-encoded-fingerprint>.onion domain name for this hidden service.
1540 If the hidden service is restricted to authorized clients only, this file
1541 also contains authorization data for all clients.
1543 __HiddenServiceDirectory__**/private_key**::
1544 The private key for this hidden service.
1546 __HiddenServiceDirectory__**/client_keys**::
1547 Authorization data for a hidden service that is only accessible by
1552 **privoxy**(1), **tsocks**(1), **torify**(1) +
1554 **https://www.torproject.org/**
1560 Plenty, probably. Tor is still in development. Please report them.
1564 Roger Dingledine [arma at mit.edu], Nick Mathewson [nickm at alum.mit.edu].