1TOR(1) Tor 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
16 circuit is unwrapped by a symmetric key at each node, which reveals the
17 downstream node.
18 Basically, Tor provides a distributed network of servers or relays
20 ("onion routers"). Users bounce their TCP streams — web traffic, ftp,
21 ssh, etc. — around the network, and recipients, observers, and even the
22 relays themselves have difficulty tracking the source of the stream.
23 By default, tor will act as a client only. To help the network by
25 providing bandwidth as a relay, change the ORPort configuration option
26 — see below. Please also consult the documentation on the Tor Project’s
27 website.
28
30 -h, --help
31 Display a short help message and exit.
32 -f FILE
34 Specify a new configuration file to contain further Tor
35 configuration options OR pass - to make Tor read its configuration
36 from standard input. (Default: /etc/tor/torrc, or $HOME/.torrc if
37 that file is not found)
38 --allow-missing-torrc
40 Do not require that configuration file specified by -f exist if
41 default torrc can be accessed.
42 --defaults-torrc FILE
44 Specify a file in which to find default values for Tor options. The
45 contents of this file are overridden by those in the regular
46 configuration file, and by those on the command line. (Default:
47 /etc/tor/torrc-defaults.)
48 --ignore-missing-torrc
50 Specifies that Tor should treat a missing torrc file as though it
51 were empty. Ordinarily, Tor does this for missing default torrc
52 files, but not for those specified on the command line.
53 --hash-password PASSWORD
55 Generates a hashed password for control port access.
56 --list-fingerprint
58 Generate your keys and output your nickname and fingerprint.
59 --verify-config
61 Verify the configuration file is valid.
62 --service install [--options command-line options]
64 Install an instance of Tor as a Windows service, with the provided
65 command-line options. Current instructions can be found at
66 https://www.torproject.org/docs/faq#NTService
67 --service remove|start|stop
69 Remove, start, or stop a configured Tor Windows service.
70 --nt-service
72 Used internally to implement a Windows service.
73 --list-torrc-options
75 List all valid options.
76 --list-deprecated-options
78 List all valid options that are scheduled to become obsolete in a
79 future version. (This is a warning, not a promise.)
80 --list-modules
82 For each optional module, list whether or not it has been compiled
83 into Tor. (Any module not listed is not optional in this version of
84 Tor.)
85 --version
87 Display Tor version and exit. The output is a single line of the
88 format "Tor version [version number]." (The version number format
89 is as specified in version-spec.txt.)
90 --quiet|--hush
92 Override the default console log. By default, Tor starts out
93 logging messages at level "notice" and higher to the console. It
94 stops doing so after it parses its configuration, if the
95 configuration tells it to log anywhere else. You can override this
96 behavior with the --hush option, which tells Tor to only send
97 warnings and errors to the console, or with the --quiet option,
98 which tells Tor not to log to the console at all.
99 --keygen [--newpass]
101 Running "tor --keygen" creates a new ed25519 master identity key
102 for a relay, or only a fresh temporary signing key and certificate,
103 if you already have a master key. Optionally you can encrypt the
104 master identity key with a passphrase: Tor will ask you for one. If
105 you don’t want to encrypt the master key, just don’t enter any
106 passphrase when asked.
107 The --newpass option should be used with --keygen only when you
110 need to add, change, or remove a passphrase on an existing ed25519
111 master identity key. You will be prompted for the old passphase (if
112 any), and the new passphrase (if any).
113 When generating a master key, you will probably want to use
116 --DataDirectory to control where the keys and certificates will be
117 stored, and --SigningKeyLifetime to control their lifetimes. Their
118 behavior is as documented in the server options section below. (You
119 must have write access to the specified DataDirectory.)
120 To use the generated files, you must copy them to the
123 DataDirectory/keys directory of your Tor daemon, and make sure that
124 they are owned by the user actually running the Tor daemon on your
125 system.
126 --passphrase-fd FILEDES
128 Filedescriptor to read the passphrase from. Note that unlike with
129 the tor-gencert program, the entire file contents are read and used
130 as the passphrase, including any trailing newlines. Default: read
131 from the terminal.
132 --key-expiration [purpose]
134 The purpose specifies which type of key certificate to determine
135 the expiration of. The only currently recognised purpose is "sign".
136 Running "tor --key-expiration sign" will attempt to find your
139 signing key certificate and will output, both in the logs as well
140 as to stdout, the signing key certificate’s expiration time in
141 ISO-8601 format. For example, the output sent to stdout will be of
142 the form: "signing-cert-expiry: 2017-07-25 08:30:15 UTC"
143 Other options can be specified on the command-line in the format
145 "--option value", in the format "option value", or in a configuration
146 file. For instance, you can tell Tor to start listening for SOCKS
147 connections on port 9999 by passing --SocksPort 9999 or SocksPort 9999
148 to it on the command line, or by putting "SocksPort 9999" in the
149 configuration file. You will need to quote options with spaces in them:
150 if you want Tor to log all debugging messages to debug.log, you will
151 probably need to say --Log "debug file debug.log".
152 Options on the command line override those in configuration files. See
154 the next section for more information.
155
157 All configuration options in a configuration are written on a single
158 line by default. They take the form of an option name and a value, or
159 an option name and a quoted value (option value or option "value").
160 Anything after a # character is treated as a comment. Options are
161 case-insensitive. C-style escaped characters are allowed inside quoted
162 values. To split one configuration entry into multiple lines, use a
163 single backslash character (\) before the end of the line. Comments can
164 be used in such multiline entries, but they must start at the beginning
165 of a line.
166 Configuration options can be imported from files or folders using the
168 %include option with the value being a path. If the path is a file, the
169 options from the file will be parsed as if they were written where the
170 %include option is. If the path is a folder, all files on that folder
171 will be parsed following lexical order. Files starting with a dot are
172 ignored. Files on subfolders are ignored. The %include option can be
173 used recursively.
174 By default, an option on the command line overrides an option found in
176 the configuration file, and an option in a configuration file overrides
177 one in the defaults file.
178 This rule is simple for options that take a single value, but it can
180 become complicated for options that are allowed to occur more than
181 once: if you specify four SocksPorts in your configuration file, and
182 one more SocksPort on the command line, the option on the command line
183 will replace all of the SocksPorts in the configuration file. If this
184 isn’t what you want, prefix the option name with a plus sign (+), and
185 it will be appended to the previous set of options instead. For
186 example, setting SocksPort 9100 will use only port 9100, but setting
187 +SocksPort 9100 will use ports 9100 and 9050 (because this is the
188 default).
189 Alternatively, you might want to remove every instance of an option in
191 the configuration file, and not replace it at all: you might want to
192 say on the command line that you want no SocksPorts at all. To do that,
193 prefix the option name with a forward slash (/). You can use the plus
194 sign (+) and the forward slash (/) in the configuration file and on the
195 command line.
196
198 BandwidthRate N
199 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
200 A token bucket limits the average incoming bandwidth usage on this
201 node to the specified number of bytes per second, and the average
202 outgoing bandwidth usage to that same value. If you want to run a
203 relay in the public network, this needs to be at the very least 75
204 KBytes for a relay (that is, 600 kbits) or 50 KBytes for a bridge
205 (400 kbits) — but of course, more is better; we recommend at least
206 250 KBytes (2 mbits) if possible. (Default: 1 GByte)
207 Note that this option, and other bandwidth-limiting options, apply
210 to TCP data only: They do not count TCP headers or DNS traffic.
211 Tor uses powers of two, not powers of ten, so 1 GByte is
214 1024*1024*1024 bytes as opposed to 1 billion bytes.
215 With this option, and in other options that take arguments in
218 bytes, KBytes, and so on, other formats are also supported.
219 Notably, "KBytes" can also be written as "kilobytes" or "kb";
220 "MBytes" can be written as "megabytes" or "MB"; "kbits" can be
221 written as "kilobits"; and so forth. Case doesn’t matter. Tor also
222 accepts "byte" and "bit" in the singular. The prefixes "tera" and
223 "T" are also recognized. If no units are given, we default to
224 bytes. To avoid confusion, we recommend writing "bytes" or "bits"
225 explicitly, since it’s easy to forget that "B" means bytes, not
226 bits.
227 BandwidthBurst N
229 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
230 Limit the maximum token bucket size (also known as the burst) to
231 the given number of bytes in each direction. (Default: 1 GByte)
232 MaxAdvertisedBandwidth N
234 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
235 If set, we will not advertise more than this amount of bandwidth
236 for our BandwidthRate. Server operators who want to reduce the
237 number of clients who ask to build circuits through them (since
238 this is proportional to advertised bandwidth rate) can thus reduce
239 the CPU demands on their server without impacting network
240 performance.
241 RelayBandwidthRate N
243 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
244 If not 0, a separate token bucket limits the average incoming
245 bandwidth usage for _relayed traffic_ on this node to the specified
246 number of bytes per second, and the average outgoing bandwidth
247 usage to that same value. Relayed traffic currently is calculated
248 to include answers to directory requests, but that may change in
249 future versions. They do not include directory fetches by the relay
250 (from authority or other relays), because that is considered
251 "client" activity. (Default: 0)
252 RelayBandwidthBurst N
254 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
255 If not 0, limit the maximum token bucket size (also known as the
256 burst) for _relayed traffic_ to the given number of bytes in each
257 direction. They do not include directory fetches by the relay (from
258 authority or other relays), because that is considered "client"
259 activity. (Default: 0)
260 PerConnBWRate N
262 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
263 If this option is set manually, or via the "perconnbwrate"
264 consensus field, Tor will use it for separate rate limiting for
265 each connection from a non-relay. (Default: 0)
266 PerConnBWBurst N
268 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
269 If this option is set manually, or via the "perconnbwburst"
270 consensus field, Tor will use it for separate rate limiting for
271 each connection from a non-relay. (Default: 0)
272 ClientTransportPlugin transport socks4|socks5 IP:PORT,
274 ClientTransportPlugin transport exec path-to-binary [options]
275 In its first form, when set along with a corresponding Bridge line,
276 the Tor client forwards its traffic to a SOCKS-speaking proxy on
277 "IP:PORT". (IPv4 addresses should written as-is; IPv6 addresses
278 should be wrapped in square brackets.) It’s the duty of that proxy
279 to properly forward the traffic to the bridge.
280 In its second form, when set along with a corresponding Bridge
283 line, the Tor client launches the pluggable transport proxy
284 executable in path-to-binary using options as its command-line
285 options, and forwards its traffic to it. It’s the duty of that
286 proxy to properly forward the traffic to the bridge.
287 ServerTransportPlugin transport exec path-to-binary [options]
289 The Tor relay launches the pluggable transport proxy in
290 path-to-binary using options as its command-line options, and
291 expects to receive proxied client traffic from it.
292 ServerTransportListenAddr transport IP:PORT
294 When this option is set, Tor will suggest IP:PORT as the listening
295 address of any pluggable transport proxy that tries to launch
296 transport. (IPv4 addresses should written as-is; IPv6 addresses
297 should be wrapped in square brackets.)
298 ServerTransportOptions transport k=v k=v ...
300 When this option is set, Tor will pass the k=v parameters to any
301 pluggable transport proxy that tries to launch transport.
302 (Example: ServerTransportOptions obfs45 shared-secret=bridgepasswd
304 cache=/var/lib/tor/cache)
305 ExtORPort [address:]port|auto
307 Open this port to listen for Extended ORPort connections from your
308 pluggable transports.
309 ExtORPortCookieAuthFile Path
311 If set, this option overrides the default location and file name
312 for the Extended ORPort’s cookie file — the cookie file is needed
313 for pluggable transports to communicate through the Extended
314 ORPort.
315 ExtORPortCookieAuthFileGroupReadable 0|1
317 If this option is set to 0, don’t allow the filesystem group to
318 read the Extended OR Port cookie file. If the option is set to 1,
319 make the cookie file readable by the default GID. [Making the file
320 readable by other groups is not yet implemented; let us know if you
321 need this for some reason.] (Default: 0)
322 ConnLimit NUM
324 The minimum number of file descriptors that must be available to
325 the Tor process before it will start. Tor will ask the OS for as
326 many file descriptors as the OS will allow (you can find this by
327 "ulimit -H -n"). If this number is less than ConnLimit, then Tor
328 will refuse to start.
329 Tor relays need thousands of sockets, to connect to every other
332 relay. If you are running a private bridge, you can reduce the
333 number of sockets that Tor uses. For example, to limit Tor to 500
334 sockets, run "ulimit -n 500" in a shell. Then start tor in the same
335 shell, with ConnLimit 500. You may also need to set DisableOOSCheck
336 0.
337 Unless you have severely limited sockets, you probably don’t need
340 to adjust ConnLimit itself. It has no effect on Windows, since that
341 platform lacks getrlimit(). (Default: 1000)
342 DisableNetwork 0|1
344 When this option is set, we don’t listen for or accept any
345 connections other than controller connections, and we close (and
346 don’t reattempt) any outbound connections. Controllers sometimes
347 use this option to avoid using the network until Tor is fully
348 configured. Tor will make still certain network-related calls (like
349 DNS lookups) as a part of its configuration process, even if
350 DisableNetwork is set. (Default: 0)
351 ConstrainedSockets 0|1
353 If set, Tor will tell the kernel to attempt to shrink the buffers
354 for all sockets to the size specified in ConstrainedSockSize. This
355 is useful for virtual servers and other environments where system
356 level TCP buffers may be limited. If you’re on a virtual server,
357 and you encounter the "Error creating network socket: No buffer
358 space available" message, you are likely experiencing this problem.
359 The preferred solution is to have the admin increase the buffer
362 pool for the host itself via /proc/sys/net/ipv4/tcp_mem or
363 equivalent facility; this configuration option is a second-resort.
364 The DirPort option should also not be used if TCP buffers are
367 scarce. The cached directory requests consume additional sockets
368 which exacerbates the problem.
369 You should not enable this feature unless you encounter the "no
372 buffer space available" issue. Reducing the TCP buffers affects
373 window size for the TCP stream and will reduce throughput in
374 proportion to round trip time on long paths. (Default: 0)
375 ConstrainedSockSize N bytes|KBytes
377 When ConstrainedSockets is enabled the receive and transmit buffers
378 for all sockets will be set to this limit. Must be a value between
379 2048 and 262144, in 1024 byte increments. Default of 8192 is
380 recommended.
381 ControlPort [address:]port|unix:path|auto [flags]
383 If set, Tor will accept connections on this port and allow those
384 connections to control the Tor process using the Tor Control
385 Protocol (described in control-spec.txt in torspec). Note: unless
386 you also specify one or more of HashedControlPassword or
387 CookieAuthentication, setting this option will cause Tor to allow
388 any process on the local host to control it. (Setting both
389 authentication methods means either method is sufficient to
390 authenticate to Tor.) This option is required for many Tor
391 controllers; most use the value of 9051. If a unix domain socket is
392 used, you may quote the path using standard C escape sequences. You
393 can specify this directive multiple times, to bind to multiple
394 address/port pairs. Set it to "auto" to have Tor pick a port for
395 you. (Default: 0)
396 Recognized flags are...
399 GroupWritable
401 Unix domain sockets only: makes the socket get created as
402 group-writable.
403 WorldWritable
405 Unix domain sockets only: makes the socket get created as
406 world-writable.
407 RelaxDirModeCheck
409 Unix domain sockets only: Do not insist that the directory that
410 holds the socket be read-restricted.
411 ControlSocket Path
413 Like ControlPort, but listens on a Unix domain socket, rather than
414 a TCP socket. 0 disables ControlSocket. (Unix and Unix-like
415 systems only.) (Default: 0)
416 ControlSocketsGroupWritable 0|1
418 If this option is set to 0, don’t allow the filesystem group to
419 read and write unix sockets (e.g. ControlSocket). If the option is
420 set to 1, make the control socket readable and writable by the
421 default GID. (Default: 0)
422 HashedControlPassword hashed_password
424 Allow connections on the control port if they present the password
425 whose one-way hash is hashed_password. You can compute the hash of
426 a password by running "tor --hash-password password". You can
427 provide several acceptable passwords by using more than one
428 HashedControlPassword line.
429 CookieAuthentication 0|1
431 If this option is set to 1, allow connections on the control port
432 when the connecting process knows the contents of a file named
433 "control_auth_cookie", which Tor will create in its data directory.
434 This authentication method should only be used on systems with good
435 filesystem security. (Default: 0)
436 CookieAuthFile Path
438 If set, this option overrides the default location and file name
439 for Tor’s cookie file. (See CookieAuthentication above.)
440 CookieAuthFileGroupReadable 0|1
442 If this option is set to 0, don’t allow the filesystem group to
443 read the cookie file. If the option is set to 1, make the cookie
444 file readable by the default GID. [Making the file readable by
445 other groups is not yet implemented; let us know if you need this
446 for some reason.] (Default: 0)
447 ControlPortWriteToFile Path
449 If set, Tor writes the address and port of any control port it
450 opens to this address. Usable by controllers to learn the actual
451 control port when ControlPort is set to "auto".
452 ControlPortFileGroupReadable 0|1
454 If this option is set to 0, don’t allow the filesystem group to
455 read the control port file. If the option is set to 1, make the
456 control port file readable by the default GID. (Default: 0)
457 DataDirectory DIR
459 Store working data in DIR. Can not be changed while tor is running.
460 (Default: ~/.tor if your home directory is not /; otherwise,
461 /var/lib/tor. On Windows, the default is your ApplicationData
462 folder.)
463 DataDirectoryGroupReadable 0|1
465 If this option is set to 0, don’t allow the filesystem group to
466 read the DataDirectory. If the option is set to 1, make the
467 DataDirectory readable by the default GID. (Default: 0)
468 CacheDirectory DIR
470 Store cached directory data in DIR. Can not be changed while tor is
471 running. (Default: uses the value of DataDirectory.)
472 CacheDirectoryGroupReadable 0|1|auto
474 If this option is set to 0, don’t allow the filesystem group to
475 read the CacheDirectory. If the option is set to 1, make the
476 CacheDirectory readable by the default GID. If the option is
477 "auto", then we use the setting for DataDirectoryGroupReadable when
478 the CacheDirectory is the same as the DataDirectory, and 0
479 otherwise. (Default: auto)
480 FallbackDir ipv4address:dirport orport=orport id=fingerprint
482 [weight=num] [ipv6=[ipv6address]:orport]
483 When tor is unable to connect to any directory cache for directory
484 info (usually because it doesn’t know about any yet) it tries a
485 hard-coded directory. Relays try one directory authority at a time.
486 Clients try multiple directory authorities and FallbackDirs, to
487 avoid hangs on startup if a hard-coded directory is down. Clients
488 wait for a few seconds between each attempt, and retry FallbackDirs
489 more often than directory authorities, to reduce the load on the
490 directory authorities.
491 FallbackDirs should be stable relays with stable IP addresses,
494 ports, and identity keys. They must have a DirPort.
495 By default, the directory authorities are also FallbackDirs.
498 Specifying a FallbackDir replaces Tor’s default hard-coded
499 FallbackDirs (if any). (See the DirAuthority entry for an
500 explanation of each flag.)
501 UseDefaultFallbackDirs 0|1
503 Use Tor’s default hard-coded FallbackDirs (if any). (When a
504 FallbackDir line is present, it replaces the hard-coded
505 FallbackDirs, regardless of the value of UseDefaultFallbackDirs.)
506 (Default: 1)
507 DirAuthority [nickname] [flags] ipv4address:dirport fingerprint
509 Use a nonstandard authoritative directory server at the provided
510 address and port, with the specified key fingerprint. This option
511 can be repeated many times, for multiple authoritative directory
512 servers. Flags are separated by spaces, and determine what kind of
513 an authority this directory is. By default, an authority is not
514 authoritative for any directory style or version unless an
515 appropriate flag is given.
516 Tor will use this authority as a bridge authoritative directory if
519 the "bridge" flag is set. If a flag "orport=orport" is given, Tor
520 will use the given port when opening encrypted tunnels to the
521 dirserver. If a flag "weight=num" is given, then the directory
522 server is chosen randomly with probability proportional to that
523 weight (default 1.0). If a flag "v3ident=fp" is given, the
524 dirserver is a v3 directory authority whose v3 long-term signing
525 key has the fingerprint fp. Lastly, if an
526 "ipv6=[ipv6address]:orport" flag is present, then the directory
527 authority is listening for IPv6 connections on the indicated IPv6
528 address and OR Port.
529 Tor will contact the authority at ipv4address to download directory
532 documents. Clients always use the ORPort. Relays usually use the
533 DirPort, but will use the ORPort in some circumstances. If an IPv6
534 ORPort is supplied, clients will also download directory documents
535 at the IPv6 ORPort, if they are configured to use IPv6.
536 If no DirAuthority line is given, Tor will use the default
539 directory authorities. NOTE: this option is intended for setting up
540 a private Tor network with its own directory authorities. If you
541 use it, you will be distinguishable from other users, because you
542 won’t believe the same authorities they do.
543 DirAuthorityFallbackRate NUM
545 When configured to use both directory authorities and fallback
546 directories, the directory authorities also work as fallbacks. They
547 are chosen with their regular weights, multiplied by this number,
548 which should be 1.0 or less. The default is less than 1, to reduce
549 load on authorities. (Default: 0.1)
550 AlternateDirAuthority [nickname] [flags] ipv4address:port fingerprint
552 AlternateBridgeAuthority [nickname] [flags] ipv4address:port
554 fingerprint
555 These options behave as DirAuthority, but they replace fewer of the
556 default directory authorities. Using AlternateDirAuthority replaces
557 the default Tor directory authorities, but leaves the default
558 bridge authorities in place. Similarly, AlternateBridgeAuthority
559 replaces the default bridge authority, but leaves the directory
560 authorities alone.
561 DisableAllSwap 0|1
563 If set to 1, Tor will attempt to lock all current and future memory
564 pages, so that memory cannot be paged out. Windows, OS X and
565 Solaris are currently not supported. We believe that this feature
566 works on modern Gnu/Linux distributions, and that it should work on
567 *BSD systems (untested). This option requires that you start your
568 Tor as root, and you should use the User option to properly reduce
569 Tor’s privileges. Can not be changed while tor is running.
570 (Default: 0)
571 DisableDebuggerAttachment 0|1
573 If set to 1, Tor will attempt to prevent basic debugging attachment
574 attempts by other processes. This may also keep Tor from generating
575 core files if it crashes. It has no impact for users who wish to
576 attach if they have CAP_SYS_PTRACE or if they are root. We believe
577 that this feature works on modern Gnu/Linux distributions, and that
578 it may also work on *BSD systems (untested). Some modern Gnu/Linux
579 systems such as Ubuntu have the kernel.yama.ptrace_scope sysctl and
580 by default enable it as an attempt to limit the PTRACE scope for
581 all user processes by default. This feature will attempt to limit
582 the PTRACE scope for Tor specifically - it will not attempt to
583 alter the system wide ptrace scope as it may not even exist. If you
584 wish to attach to Tor with a debugger such as gdb or strace you
585 will want to set this to 0 for the duration of your debugging.
586 Normal users should leave it on. Disabling this option while Tor is
587 running is prohibited. (Default: 1)
588 FetchDirInfoEarly 0|1
590 If set to 1, Tor will always fetch directory information like other
591 directory caches, even if you don’t meet the normal criteria for
592 fetching early. Normal users should leave it off. (Default: 0)
593 FetchDirInfoExtraEarly 0|1
595 If set to 1, Tor will fetch directory information before other
596 directory caches. It will attempt to download directory information
597 closer to the start of the consensus period. Normal users should
598 leave it off. (Default: 0)
599 FetchHidServDescriptors 0|1
601 If set to 0, Tor will never fetch any hidden service descriptors
602 from the rendezvous directories. This option is only useful if
603 you’re using a Tor controller that handles hidden service fetches
604 for you. (Default: 1)
605 FetchServerDescriptors 0|1
607 If set to 0, Tor will never fetch any network status summaries or
608 server descriptors from the directory servers. This option is only
609 useful if you’re using a Tor controller that handles directory
610 fetches for you. (Default: 1)
611 FetchUselessDescriptors 0|1
613 If set to 1, Tor will fetch every consensus flavor, and all server
614 descriptors and authority certificates referenced by those
615 consensuses, except for extra info descriptors. When this option is
616 1, Tor will also keep fetching descriptors, even when idle. If set
617 to 0, Tor will avoid fetching useless descriptors: flavors that it
618 is not using to build circuits, and authority certificates it does
619 not trust. When Tor hasn’t built any application circuits, it will
620 go idle, and stop fetching descriptors. This option is useful if
621 you’re using a tor client with an external parser that uses a full
622 consensus. This option fetches all documents except extrainfo
623 descriptors, DirCache fetches and serves all documents except
624 extrainfo descriptors, DownloadExtraInfo* fetches extrainfo
625 documents, and serves them if DirCache is on, and
626 UseMicrodescriptors changes the flavour of consensues and
627 descriptors that is fetched and used for building circuits.
628 (Default: 0)
629 HTTPProxy host[:port]
631 Tor will make all its directory requests through this host:port (or
632 host:80 if port is not specified), rather than connecting directly
633 to any directory servers. (DEPRECATED: As of 0.3.1.0-alpha you
634 should use HTTPSProxy.)
635 HTTPProxyAuthenticator username:password
637 If defined, Tor will use this username:password for Basic HTTP
638 proxy authentication, as in RFC 2617. This is currently the only
639 form of HTTP proxy authentication that Tor supports; feel free to
640 submit a patch if you want it to support others. (DEPRECATED: As of
641 0.3.1.0-alpha you should use HTTPSProxyAuthenticator.)
642 HTTPSProxy host[:port]
644 Tor will make all its OR (SSL) connections through this host:port
645 (or host:443 if port is not specified), via HTTP CONNECT rather
646 than connecting directly to servers. You may want to set
647 FascistFirewall to restrict the set of ports you might try to
648 connect to, if your HTTPS proxy only allows connecting to certain
649 ports.
650 HTTPSProxyAuthenticator username:password
652 If defined, Tor will use this username:password for Basic HTTPS
653 proxy authentication, as in RFC 2617. This is currently the only
654 form of HTTPS proxy authentication that Tor supports; feel free to
655 submit a patch if you want it to support others.
656 Sandbox 0|1
658 If set to 1, Tor will run securely through the use of a syscall
659 sandbox. Otherwise the sandbox will be disabled. The option is
660 currently an experimental feature. It only works on Linux-based
661 operating systems, and only when Tor has been built with the
662 libseccomp library. This option can not be changed while tor is
663 running.
664 When the Sandbox is 1, the following options can not be changed
667 when tor is running: Address, ConnLimit, CookieAuthFile,
668 DirPortFrontPage, ExtORPortCookieAuthFile, Logs,
669 ServerDNSResolvConfFile, ClientOnionAuthDir (and any files in it
670 won’t reload on HUP signal).
671 Launching new Onion Services through the control port is not
673 supported with current syscall sandboxing implementation.
674 Tor must remain in client or server mode (some changes to
676 ClientOnly and ORPort are not allowed). Currently, if Sandbox is 1,
677 ControlPort command "GETINFO address" will not work.
678 (Default: 0)
680 Socks4Proxy host[:port]
682 Tor will make all OR connections through the SOCKS 4 proxy at
683 host:port (or host:1080 if port is not specified).
684 Socks5Proxy host[:port]
686 Tor will make all OR connections through the SOCKS 5 proxy at
687 host:port (or host:1080 if port is not specified).
688 Socks5ProxyUsername username
690 Socks5ProxyPassword password
692 If defined, authenticate to the SOCKS 5 server using username and
693 password in accordance to RFC 1929. Both username and password must
694 be between 1 and 255 characters.
695 UnixSocksGroupWritable 0|1
697 If this option is set to 0, don’t allow the filesystem group to
698 read and write unix sockets (e.g. SocksPort unix:). If the option
699 is set to 1, make the Unix socket readable and writable by the
700 default GID. (Default: 0)
701 KeepalivePeriod NUM
703 To keep firewalls from expiring connections, send a padding
704 keepalive cell every NUM seconds on open connections that are in
705 use. (Default: 5 minutes)
706 Log minSeverity[-maxSeverity] stderr|stdout|syslog
708 Send all messages between minSeverity and maxSeverity to the
709 standard output stream, the standard error stream, or to the system
710 log. (The "syslog" value is only supported on Unix.) Recognized
711 severity levels are debug, info, notice, warn, and err. We advise
712 using "notice" in most cases, since anything more verbose may
713 provide sensitive information to an attacker who obtains the logs.
714 If only one severity level is given, all messages of that level or
715 higher will be sent to the listed destination.
716 Some low-level logs may be sent from signal handlers, so their
719 destination logs must be signal-safe. These low-level logs include
720 backtraces, logging function errors, and errors in code called by
721 logging functions. Signal-safe logs are always sent to stderr or
722 stdout. They are also sent to a limited number of log files that
723 are configured to log messages at error severity from the bug or
724 general domains. They are never sent as syslogs, android logs,
725 control port log events, or to any API-based log destinations.
726 Log minSeverity[-maxSeverity] file FILENAME
728 As above, but send log messages to the listed filename. The "Log"
729 option may appear more than once in a configuration file. Messages
730 are sent to all the logs that match their severity level.
731 Log [domain,...]minSeverity[-maxSeverity] ... file FILENAME
733 Log [domain,...]minSeverity[-maxSeverity] ... stderr|stdout|syslog
735 As above, but select messages by range of log severity and by a set
736 of "logging domains". Each logging domain corresponds to an area of
737 functionality inside Tor. You can specify any number of severity
738 ranges for a single log statement, each of them prefixed by a
739 comma-separated list of logging domains. You can prefix a domain
740 with ~ to indicate negation, and use * to indicate "all domains".
741 If you specify a severity range without a list of domains, it
742 matches all domains.
743 This is an advanced feature which is most useful for debugging one
746 or two of Tor’s subsystems at a time.
747 The currently recognized domains are: general, crypto, net, config,
750 fs, protocol, mm, http, app, control, circ, rend, bug, dir,
751 dirserv, or, edge, acct, hist, handshake, heartbeat, channel,
752 sched, guard, consdiff, dos, process, pt, btrack, and mesg. Domain
753 names are case-insensitive.
754 For example, "Log [handshake]debug [~net,~mm]info notice stdout"
757 sends to stdout: all handshake messages of any severity, all
758 info-and-higher messages from domains other than networking and
759 memory management, and all messages of severity notice or higher.
760 LogMessageDomains 0|1
762 If 1, Tor includes message domains with each log message. Every log
763 message currently has at least one domain; most currently have
764 exactly one. This doesn’t affect controller log messages. (Default:
765 0)
766 MaxUnparseableDescSizeToLog N bytes|KBytes|MBytes|GBytes|TBytes
768 Unparseable descriptors (e.g. for votes, consensuses, routers) are
769 logged in separate files by hash, up to the specified size in
770 total. Note that only files logged during the lifetime of this Tor
771 process count toward the total; this is intended to be used to
772 debug problems without opening live servers to resource exhaustion
773 attacks. (Default: 10 MB)
774 OutboundBindAddress IP
776 Make all outbound connections originate from the IP address
777 specified. This is only useful when you have multiple network
778 interfaces, and you want all of Tor’s outgoing connections to use a
779 single one. This option may be used twice, once with an IPv4
780 address and once with an IPv6 address. IPv6 addresses should be
781 wrapped in square brackets. This setting will be ignored for
782 connections to the loopback addresses (127.0.0.0/8 and ::1), and is
783 not used for DNS requests as well.
784 OutboundBindAddressOR IP
786 Make all outbound non-exit (relay and other) connections originate
787 from the IP address specified. This option overrides
788 OutboundBindAddress for the same IP version. This option may be
789 used twice, once with an IPv4 address and once with an IPv6
790 address. IPv6 addresses should be wrapped in square brackets. This
791 setting will be ignored for connections to the loopback addresses
792 (127.0.0.0/8 and ::1).
793 OutboundBindAddressExit IP
795 Make all outbound exit connections originate from the IP address
796 specified. This option overrides OutboundBindAddress for the same
797 IP version. This option may be used twice, once with an IPv4
798 address and once with an IPv6 address. IPv6 addresses should be
799 wrapped in square brackets. This setting will be ignored for
800 connections to the loopback addresses (127.0.0.0/8 and ::1).
801 PidFile FILE
803 On startup, write our PID to FILE. On clean shutdown, remove FILE.
804 Can not be changed while tor is running.
805 ProtocolWarnings 0|1
807 If 1, Tor will log with severity 'warn' various cases of other
808 parties not following the Tor specification. Otherwise, they are
809 logged with severity 'info'. (Default: 0)
810 RunAsDaemon 0|1
812 If 1, Tor forks and daemonizes to the background. This option has
813 no effect on Windows; instead you should use the --service
814 command-line option. Can not be changed while tor is running.
815 (Default: 0)
816 LogTimeGranularity NUM
818 Set the resolution of timestamps in Tor’s logs to NUM milliseconds.
819 NUM must be positive and either a divisor or a multiple of 1
820 second. Note that this option only controls the granularity written
821 by Tor to a file or console log. Tor does not (for example) "batch
822 up" log messages to affect times logged by a controller, times
823 attached to syslog messages, or the mtime fields on log files.
824 (Default: 1 second)
825 TruncateLogFile 0|1
827 If 1, Tor will overwrite logs at startup and in response to a HUP
828 signal, instead of appending to them. (Default: 0)
829 SyslogIdentityTag tag
831 When logging to syslog, adds a tag to the syslog identity such that
832 log entries are marked with "Tor-tag". Can not be changed while tor
833 is running. (Default: none)
834 AndroidIdentityTag tag
836 When logging to Android’s logging subsystem, adds a tag to the log
837 identity such that log entries are marked with "Tor-tag". Can not
838 be changed while tor is running. (Default: none)
839 SafeLogging 0|1|relay
841 Tor can scrub potentially sensitive strings from log messages (e.g.
842 addresses) by replacing them with the string [scrubbed]. This way
843 logs can still be useful, but they don’t leave behind personally
844 identifying information about what sites a user might have visited.
845 If this option is set to 0, Tor will not perform any scrubbing, if
848 it is set to 1, all potentially sensitive strings are replaced. If
849 it is set to relay, all log messages generated when acting as a
850 relay are sanitized, but all messages generated when acting as a
851 client are not. Note: Tor may not heed this option when logging at
852 log levels below Notice. (Default: 1)
853 User Username
855 On startup, setuid to this user and setgid to their primary group.
856 Can not be changed while tor is running.
857 KeepBindCapabilities 0|1|auto
859 On Linux, when we are started as root and we switch our identity
860 using the User option, the KeepBindCapabilities option tells us
861 whether to try to retain our ability to bind to low ports. If this
862 value is 1, we try to keep the capability; if it is 0 we do not;
863 and if it is auto, we keep the capability only if we are configured
864 to listen on a low port. Can not be changed while tor is running.
865 (Default: auto.)
866 HardwareAccel 0|1
868 If non-zero, try to use built-in (static) crypto hardware
869 acceleration when available. Can not be changed while tor is
870 running. (Default: 0)
871 AccelName NAME
873 When using OpenSSL hardware crypto acceleration attempt to load the
874 dynamic engine of this name. This must be used for any dynamic
875 hardware engine. Names can be verified with the openssl engine
876 command. Can not be changed while tor is running.
877 AccelDir DIR
879 Specify this option if using dynamic hardware acceleration and the
880 engine implementation library resides somewhere other than the
881 OpenSSL default. Can not be changed while tor is running.
882 AvoidDiskWrites 0|1
884 If non-zero, try to write to disk less frequently than we would
885 otherwise. This is useful when running on flash memory or other
886 media that support only a limited number of writes. (Default: 0)
887 CircuitPriorityHalflife NUM
889 If this value is set, we override the default algorithm for
890 choosing which circuit’s cell to deliver or relay next. It is
891 delivered first to the circuit that has the lowest weighted cell
892 count, where cells are weighted exponentially according to this
893 value (in seconds). If the value is -1, it is taken from the
894 consensus if possible else it will fallback to the default value of
895 30. Minimum: 1, Maximum: 2147483647. This can be defined as a float
896 value. This is an advanced option; you generally shouldn’t have to
897 mess with it. (Default: -1)
898 CountPrivateBandwidth 0|1
900 If this option is set, then Tor’s rate-limiting applies not only to
901 remote connections, but also to connections to private addresses
902 like 127.0.0.1 or 10.0.0.1. This is mostly useful for debugging
903 rate-limiting. (Default: 0)
904 ExtendByEd25519ID 0|1|auto
906 If this option is set to 1, we always try to include a relay’s
907 Ed25519 ID when telling the proceeding relay in a circuit to extend
908 to it. If this option is set to 0, we never include Ed25519 IDs
909 when extending circuits. If the option is set to "default", we obey
910 a parameter in the consensus document. (Default: auto)
911 NoExec 0|1
913 If this option is set to 1, then Tor will never launch another
914 executable, regardless of the settings of ClientTransportPlugin or
915 ServerTransportPlugin. Once this option has been set to 1, it
916 cannot be set back to 0 without restarting Tor. (Default: 0)
917 Schedulers KIST|KISTLite|Vanilla
919 Specify the scheduler type that tor should use. The scheduler is
920 responsible for moving data around within a Tor process. This is an
921 ordered list by priority which means that the first value will be
922 tried first and if unavailable, the second one is tried and so on.
923 It is possible to change these values at runtime. This option
924 mostly effects relays, and most operators should leave it set to
925 its default value. (Default: KIST,KISTLite,Vanilla)
926 The possible scheduler types are:
928 KIST: Kernel-Informed Socket Transport. Tor will use TCP
930 information from the kernel to make informed decisions regarding
931 how much data to send and when to send it. KIST also handles
932 traffic in batches (see KISTSchedRunInterval) in order to improve
933 traffic prioritization decisions. As implemented, KIST will only
934 work on Linux kernel version 2.6.39 or higher.
935 KISTLite: Same as KIST but without kernel support. Tor will use all
937 the same mechanics as with KIST, including the batching, but its
938 decisions regarding how much data to send will not be as good.
939 KISTLite will work on all kernels and operating systems, and the
940 majority of the benefits of KIST are still realized with KISTLite.
941 Vanilla: The scheduler that Tor used before KIST was implemented.
943 It sends as much data as possible, as soon as possible. Vanilla
944 will work on all kernels and operating systems.
945 KISTSchedRunInterval NUM msec
947 If KIST or KISTLite is used in the Schedulers option, this controls
948 at which interval the scheduler tick is. If the value is 0 msec,
949 the value is taken from the consensus if possible else it will
950 fallback to the default 10 msec. Maximum possible value is 100
951 msec. (Default: 0 msec)
952 KISTSockBufSizeFactor NUM
954 If KIST is used in Schedulers, this is a multiplier of the
955 per-socket limit calculation of the KIST algorithm. (Default: 1.0)
956
958 The following options are useful only for clients (that is, if
959 SocksPort, HTTPTunnelPort, TransPort, DNSPort, or NATDPort is
960 non-zero):
961 Bridge [transport] IP:ORPort [fingerprint]
963 When set along with UseBridges, instructs Tor to use the relay at
964 "IP:ORPort" as a "bridge" relaying into the Tor network. If
965 "fingerprint" is provided (using the same format as for
966 DirAuthority), we will verify that the relay running at that
967 location has the right fingerprint. We also use fingerprint to look
968 up the bridge descriptor at the bridge authority, if it’s provided
969 and if UpdateBridgesFromAuthority is set too.
970 If "transport" is provided, it must match a ClientTransportPlugin
973 line. We then use that pluggable transport’s proxy to transfer data
974 to the bridge, rather than connecting to the bridge directly. Some
975 transports use a transport-specific method to work out the remote
976 address to connect to. These transports typically ignore the
977 "IP:ORPort" specified in the bridge line.
978 Tor passes any "key=val" settings to the pluggable transport proxy
981 as per-connection arguments when connecting to the bridge. Consult
982 the documentation of the pluggable transport for details of what
983 arguments it supports.
984 LearnCircuitBuildTimeout 0|1
986 If 0, CircuitBuildTimeout adaptive learning is disabled. (Default:
987 1)
988 CircuitBuildTimeout NUM
990 Try for at most NUM seconds when building circuits. If the circuit
991 isn’t open in that time, give up on it. If LearnCircuitBuildTimeout
992 is 1, this value serves as the initial value to use before a
993 timeout is learned. If LearnCircuitBuildTimeout is 0, this value is
994 the only value used. (Default: 60 seconds)
995 CircuitsAvailableTimeout NUM
997 Tor will attempt to keep at least one open, unused circuit
998 available for this amount of time. This option governs how long
999 idle circuits are kept open, as well as the amount of time Tor will
1000 keep a circuit open to each of the recently used ports. This way
1001 when the Tor client is entirely idle, it can expire all of its
1002 circuits, and then expire its TLS connections. Note that the actual
1003 timeout value is uniformly randomized from the specified value to
1004 twice that amount. (Default: 30 minutes; Max: 24 hours)
1005 CircuitStreamTimeout NUM
1007 If non-zero, this option overrides our internal timeout schedule
1008 for how many seconds until we detach a stream from a circuit and
1009 try a new circuit. If your network is particularly slow, you might
1010 want to set this to a number like 60. (Default: 0)
1011 ClientOnly 0|1
1013 If set to 1, Tor will not run as a relay or serve directory
1014 requests, even if the ORPort, ExtORPort, or DirPort options are
1015 set. (This config option is mostly unnecessary: we added it back
1016 when we were considering having Tor clients auto-promote themselves
1017 to being relays if they were stable and fast enough. The current
1018 behavior is simply that Tor is a client unless ORPort, ExtORPort,
1019 or DirPort are configured.) (Default: 0)
1020 ConnectionPadding 0|1|auto
1022 This option governs Tor’s use of padding to defend against some
1023 forms of traffic analysis. If it is set to auto, Tor will send
1024 padding only if both the client and the relay support it. If it is
1025 set to 0, Tor will not send any padding cells. If it is set to 1,
1026 Tor will still send padding for client connections regardless of
1027 relay support. Only clients may set this option. This option should
1028 be offered via the UI to mobile users for use where bandwidth may
1029 be expensive. (Default: auto)
1030 ReducedConnectionPadding 0|1
1032 If set to 1, Tor will not not hold OR connections open for very
1033 long, and will send less padding on these connections. Only clients
1034 may set this option. This option should be offered via the UI to
1035 mobile users for use where bandwidth may be expensive. (Default: 0)
1036 CircuitPadding 0|1
1038 If set to 0, Tor will not pad client circuits with additional cover
1039 traffic. Only clients may set this option. This option should be
1040 offered via the UI to mobile users for use where bandwidth may be
1041 expensive. If set to 1, padding will be negotiated as per the
1042 consensus and relay support (unlike ConnectionPadding,
1043 CircuitPadding cannot be force-enabled). (Default: 1)
1044 ReducedCircuitPadding 0|1
1046 If set to 1, Tor will only use circuit padding algorithms that have
1047 low overhead. Only clients may set this option. This option should
1048 be offered via the UI to mobile users for use where bandwidth may
1049 be expensive. (Default: 0)
1050 ExcludeNodes node,node,...
1052 A list of identity fingerprints, country codes, and address
1053 patterns of nodes to avoid when building a circuit. Country codes
1054 are 2-letter ISO3166 codes, and must be wrapped in braces;
1055 fingerprints may be preceded by a dollar sign. (Example:
1056 ExcludeNodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, {cc},
1057 255.254.0.0/8)
1058 By default, this option is treated as a preference that Tor is
1061 allowed to override in order to keep working. For example, if you
1062 try to connect to a hidden service, but you have excluded all of
1063 the hidden service’s introduction points, Tor will connect to one
1064 of them anyway. If you do not want this behavior, set the
1065 StrictNodes option (documented below).
1066 Note also that if you are a relay, this (and the other node
1069 selection options below) only affects your own circuits that Tor
1070 builds for you. Clients can still build circuits through you to any
1071 node. Controllers can tell Tor to build circuits through any node.
1072 Country codes are case-insensitive. The code "{??}" refers to nodes
1075 whose country can’t be identified. No country code, including {??},
1076 works if no GeoIPFile can be loaded. See also the
1077 GeoIPExcludeUnknown option below.
1078 ExcludeExitNodes node,node,...
1080 A list of identity fingerprints, country codes, and address
1081 patterns of nodes to never use when picking an exit node---that is,
1082 a node that delivers traffic for you outside the Tor network. Note
1083 that any node listed in ExcludeNodes is automatically considered to
1084 be part of this list too. See the ExcludeNodes option for more
1085 information on how to specify nodes. See also the caveats on the
1086 "ExitNodes" option below.
1087 GeoIPExcludeUnknown 0|1|auto
1089 If this option is set to auto, then whenever any country code is
1090 set in ExcludeNodes or ExcludeExitNodes, all nodes with unknown
1091 country ({??} and possibly {A1}) are treated as excluded as well.
1092 If this option is set to 1, then all unknown countries are treated
1093 as excluded in ExcludeNodes and ExcludeExitNodes. This option has
1094 no effect when a GeoIP file isn’t configured or can’t be found.
1095 (Default: auto)
1096 ExitNodes node,node,...
1098 A list of identity fingerprints, country codes, and address
1099 patterns of nodes to use as exit node---that is, a node that
1100 delivers traffic for you outside the Tor network. See the
1101 ExcludeNodes option for more information on how to specify nodes.
1102 Note that if you list too few nodes here, or if you exclude too
1105 many exit nodes with ExcludeExitNodes, you can degrade
1106 functionality. For example, if none of the exits you list allows
1107 traffic on port 80 or 443, you won’t be able to browse the web.
1108 Note also that not every circuit is used to deliver traffic outside
1111 of the Tor network. It is normal to see non-exit circuits (such as
1112 those used to connect to hidden services, those that do directory
1113 fetches, those used for relay reachability self-tests, and so on)
1114 that end at a non-exit node. To keep a node from being used
1115 entirely, see ExcludeNodes and StrictNodes.
1116 The ExcludeNodes option overrides this option: any node listed in
1119 both ExitNodes and ExcludeNodes is treated as excluded.
1120 The .exit address notation, if enabled via MapAddress, overrides
1123 this option.
1124 MiddleNodes node,node,...
1126 A list of identity fingerprints and country codes of nodes to use
1127 for "middle" hops in your normal circuits. Normal circuits include
1128 all circuits except for direct connections to directory servers.
1129 Middle hops are all hops other than exit and entry.
1130 This is an **experimental** feature that is meant to be used by researchers
1133 and developers to test new features in the Tor network safely. Using it
1134 without care will strongly influence your anonymity. This feature might get
1135 removed in the future.
1136 The HSLayer2Node and HSLayer3Node options override this option for onion
1138 service circuits, if they are set. The vanguards addon will read this
1139 option, and if set, it will set HSLayer2Nodes and HSLayer3Nodes to nodes
1140 from this set.
1141 The ExcludeNodes option overrides this option: any node listed in both
1143 MiddleNodes and ExcludeNodes is treated as excluded. See
1144 the **ExcludeNodes** option for more information on how to specify nodes.
1145 EntryNodes node,node,...
1147 A list of identity fingerprints and country codes of nodes to use
1148 for the first hop in your normal circuits. Normal circuits include
1149 all circuits except for direct connections to directory servers.
1150 The Bridge option overrides this option; if you have configured
1151 bridges and UseBridges is 1, the Bridges are used as your entry
1152 nodes.
1153 The ExcludeNodes option overrides this option: any node listed in
1156 both EntryNodes and ExcludeNodes is treated as excluded. See the
1157 ExcludeNodes option for more information on how to specify nodes.
1158 StrictNodes 0|1
1160 If StrictNodes is set to 1, Tor will treat solely the ExcludeNodes
1161 option as a requirement to follow for all the circuits you
1162 generate, even if doing so will break functionality for you
1163 (StrictNodes does not apply to ExcludeExitNodes, ExitNodes,
1164 MiddleNodes, or MapAddress). If StrictNodes is set to 0, Tor will
1165 still try to avoid nodes in the ExcludeNodes list, but it will err
1166 on the side of avoiding unexpected errors. Specifically,
1167 StrictNodes 0 tells Tor that it is okay to use an excluded node
1168 when it is necessary to perform relay reachability self-tests,
1169 connect to a hidden service, provide a hidden service to a client,
1170 fulfill a .exit request, upload directory information, or download
1171 directory information. (Default: 0)
1172 FascistFirewall 0|1
1174 If 1, Tor will only create outgoing connections to ORs running on
1175 ports that your firewall allows (defaults to 80 and 443; see
1176 FirewallPorts). This will allow you to run Tor as a client behind a
1177 firewall with restrictive policies, but will not allow you to run
1178 as a server behind such a firewall. If you prefer more fine-grained
1179 control, use ReachableAddresses instead.
1180 FirewallPorts PORTS
1182 A list of ports that your firewall allows you to connect to. Only
1183 used when FascistFirewall is set. This option is deprecated; use
1184 ReachableAddresses instead. (Default: 80, 443)
1185 ReachableAddresses IP[/MASK][:PORT]...
1187 A comma-separated list of IP addresses and ports that your firewall
1188 allows you to connect to. The format is as for the addresses in
1189 ExitPolicy, except that "accept" is understood unless "reject" is
1190 explicitly provided. For example, 'ReachableAddresses 99.0.0.0/8,
1191 reject 18.0.0.0/8:80, accept *:80' means that your firewall allows
1192 connections to everything inside net 99, rejects port 80
1193 connections to net 18, and accepts connections to port 80
1194 otherwise. (Default: 'accept *:*'.)
1195 ReachableDirAddresses IP[/MASK][:PORT]...
1197 Like ReachableAddresses, a list of addresses and ports. Tor will
1198 obey these restrictions when fetching directory information, using
1199 standard HTTP GET requests. If not set explicitly then the value of
1200 ReachableAddresses is used. If HTTPProxy is set then these
1201 connections will go through that proxy. (DEPRECATED: This option
1202 has had no effect for some time.)
1203 ReachableORAddresses IP[/MASK][:PORT]...
1205 Like ReachableAddresses, a list of addresses and ports. Tor will
1206 obey these restrictions when connecting to Onion Routers, using
1207 TLS/SSL. If not set explicitly then the value of ReachableAddresses
1208 is used. If HTTPSProxy is set then these connections will go
1209 through that proxy.
1210 The separation between ReachableORAddresses and
1213 ReachableDirAddresses is only interesting when you are connecting
1214 through proxies (see HTTPProxy and HTTPSProxy). Most proxies limit
1215 TLS connections (which Tor uses to connect to Onion Routers) to
1216 port 443, and some limit HTTP GET requests (which Tor uses for
1217 fetching directory information) to port 80.
1218 HidServAuth onion-address auth-cookie [service-name]
1220 Client authorization for a v2 hidden service. Valid onion addresses
1221 contain 16 characters in a-z2-7 plus ".onion", and valid auth
1222 cookies contain 22 characters in A-Za-z0-9+/. The service name is
1223 only used for internal purposes, e.g., for Tor controllers. This
1224 option may be used multiple times for different hidden services. If
1225 a hidden service uses authorization and this option is not set, the
1226 hidden service is not accessible. Hidden services can be configured
1227 to require authorization using the HiddenServiceAuthorizeClient
1228 option.
1229 ClientOnionAuthDir path
1231 Path to the directory containing v3 hidden service authorization
1232 files. Each file is for a single onion address, and the files MUST
1233 have the suffix ".auth_private" (i.e. "bob_onion.auth_private").
1234 The content format MUST be:
1235 <onion-address>:descriptor:x25519:<base32-encoded-privkey>
1237 The <onion-address> MUST NOT have the ".onion" suffix. The
1239 <base32-encoded-privkey> is the base32 representation of the raw
1240 key bytes only (32 bytes for x25519). See Appendix G in the
1241 rend-spec-v3.txt file of torspec for more information.
1242 LongLivedPorts PORTS
1244 A list of ports for services that tend to have long-running
1245 connections (e.g. chat and interactive shells). Circuits for
1246 streams that use these ports will contain only high-uptime nodes,
1247 to reduce the chance that a node will go down before the stream is
1248 finished. Note that the list is also honored for circuits (both
1249 client and service side) involving hidden services whose virtual
1250 port is in this list. (Default: 21, 22, 706, 1863, 5050, 5190,
1251 5222, 5223, 6523, 6667, 6697, 8300)
1252 MapAddress address newaddress
1254 When a request for address arrives to Tor, it will transform to
1255 newaddress before processing it. For example, if you always want
1256 connections to www.example.com to exit via torserver (where
1257 torserver is the fingerprint of the server), use "MapAddress
1258 www.example.com www.example.com.torserver.exit". If the value is
1259 prefixed with a "*.", matches an entire domain. For example, if you
1260 always want connections to example.com and any if its subdomains to
1261 exit via torserver (where torserver is the fingerprint of the
1262 server), use "MapAddress *.example.com
1263 *.example.com.torserver.exit". (Note the leading "*." in each part
1264 of the directive.) You can also redirect all subdomains of a domain
1265 to a single address. For example, "MapAddress *.example.com
1266 www.example.com". If the specified exit is not available, or the
1267 exit can not connect to the site, Tor will fail any connections to
1268 the mapped address.+
1269 NOTES:
1271 1. When evaluating MapAddress expressions Tor stops when it hits
1273 the most recently added expression that matches the requested
1274 address. So if you have the following in your torrc,
1275 www.torproject.org will map to 198.51.100.1:
1276 MapAddress www.torproject.org 192.0.2.1
1278 MapAddress www.torproject.org 198.51.100.1
1279 2. Tor evaluates the MapAddress configuration until it finds no
1281 matches. So if you have the following in your torrc,
1282 www.torproject.org will map to 203.0.113.1:
1283 MapAddress 198.51.100.1 203.0.113.1
1285 MapAddress www.torproject.org 198.51.100.1
1286 3. The following MapAddress expression is invalid (and will be
1288 ignored) because you cannot map from a specific address to a
1289 wildcard address:
1290 MapAddress www.torproject.org *.torproject.org.torserver.exit
1292 4. Using a wildcard to match only part of a string (as in
1294 *ample.com) is also invalid.
1295 5. Tor maps hostnames and IP addresses separately. If you
1297 MapAddress a DNS name, but use an IP address to connect, then
1298 Tor will ignore the DNS name mapping.
1299 6. MapAddress does not apply to redirects in the application
1301 protocol. For example, HTTP redirects and alt-svc headers will
1302 ignore mappings for the original address. You can use a
1303 wildcard mapping to handle redirects within the same site.
1304 NewCircuitPeriod NUM
1306 Every NUM seconds consider whether to build a new circuit.
1307 (Default: 30 seconds)
1308 MaxCircuitDirtiness NUM
1310 Feel free to reuse a circuit that was first used at most NUM
1311 seconds ago, but never attach a new stream to a circuit that is too
1312 old. For hidden services, this applies to the last time a circuit
1313 was used, not the first. Circuits with streams constructed with
1314 SOCKS authentication via SocksPorts that have
1315 KeepAliveIsolateSOCKSAuth also remain alive for MaxCircuitDirtiness
1316 seconds after carrying the last such stream. (Default: 10 minutes)
1317 MaxClientCircuitsPending NUM
1319 Do not allow more than NUM circuits to be pending at a time for
1320 handling client streams. A circuit is pending if we have begun
1321 constructing it, but it has not yet been completely constructed.
1322 (Default: 32)
1323 NodeFamily node,node,...
1325 The Tor servers, defined by their identity fingerprints, constitute
1326 a "family" of similar or co-administered servers, so never use any
1327 two of them in the same circuit. Defining a NodeFamily is only
1328 needed when a server doesn’t list the family itself (with
1329 MyFamily). This option can be used multiple times; each instance
1330 defines a separate family. In addition to nodes, you can also list
1331 IP address and ranges and country codes in {curly braces}. See the
1332 ExcludeNodes option for more information on how to specify nodes.
1333 EnforceDistinctSubnets 0|1
1335 If 1, Tor will not put two servers whose IP addresses are "too
1336 close" on the same circuit. Currently, two addresses are "too
1337 close" if they lie in the same /16 range. (Default: 1)
1338 SocksPort [address:]port|unix:path|auto [flags] [isolation flags]
1340 Open this port to listen for connections from SOCKS-speaking
1341 applications. Set this to 0 if you don’t want to allow application
1342 connections via SOCKS. Set it to "auto" to have Tor pick a port for
1343 you. This directive can be specified multiple times to bind to
1344 multiple addresses/ports. If a unix domain socket is used, you may
1345 quote the path using standard C escape sequences. (Default: 9050)
1346 NOTE: Although this option allows you to specify an IP address
1349 other than localhost, you should do so only with extreme caution.
1350 The SOCKS protocol is unencrypted and (as we use it)
1351 unauthenticated, so exposing it in this way could leak your
1352 information to anybody watching your network, and allow anybody to
1353 use your computer as an open proxy.
1354 If multiple entries of this option are present in your
1357 configuration file, Tor will perform stream isolation between
1358 listeners by default. The isolation flags arguments give Tor rules
1359 for which streams received on this SocksPort are allowed to share
1360 circuits with one another. Recognized isolation flags are:
1361 IsolateClientAddr
1363 Don’t share circuits with streams from a different client
1364 address. (On by default and strongly recommended when
1365 supported; you can disable it with NoIsolateClientAddr.
1366 Unsupported and force-disabled when using Unix domain sockets.)
1367 IsolateSOCKSAuth
1369 Don’t share circuits with streams for which different SOCKS
1370 authentication was provided. (For HTTPTunnelPort connections,
1371 this option looks at the Proxy-Authorization and
1372 X-Tor-Stream-Isolation headers. On by default; you can disable
1373 it with NoIsolateSOCKSAuth.)
1374 IsolateClientProtocol
1376 Don’t share circuits with streams using a different protocol.
1377 (SOCKS 4, SOCKS 5, TransPort connections, NATDPort connections,
1378 and DNSPort requests are all considered to be different
1379 protocols.)
1380 IsolateDestPort
1382 Don’t share circuits with streams targeting a different
1383 destination port.
1384 IsolateDestAddr
1386 Don’t share circuits with streams targeting a different
1387 destination address.
1388 KeepAliveIsolateSOCKSAuth
1390 If IsolateSOCKSAuth is enabled, keep alive circuits while they
1391 have at least one stream with SOCKS authentication active.
1392 After such a circuit is idle for more than MaxCircuitDirtiness
1393 seconds, it can be closed.
1394 SessionGroup=INT
1396 If no other isolation rules would prevent it, allow streams on
1397 this port to share circuits with streams from every other port
1398 with the same session group. (By default, streams received on
1399 different SocksPorts, TransPorts, etc are always isolated from
1400 one another. This option overrides that behavior.)
1401 Other recognized flags for a SocksPort are:
1403 NoIPv4Traffic
1405 Tell exits to not connect to IPv4 addresses in response to
1406 SOCKS requests on this connection.
1407 IPv6Traffic
1409 Tell exits to allow IPv6 addresses in response to SOCKS
1410 requests on this connection, so long as SOCKS5 is in use.
1411 (SOCKS4 can’t handle IPv6.)
1412 PreferIPv6
1414 Tells exits that, if a host has both an IPv4 and an IPv6
1415 address, we would prefer to connect to it via IPv6. (IPv4 is
1416 the default.)
1417 NoDNSRequest
1419 Do not ask exits to resolve DNS addresses in SOCKS5 requests.
1420 Tor will connect to IPv4 addresses, IPv6 addresses (if
1421 IPv6Traffic is set) and .onion addresses.
1422 NoOnionTraffic
1424 Do not connect to .onion addresses in SOCKS5 requests.
1425 OnionTrafficOnly
1427 Tell the tor client to only connect to .onion addresses in
1428 response to SOCKS5 requests on this connection. This is
1429 equivalent to NoDNSRequest, NoIPv4Traffic, NoIPv6Traffic. The
1430 corresponding NoOnionTrafficOnly flag is not supported.
1431 CacheIPv4DNS
1433 Tells the client to remember IPv4 DNS answers we receive from
1434 exit nodes via this connection.
1435 CacheIPv6DNS
1437 Tells the client to remember IPv6 DNS answers we receive from
1438 exit nodes via this connection.
1439 GroupWritable
1441 Unix domain sockets only: makes the socket get created as
1442 group-writable.
1443 WorldWritable
1445 Unix domain sockets only: makes the socket get created as
1446 world-writable.
1447 CacheDNS
1449 Tells the client to remember all DNS answers we receive from
1450 exit nodes via this connection.
1451 UseIPv4Cache
1453 Tells the client to use any cached IPv4 DNS answers we have
1454 when making requests via this connection. (NOTE: This option,
1455 or UseIPv6Cache or UseDNSCache, can harm your anonymity, and
1456 probably won’t help performance as much as you might expect.
1457 Use with care!)
1458 UseIPv6Cache
1460 Tells the client to use any cached IPv6 DNS answers we have
1461 when making requests via this connection.
1462 UseDNSCache
1464 Tells the client to use any cached DNS answers we have when
1465 making requests via this connection.
1466 PreferIPv6Automap
1468 When serving a hostname lookup request on this port that should
1469 get automapped (according to AutomapHostsOnResolve), if we
1470 could return either an IPv4 or an IPv6 answer, prefer an IPv6
1471 answer. (On by default.)
1472 PreferSOCKSNoAuth
1474 Ordinarily, when an application offers both "username/password
1475 authentication" and "no authentication" to Tor via SOCKS5, Tor
1476 selects username/password authentication so that
1477 IsolateSOCKSAuth can work. This can confuse some applications,
1478 if they offer a username/password combination then get confused
1479 when asked for one. You can disable this behavior, so that Tor
1480 will select "No authentication" when IsolateSOCKSAuth is
1481 disabled, or when this option is set.
1482 Flags are processed left to right. If flags conflict, the last flag
1484 on the line is used, and all earlier flags are ignored. No error is
1485 issued for conflicting flags.
1486 SocksPolicy policy,policy,...
1488 Set an entrance policy for this server, to limit who can connect to
1489 the SocksPort and DNSPort ports. The policies have the same form as
1490 exit policies below, except that port specifiers are ignored. Any
1491 address not matched by some entry in the policy is accepted.
1492 SocksTimeout NUM
1494 Let a socks connection wait NUM seconds handshaking, and NUM
1495 seconds unattached waiting for an appropriate circuit, before we
1496 fail it. (Default: 2 minutes)
1497 TokenBucketRefillInterval NUM [msec|second]
1499 Set the refill delay interval of Tor’s token bucket to NUM
1500 milliseconds. NUM must be between 1 and 1000, inclusive. When Tor
1501 is out of bandwidth, on a connection or globally, it will wait up
1502 to this long before it tries to use that connection again. Note
1503 that bandwidth limits are still expressed in bytes per second: this
1504 option only affects the frequency with which Tor checks to see
1505 whether previously exhausted connections may read again. Can not be
1506 changed while tor is running. (Default: 100 msec)
1507 TrackHostExits host,.domain,...
1509 For each value in the comma separated list, Tor will track recent
1510 connections to hosts that match this value and attempt to reuse the
1511 same exit node for each. If the value is prepended with a '.', it
1512 is treated as matching an entire domain. If one of the values is
1513 just a '.', it means match everything. This option is useful if you
1514 frequently connect to sites that will expire all your
1515 authentication cookies (i.e. log you out) if your IP address
1516 changes. Note that this option does have the disadvantage of making
1517 it more clear that a given history is associated with a single
1518 user. However, most people who would wish to observe this will
1519 observe it through cookies or other protocol-specific means anyhow.
1520 TrackHostExitsExpire NUM
1522 Since exit servers go up and down, it is desirable to expire the
1523 association between host and exit server after NUM seconds. The
1524 default is 1800 seconds (30 minutes).
1525 UpdateBridgesFromAuthority 0|1
1527 When set (along with UseBridges), Tor will try to fetch bridge
1528 descriptors from the configured bridge authorities when feasible.
1529 It will fall back to a direct request if the authority responds
1530 with a 404. (Default: 0)
1531 UseBridges 0|1
1533 When set, Tor will fetch descriptors for each bridge listed in the
1534 "Bridge" config lines, and use these relays as both entry guards
1535 and directory guards. (Default: 0)
1536 UseEntryGuards 0|1
1538 If this option is set to 1, we pick a few long-term entry servers,
1539 and try to stick with them. This is desirable because constantly
1540 changing servers increases the odds that an adversary who owns some
1541 servers will observe a fraction of your paths. Entry Guards can not
1542 be used by Directory Authorities or Single Onion Services. In these
1543 cases, this option is ignored. (Default: 1)
1544 GuardfractionFile FILENAME
1546 V3 authoritative directories only. Configures the location of the
1547 guardfraction file which contains information about how long relays
1548 have been guards. (Default: unset)
1549 UseGuardFraction 0|1|auto
1551 This option specifies whether clients should use the guardfraction
1552 information found in the consensus during path selection. If it’s
1553 set to auto, clients will do what the UseGuardFraction consensus
1554 parameter tells them to do. (Default: auto)
1555 NumEntryGuards NUM
1557 If UseEntryGuards is set to 1, we will try to pick a total of NUM
1558 routers as long-term entries for our circuits. If NUM is 0, we try
1559 to learn the number from the guard-n-primary-guards-to-use
1560 consensus parameter, and default to 1 if the consensus parameter
1561 isn’t set. (Default: 0)
1562 NumPrimaryGuards NUM
1564 If UseEntryGuards is set to 1, we will try to pick NUM routers for
1565 our primary guard list, which is the set of routers we strongly
1566 prefer when connecting to the Tor network. If NUM is 0, we try to
1567 learn the number from the guard-n-primary-guards consensus
1568 parameter, and default to 3 if the consensus parameter isn’t set.
1569 (Default: 0)
1570 NumDirectoryGuards NUM
1572 If UseEntryGuards is set to 1, we try to make sure we have at least
1573 NUM routers to use as directory guards. If this option is set to 0,
1574 use the value from the guard-n-primary-dir-guards-to-use consensus
1575 parameter, and default to 3 if the consensus parameter isn’t set.
1576 (Default: 0)
1577 GuardLifetime N days|weeks|months
1579 If UseEntryGuards is set, minimum time to keep a guard on our guard
1580 list before picking a new one. If less than one day, we use
1581 defaults from the consensus directory. (Default: 0)
1582 SafeSocks 0|1
1584 When this option is enabled, Tor will reject application
1585 connections that use unsafe variants of the socks protocol — ones
1586 that only provide an IP address, meaning the application is doing a
1587 DNS resolve first. Specifically, these are socks4 and socks5 when
1588 not doing remote DNS. (Default: 0)
1589 TestSocks 0|1
1591 When this option is enabled, Tor will make a notice-level log entry
1592 for each connection to the Socks port indicating whether the
1593 request used a safe socks protocol or an unsafe one (see above
1594 entry on SafeSocks). This helps to determine whether an application
1595 using Tor is possibly leaking DNS requests. (Default: 0)
1596 VirtualAddrNetworkIPv4 IPv4Address/bits
1598 VirtualAddrNetworkIPv6 [IPv6Address]/bits
1600 When Tor needs to assign a virtual (unused) address because of a
1601 MAPADDRESS command from the controller or the AutomapHostsOnResolve
1602 feature, Tor picks an unassigned address from this range.
1603 (Defaults: 127.192.0.0/10 and [FE80::]/10 respectively.)
1604 When providing proxy server service to a network of computers using
1607 a tool like dns-proxy-tor, change the IPv4 network to
1608 "10.192.0.0/10" or "172.16.0.0/12" and change the IPv6 network to
1609 "[FC00::]/7". The default VirtualAddrNetwork address ranges on a
1610 properly configured machine will route to the loopback or
1611 link-local interface. The maximum number of bits for the network
1612 prefix is set to 104 for IPv6 and 16 for IPv4. However, a wider
1613 network - smaller prefix length
1614 · is preferable since it reduces the chances for an attacker to
1616 guess the used IP. For local use, no change to the default
1617 VirtualAddrNetwork setting is needed.
1618 AllowNonRFC953Hostnames 0|1
1620 When this option is disabled, Tor blocks hostnames containing
1621 illegal characters (like @ and :) rather than sending them to an
1622 exit node to be resolved. This helps trap accidental attempts to
1623 resolve URLs and so on. (Default: 0)
1624 HTTPTunnelPort [address:]port|auto [isolation flags]
1626 Open this port to listen for proxy connections using the "HTTP
1627 CONNECT" protocol instead of SOCKS. Set this to 0 if you don’t want
1628 to allow "HTTP CONNECT" connections. Set the port to "auto" to have
1629 Tor pick a port for you. This directive can be specified multiple
1630 times to bind to multiple addresses/ports. If multiple entries of
1631 this option are present in your configuration file, Tor will
1632 perform stream isolation between listeners by default. See
1633 SOCKSPort for an explanation of isolation flags. (Default: 0)
1634 TransPort [address:]port|auto [isolation flags]
1636 Open this port to listen for transparent proxy connections. Set
1637 this to 0 if you don’t want to allow transparent proxy connections.
1638 Set the port to "auto" to have Tor pick a port for you. This
1639 directive can be specified multiple times to bind to multiple
1640 addresses/ports. If multiple entries of this option are present in
1641 your configuration file, Tor will perform stream isolation between
1642 listeners by default. See SOCKSPort for an explanation of isolation
1643 flags.
1644 TransPort requires OS support for transparent proxies, such as
1647 BSDs' pf or Linux’s IPTables. If you’re planning to use Tor as a
1648 transparent proxy for a network, you’ll want to examine and change
1649 VirtualAddrNetwork from the default setting. (Default: 0)
1650 TransProxyType default|TPROXY|ipfw|pf-divert
1652 TransProxyType may only be enabled when there is transparent proxy
1653 listener enabled.
1654 Set this to "TPROXY" if you wish to be able to use the TPROXY Linux
1657 module to transparently proxy connections that are configured using
1658 the TransPort option. Detailed information on how to configure the
1659 TPROXY feature can be found in the Linux kernel source tree in the
1660 file Documentation/networking/tproxy.txt.
1661 Set this option to "ipfw" to use the FreeBSD ipfw interface.
1664 On *BSD operating systems when using pf, set this to "pf-divert" to
1667 take advantage of divert-to rules, which do not modify the packets
1668 like rdr-to rules do. Detailed information on how to configure pf
1669 to use divert-to rules can be found in the pf.conf(5) manual page.
1670 On OpenBSD, divert-to is available to use on versions greater than
1671 or equal to OpenBSD 4.4.
1672 Set this to "default", or leave it unconfigured, to use regular
1675 IPTables on Linux, or to use pf rdr-to rules on *BSD systems.
1676 (Default: "default")
1679 NATDPort [address:]port|auto [isolation flags]
1681 Open this port to listen for connections from old versions of ipfw
1682 (as included in old versions of FreeBSD, etc) using the NATD
1683 protocol. Use 0 if you don’t want to allow NATD connections. Set
1684 the port to "auto" to have Tor pick a port for you. This directive
1685 can be specified multiple times to bind to multiple
1686 addresses/ports. If multiple entries of this option are present in
1687 your configuration file, Tor will perform stream isolation between
1688 listeners by default. See SocksPort for an explanation of isolation
1689 flags.
1690 This option is only for people who cannot use TransPort. (Default:
1693 0)
1694 AutomapHostsOnResolve 0|1
1696 When this option is enabled, and we get a request to resolve an
1697 address that ends with one of the suffixes in AutomapHostsSuffixes,
1698 we map an unused virtual address to that address, and return the
1699 new virtual address. This is handy for making ".onion" addresses
1700 work with applications that resolve an address and then connect to
1701 it. (Default: 0)
1702 AutomapHostsSuffixes SUFFIX,SUFFIX,...
1704 A comma-separated list of suffixes to use with
1705 AutomapHostsOnResolve. The "." suffix is equivalent to "all
1706 addresses." (Default: .exit,.onion).
1707 DNSPort [address:]port|auto [isolation flags]
1709 If non-zero, open this port to listen for UDP DNS requests, and
1710 resolve them anonymously. This port only handles A, AAAA, and PTR
1711 requests---it doesn’t handle arbitrary DNS request types. Set the
1712 port to "auto" to have Tor pick a port for you. This directive can
1713 be specified multiple times to bind to multiple addresses/ports.
1714 See SocksPort for an explanation of isolation flags. (Default: 0)
1715 ClientDNSRejectInternalAddresses 0|1
1717 If true, Tor does not believe any anonymously retrieved DNS answer
1718 that tells it that an address resolves to an internal address (like
1719 127.0.0.1 or 192.168.0.1). This option prevents certain
1720 browser-based attacks; it is not allowed to be set on the default
1721 network. (Default: 1)
1722 ClientRejectInternalAddresses 0|1
1724 If true, Tor does not try to fulfill requests to connect to an
1725 internal address (like 127.0.0.1 or 192.168.0.1) unless an exit
1726 node is specifically requested (for example, via a .exit hostname,
1727 or a controller request). If true, multicast DNS hostnames for
1728 machines on the local network (of the form *.local) are also
1729 rejected. (Default: 1)
1730 DownloadExtraInfo 0|1
1732 If true, Tor downloads and caches "extra-info" documents. These
1733 documents contain information about servers other than the
1734 information in their regular server descriptors. Tor does not use
1735 this information for anything itself; to save bandwidth, leave this
1736 option turned off. (Default: 0)
1737 WarnPlaintextPorts port,port,...
1739 Tells Tor to issue a warnings whenever the user tries to make an
1740 anonymous connection to one of these ports. This option is designed
1741 to alert users to services that risk sending passwords in the
1742 clear. (Default: 23,109,110,143)
1743 RejectPlaintextPorts port,port,...
1745 Like WarnPlaintextPorts, but instead of warning about risky port
1746 uses, Tor will instead refuse to make the connection. (Default:
1747 None)
1748 OptimisticData 0|1|auto
1750 When this option is set, and Tor is using an exit node that
1751 supports the feature, it will try optimistically to send data to
1752 the exit node without waiting for the exit node to report whether
1753 the connection succeeded. This can save a round-trip time for
1754 protocols like HTTP where the client talks first. If OptimisticData
1755 is set to auto, Tor will look at the UseOptimisticData parameter in
1756 the networkstatus. (Default: auto)
1757 HSLayer2Nodes node,node,...
1759 A list of identity fingerprints, nicknames, country codes, and
1760 address patterns of nodes that are allowed to be used as the second
1761 hop in all client or service-side Onion Service circuits. This
1762 option mitigates attacks where the adversary runs middle nodes and
1763 induces your client or service to create many circuits, in order to
1764 discover your primary guard node. (Default: Any node in the network
1765 may be used in the second hop.)
1766 (Example: HSLayer2Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234,
1768 {cc}, 255.254.0.0/8)
1769 When this is set, the resulting hidden service paths will look
1772 like:
1773 C - G - L2 - M - Rend
1775 C - G - L2 - M - HSDir
1777 C - G - L2 - M - Intro
1779 S - G - L2 - M - Rend
1781 S - G - L2 - M - HSDir
1783 S - G - L2 - M - Intro
1785 where C is this client, S is the service, G is the Guard node, L2
1788 is a node from this option, and M is a random middle node. Rend,
1789 HSDir, and Intro point selection is not affected by this option.
1790 This option may be combined with HSLayer3Nodes to create paths of
1792 the form:
1793 C - G - L2 - L3 - Rend
1795 C - G - L2 - L3 - M - HSDir
1797 C - G - L2 - L3 - M - Intro
1799 S - G - L2 - L3 - M - Rend
1801 S - G - L2 - L3 - HSDir
1803 S - G - L2 - L3 - Intro
1805 ExcludeNodes have higher priority than HSLayer2Nodes, which means
1808 that nodes specified in ExcludeNodes will not be picked.
1809 When either this option or HSLayer3Nodes are set, the /16 subnet
1811 and node family restrictions are removed for hidden service
1812 circuits. Additionally, we allow the guard node to be present as
1813 the Rend, HSDir, and IP node, and as the hop before it. This is
1814 done to prevent the adversary from inferring information about our
1815 guard, layer2, and layer3 node choices at later points in the path.
1816 This option is meant to be managed by a Tor controller such as
1818 https://github.com/mikeperry-tor/vanguards that selects and updates
1819 this set of nodes for you. Hence it does not do load balancing if
1820 fewer than 20 nodes are selected, and if no nodes in HSLayer2Nodes
1821 are currently available for use, Tor will not work. Please use
1822 extreme care if you are setting this option manually.
1823 HSLayer3Nodes node,node,...
1825 A list of identity fingerprints, nicknames, country codes, and
1826 address patterns of nodes that are allowed to be used as the third
1827 hop in all client and service-side Onion Service circuits. This
1828 option mitigates attacks where the adversary runs middle nodes and
1829 induces your client or service to create many circuits, in order to
1830 discover your primary or Layer2 guard nodes. (Default: Any node in
1831 the network may be used in the third hop.)
1832 (Example: HSLayer3Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234,
1834 {cc}, 255.254.0.0/8)
1835 When this is set by itself, the resulting hidden service paths will
1838 look like:
1839 C - G - M - L3 - Rend
1841 C - G - M - L3 - M - HSDir
1843 C - G - M - L3 - M - Intro
1845 S - G - M - L3 - M - Rend
1847 S - G - M - L3 - HSDir
1849 S - G - M - L3 - Intro
1851 where C is this client, S is the service, G is the Guard node, L2
1853 is a node from this option, and M is a random middle node. Rend,
1854 HSDir, and Intro point selection is not affected by this option.
1855 While it is possible to use this option by itself, it should be
1857 combined with HSLayer2Nodes to create paths of the form:
1858 C - G - L2 - L3 - Rend
1860 C - G - L2 - L3 - M - HSDir
1862 C - G - L2 - L3 - M - Intro
1864 S - G - L2 - L3 - M - Rend
1866 S - G - L2 - L3 - HSDir
1868 S - G - L2 - L3 - Intro
1870 ExcludeNodes have higher priority than HSLayer3Nodes, which means
1873 that nodes specified in ExcludeNodes will not be picked.
1874 When either this option or HSLayer2Nodes are set, the /16 subnet
1876 and node family restrictions are removed for hidden service
1877 circuits. Additionally, we allow the guard node to be present as
1878 the Rend, HSDir, and IP node, and as the hop before it. This is
1879 done to prevent the adversary from inferring information about our
1880 guard, layer2, and layer3 node choices at later points in the path.
1881 This option is meant to be managed by a Tor controller such as
1883 https://github.com/mikeperry-tor/vanguards that selects and updates
1884 this set of nodes for you. Hence it does not do load balancing if
1885 fewer than 20 nodes are selected, and if no nodes in HSLayer3Nodes
1886 are currently available for use, Tor will not work. Please use
1887 extreme care if you are setting this option manually.
1888 UseMicrodescriptors 0|1|auto
1890 Microdescriptors are a smaller version of the information that Tor
1891 needs in order to build its circuits. Using microdescriptors makes
1892 Tor clients download less directory information, thus saving
1893 bandwidth. Directory caches need to fetch regular descriptors and
1894 microdescriptors, so this option doesn’t save any bandwidth for
1895 them. For legacy reasons, auto is accepted, but it has the same
1896 effect as 1. (Default: auto)
1897 PathBiasCircThreshold NUM
1899 PathBiasNoticeRate NUM
1901 PathBiasWarnRate NUM
1903 PathBiasExtremeRate NUM
1905 PathBiasDropGuards NUM
1907 PathBiasScaleThreshold NUM
1909 These options override the default behavior of Tor’s (currently
1910 experimental) path bias detection algorithm. To try to find broken
1911 or misbehaving guard nodes, Tor looks for nodes where more than a
1912 certain fraction of circuits through that guard fail to get built.
1913 The PathBiasCircThreshold option controls how many circuits we need
1916 to build through a guard before we make these checks. The
1917 PathBiasNoticeRate, PathBiasWarnRate and PathBiasExtremeRate
1918 options control what fraction of circuits must succeed through a
1919 guard so we won’t write log messages. If less than
1920 PathBiasExtremeRate circuits succeed and PathBiasDropGuards is set
1921 to 1, we disable use of that guard.
1922 When we have seen more than PathBiasScaleThreshold circuits through
1925 a guard, we scale our observations by 0.5 (governed by the
1926 consensus) so that new observations don’t get swamped by old ones.
1927 By default, or if a negative value is provided for one of these
1930 options, Tor uses reasonable defaults from the networkstatus
1931 consensus document. If no defaults are available there, these
1932 options default to 150, .70, .50, .30, 0, and 300 respectively.
1933 PathBiasUseThreshold NUM
1935 PathBiasNoticeUseRate NUM
1937 PathBiasExtremeUseRate NUM
1939 PathBiasScaleUseThreshold NUM
1941 Similar to the above options, these options override the default
1942 behavior of Tor’s (currently experimental) path use bias detection
1943 algorithm.
1944 Where as the path bias parameters govern thresholds for
1947 successfully building circuits, these four path use bias parameters
1948 govern thresholds only for circuit usage. Circuits which receive no
1949 stream usage are not counted by this detection algorithm. A used
1950 circuit is considered successful if it is capable of carrying
1951 streams or otherwise receiving well-formed responses to RELAY
1952 cells.
1953 By default, or if a negative value is provided for one of these
1956 options, Tor uses reasonable defaults from the networkstatus
1957 consensus document. If no defaults are available there, these
1958 options default to 20, .80, .60, and 100, respectively.
1959 ClientUseIPv4 0|1
1961 If this option is set to 0, Tor will avoid connecting to directory
1962 servers and entry nodes over IPv4. Note that clients with an IPv4
1963 address in a Bridge, proxy, or pluggable transport line will try
1964 connecting over IPv4 even if ClientUseIPv4 is set to 0. (Default:
1965 1)
1966 ClientUseIPv6 0|1
1968 If this option is set to 1, Tor might connect to directory servers
1969 or entry nodes over IPv6. For IPv6 only hosts, you need to also set
1970 ClientUseIPv4 to 0 to disable IPv4. Note that clients configured
1971 with an IPv6 address in a Bridge, proxy, or pluggable transportline
1972 will try connecting over IPv6 even if ClientUseIPv6 is set to 0.
1973 (Default: 0)
1974 ClientPreferIPv6DirPort 0|1|auto
1976 If this option is set to 1, Tor prefers a directory port with an
1977 IPv6 address over one with IPv4, for direct connections, if a given
1978 directory server has both. (Tor also prefers an IPv6 DirPort if
1979 IPv4Client is set to 0.) If this option is set to auto, clients
1980 prefer IPv4. Other things may influence the choice. This option
1981 breaks a tie to the favor of IPv6. (Default: auto) (DEPRECATED:
1982 This option has had no effect for some time.)
1983 ClientPreferIPv6ORPort 0|1|auto
1985 If this option is set to 1, Tor prefers an OR port with an IPv6
1986 address over one with IPv4 if a given entry node has both. (Tor
1987 also prefers an IPv6 ORPort if IPv4Client is set to 0.) If this
1988 option is set to auto, Tor bridge clients prefer the configured
1989 bridge address, and other clients prefer IPv4. Other things may
1990 influence the choice. This option breaks a tie to the favor of
1991 IPv6. (Default: auto)
1992 ClientAutoIPv6ORPort 0|1
1994 If this option is set to 1, Tor clients randomly prefer a node’s
1995 IPv4 or IPv6 ORPort. The random preference is set every time a node
1996 is loaded from a new consensus or bridge config. When this option
1997 is set to 1, ClientPreferIPv6ORPort is ignored. (Default: 0)
1998 PathsNeededToBuildCircuits NUM
2000 Tor clients don’t build circuits for user traffic until they know
2001 about enough of the network so that they could potentially
2002 construct enough of the possible paths through the network. If this
2003 option is set to a fraction between 0.25 and 0.95, Tor won’t build
2004 circuits until it has enough descriptors or microdescriptors to
2005 construct that fraction of possible paths. Note that setting this
2006 option too low can make your Tor client less anonymous, and setting
2007 it too high can prevent your Tor client from bootstrapping. If this
2008 option is negative, Tor will use a default value chosen by the
2009 directory authorities. If the directory authorities do not choose a
2010 value, Tor will default to 0.6. (Default: -1)
2011 ClientBootstrapConsensusAuthorityDownloadInitialDelay N
2013 Initial delay in seconds for when clients should download
2014 consensuses from authorities if they are bootstrapping (that is,
2015 they don’t have a usable, reasonably live consensus). Only used by
2016 clients fetching from a list of fallback directory mirrors. This
2017 schedule is advanced by (potentially concurrent) connection
2018 attempts, unlike other schedules, which are advanced by connection
2019 failures. (Default: 6)
2020 ClientBootstrapConsensusFallbackDownloadInitialDelay N
2022 Initial delay in seconds for when clients should download
2023 consensuses from fallback directory mirrors if they are
2024 bootstrapping (that is, they don’t have a usable, reasonably live
2025 consensus). Only used by clients fetching from a list of fallback
2026 directory mirrors. This schedule is advanced by (potentially
2027 concurrent) connection attempts, unlike other schedules, which are
2028 advanced by connection failures. (Default: 0)
2029 ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay N
2031 Initial delay in seconds for when clients should download
2032 consensuses from authorities if they are bootstrapping (that is,
2033 they don’t have a usable, reasonably live consensus). Only used by
2034 clients which don’t have or won’t fetch from a list of fallback
2035 directory mirrors. This schedule is advanced by (potentially
2036 concurrent) connection attempts, unlike other schedules, which are
2037 advanced by connection failures. (Default: 0)
2038 ClientBootstrapConsensusMaxInProgressTries NUM
2040 Try this many simultaneous connections to download a consensus
2041 before waiting for one to complete, timeout, or error out.
2042 (Default: 3)
2043 DormantClientTimeout N minutes|hours|days|weeks
2045 If Tor spends this much time without any client activity, enter a
2046 dormant state where automatic circuits are not built, and directory
2047 information is not fetched. Does not affect servers or onion
2048 services. Must be at least 10 minutes. (Default: 24 hours)
2049 DormantTimeoutDisabledByIdleStreams 0|1
2051 If true, then any open client stream (even one not reading or
2052 writing) counts as client activity for the purpose of
2053 DormantClientTimeout. If false, then only network activity counts.
2054 (Default: 1)
2055 DormantOnFirstStartup 0|1
2057 If true, then the first time Tor starts up with a fresh
2058 DataDirectory, it starts in dormant mode, and takes no actions
2059 until the user has made a request. (This mode is recommended if
2060 installing a Tor client for a user who might not actually use it.)
2061 If false, Tor bootstraps the first time it is started, whether it
2062 sees a user request or not.
2063 After the first time Tor starts, it begins in dormant mode if it
2065 was dormant before, and not otherwise. (Default: 0)
2066 DormantCanceledByStartup 0|1
2068 By default, Tor starts in active mode if it was active the last
2069 time it was shut down, and in dormant mode if it was dormant. But
2070 if this option is true, Tor treats every startup event as user
2071 activity, and Tor will never start in Dormant mode, even if it has
2072 been unused for a long time on previous runs. (Default: 0)
2073 Note: Packagers and application developers should change the value
2075 of this option only with great caution: it has the potential to
2076 create spurious traffic on the network. This option should only be
2077 used if Tor is started by an affirmative user activity (like
2078 clicking on an applcation or running a command), and not if Tor is
2079 launched for some other reason (for example, by a startup process,
2080 or by an application that launches itself on every login.)
2081
2083 The following options are useful only for servers (that is, if ORPort
2084 is non-zero):
2085 Address address
2087 The IPv4 address of this server, or a fully qualified domain name
2088 of this server that resolves to an IPv4 address. You can leave this
2089 unset, and Tor will try to guess your IPv4 address. This IPv4
2090 address is the one used to tell clients and other servers where to
2091 find your Tor server; it doesn’t affect the address that your
2092 server binds to. To bind to a different address, use the ORPort and
2093 OutboundBindAddress options.
2094 AssumeReachable 0|1
2096 This option is used when bootstrapping a new Tor network. If set to
2097 1, don’t do self-reachability testing; just upload your server
2098 descriptor immediately. If AuthoritativeDirectory is also set, this
2099 option instructs the dirserver to bypass remote reachability
2100 testing too and list all connected servers as running.
2101 BridgeRelay 0|1
2103 Sets the relay to act as a "bridge" with respect to relaying
2104 connections from bridge users to the Tor network. It mainly causes
2105 Tor to publish a server descriptor to the bridge database, rather
2106 than to the public directory authorities.
2107 Note: make sure that no MyFamily lines are present in your torrc
2110 when relay is configured in bridge mode.
2111 BridgeDistribution string
2113 If set along with BridgeRelay, Tor will include a new line in its
2114 bridge descriptor which indicates to the BridgeDB service how it
2115 would like its bridge address to be given out. Set it to "none" if
2116 you want BridgeDB to avoid distributing your bridge address, or
2117 "any" to let BridgeDB decide. (Default: any)
2118 ContactInfo email_address
2120 Administrative contact information for this relay or bridge. This
2121 line can be used to contact you if your relay or bridge is
2122 misconfigured or something else goes wrong. Note that we archive
2123 and publish all descriptors containing these lines and that Google
2124 indexes them, so spammers might also collect them. You may want to
2125 obscure the fact that it’s an email address and/or generate a new
2126 address for this purpose.
2127 ContactInfo must be set to a working address if you run more than
2130 one relay or bridge. (Really, everybody running a relay or bridge
2131 should set it.)
2132 ExitRelay 0|1|auto
2134 Tells Tor whether to run as an exit relay. If Tor is running as a
2135 non-bridge server, and ExitRelay is set to 1, then Tor allows
2136 traffic to exit according to the ExitPolicy option, the
2137 ReducedExitPolicy option, or the default ExitPolicy (if no other
2138 exit policy option is specified).
2139 If ExitRelay is set to 0, no traffic is allowed to exit, and the
2142 ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored.
2143 If ExitRelay is set to "auto", then Tor checks the ExitPolicy,
2146 ReducedExitPolicy, and IPv6Exit options. If at least one of these
2147 options is set, Tor behaves as if ExitRelay were set to 1. If none
2148 of these exit policy options are set, Tor behaves as if ExitRelay
2149 were set to 0. (Default: auto)
2150 ExitPolicy policy,policy,...
2152 Set an exit policy for this server. Each policy is of the form
2153 "accept[6]|reject[6] ADDR[/MASK][:PORT]". If /MASK is omitted then
2154 this policy just applies to the host given. Instead of giving a
2155 host or network you can also use "*" to denote the universe
2156 (0.0.0.0/0 and ::/0), or *4 to denote all IPv4 addresses, and *6 to
2157 denote all IPv6 addresses. PORT can be a single port number, an
2158 interval of ports "FROM_PORT-TO_PORT", or "*". If PORT is omitted,
2159 that means "*".
2160 For example, "accept 18.7.22.69:*,reject 18.0.0.0/8:*,accept *:*"
2163 would reject any IPv4 traffic destined for MIT except for
2164 web.mit.edu, and accept any other IPv4 or IPv6 traffic.
2165 Tor also allows IPv6 exit policy entries. For instance, "reject6
2168 [FC00::]/7:*" rejects all destinations that share 7 most
2169 significant bit prefix with address FC00::. Respectively, "accept6
2170 [C000::]/3:*" accepts all destinations that share 3 most
2171 significant bit prefix with address C000::.
2172 accept6 and reject6 only produce IPv6 exit policy entries. Using an
2175 IPv4 address with accept6 or reject6 is ignored and generates a
2176 warning. accept/reject allows either IPv4 or IPv6 addresses. Use *4
2177 as an IPv4 wildcard address, and *6 as an IPv6 wildcard address.
2178 accept/reject * expands to matching IPv4 and IPv6 wildcard address
2179 rules.
2180 To specify all IPv4 and IPv6 internal and link-local networks
2183 (including 0.0.0.0/8, 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16,
2184 10.0.0.0/8, 172.16.0.0/12, [::]/8, [FC00::]/7, [FE80::]/10,
2185 [FEC0::]/10, [FF00::]/8, and [::]/127), you can use the "private"
2186 alias instead of an address. ("private" always produces rules for
2187 IPv4 and IPv6 addresses, even when used with accept6/reject6.)
2188 Private addresses are rejected by default (at the beginning of your
2191 exit policy), along with any configured primary public IPv4 and
2192 IPv6 addresses. These private addresses are rejected unless you set
2193 the ExitPolicyRejectPrivate config option to 0. For example, once
2194 you’ve done that, you could allow HTTP to 127.0.0.1 and block all
2195 other connections to internal networks with "accept
2196 127.0.0.1:80,reject private:*", though that may also allow
2197 connections to your own computer that are addressed to its public
2198 (external) IP address. See RFC 1918 and RFC 3330 for more details
2199 about internal and reserved IP address space. See
2200 ExitPolicyRejectLocalInterfaces if you want to block every address
2201 on the relay, even those that aren’t advertised in the descriptor.
2202 This directive can be specified multiple times so you don’t have to
2205 put it all on one line.
2206 Policies are considered first to last, and the first match wins. If
2209 you want to allow the same ports on IPv4 and IPv6, write your rules
2210 using accept/reject *. If you want to allow different ports on IPv4
2211 and IPv6, write your IPv6 rules using accept6/reject6 *6, and your
2212 IPv4 rules using accept/reject *4. If you want to _replace_ the
2213 default exit policy, end your exit policy with either a reject *:*
2214 or an accept *:*. Otherwise, you’re _augmenting_ (prepending to)
2215 the default exit policy.
2216 If you want to use a reduced exit policy rather than the default
2219 exit policy, set "ReducedExitPolicy 1". If you want to replace the
2220 default exit policy with your custom exit policy, end your exit
2221 policy with either a reject : or an accept :. Otherwise, you’re
2222 augmenting (prepending to) the default or reduced exit policy.
2223 The default exit policy is:
2226 reject *:25
2228 reject *:119
2229 reject *:135-139
2230 reject *:445
2231 reject *:563
2232 reject *:1214
2233 reject *:4661-4666
2234 reject *:6346-6429
2235 reject *:6699
2236 reject *:6881-6999
2237 accept *:*
2238 Since the default exit policy uses accept/reject *, it applies to
2240 both IPv4 and IPv6 addresses.
2241 ExitPolicyRejectPrivate 0|1
2243 Reject all private (local) networks, along with the relay’s
2244 advertised public IPv4 and IPv6 addresses, at the beginning of your
2245 exit policy. See above entry on ExitPolicy. (Default: 1)
2246 ExitPolicyRejectLocalInterfaces 0|1
2248 Reject all IPv4 and IPv6 addresses that the relay knows about, at
2249 the beginning of your exit policy. This includes any
2250 OutboundBindAddress, the bind addresses of any port options, such
2251 as ControlPort or DNSPort, and any public IPv4 and IPv6 addresses
2252 on any interface on the relay. (If IPv6Exit is not set, all IPv6
2253 addresses will be rejected anyway.) See above entry on ExitPolicy.
2254 This option is off by default, because it lists all public relay IP
2255 addresses in the ExitPolicy, even those relay operators might
2256 prefer not to disclose. (Default: 0)
2257 ReducedExitPolicy 0|1
2259 If set, use a reduced exit policy rather than the default one.
2260 The reduced exit policy is an alternative to the default exit
2263 policy. It allows as many Internet services as possible while still
2264 blocking the majority of TCP ports. Currently, the policy allows
2265 approximately 65 ports. This reduces the odds that your node will
2266 be used for peer-to-peer applications.
2267 The reduced exit policy is:
2270 accept *:20-21
2272 accept *:22
2273 accept *:23
2274 accept *:43
2275 accept *:53
2276 accept *:79
2277 accept *:80-81
2278 accept *:88
2279 accept *:110
2280 accept *:143
2281 accept *:194
2282 accept *:220
2283 accept *:389
2284 accept *:443
2285 accept *:464
2286 accept *:465
2287 accept *:531
2288 accept *:543-544
2289 accept *:554
2290 accept *:563
2291 accept *:587
2292 accept *:636
2293 accept *:706
2294 accept *:749
2295 accept *:873
2296 accept *:902-904
2297 accept *:981
2298 accept *:989-990
2299 accept *:991
2300 accept *:992
2301 accept *:993
2302 accept *:994
2303 accept *:995
2304 accept *:1194
2305 accept *:1220
2306 accept *:1293
2307 accept *:1500
2308 accept *:1533
2309 accept *:1677
2310 accept *:1723
2311 accept *:1755
2312 accept *:1863
2313 accept *:2082
2314 accept *:2083
2315 accept *:2086-2087
2316 accept *:2095-2096
2317 accept *:2102-2104
2318 accept *:3128
2319 accept *:3389
2320 accept *:3690
2321 accept *:4321
2322 accept *:4643
2323 accept *:5050
2324 accept *:5190
2325 accept *:5222-5223
2326 accept *:5228
2327 accept *:5900
2328 accept *:6660-6669
2329 accept *:6679
2330 accept *:6697
2331 accept *:8000
2332 accept *:8008
2333 accept *:8074
2334 accept *:8080
2335 accept *:8082
2336 accept *:8087-8088
2337 accept *:8232-8233
2338 accept *:8332-8333
2339 accept *:8443
2340 accept *:8888
2341 accept *:9418
2342 accept *:9999
2343 accept *:10000
2344 accept *:11371
2345 accept *:19294
2346 accept *:19638
2347 accept *:50002
2348 accept *:64738
2349 reject *:*
2350 (Default: 0)
2352 IPv6Exit 0|1
2354 If set, and we are an exit node, allow clients to use us for IPv6
2355 traffic. When this option is set and ExitRelay is auto, we act as
2356 if ExitRelay is 1. (Default: 0)
2357 MaxOnionQueueDelay NUM [msec|second]
2359 If we have more onionskins queued for processing than we can
2360 process in this amount of time, reject new ones. (Default: 1750
2361 msec)
2362 MyFamily fingerprint,fingerprint,...
2364 Declare that this Tor relay is controlled or administered by a
2365 group or organization identical or similar to that of the other
2366 relays, defined by their (possibly $-prefixed) identity
2367 fingerprints. This option can be repeated many times, for
2368 convenience in defining large families: all fingerprints in all
2369 MyFamily lines are merged into one list. When two relays both
2370 declare that they are in the same 'family', Tor clients will not
2371 use them in the same circuit. (Each relay only needs to list the
2372 other servers in its family; it doesn’t need to list itself, but it
2373 won’t hurt if it does.) Do not list any bridge relay as it would
2374 compromise its concealment.
2375 When listing a node, it’s better to list it by fingerprint than by
2378 nickname: fingerprints are more reliable.
2379 If you run more than one relay, the MyFamily option on each relay
2382 must list all other relays, as described above.
2383 Note: do not use MyFamily when configuring your Tor instance as a
2386 brigde.
2387 Nickname name
2389 Set the server’s nickname to 'name'. Nicknames must be between 1
2390 and 19 characters inclusive, and must contain only the characters
2391 [a-zA-Z0-9]. If not set, Unnamed will be used. Relays can always be
2392 uniquely identified by their identity fingerprints.
2393 NumCPUs num
2395 How many processes to use at once for decrypting onionskins and
2396 other parallelizable operations. If this is set to 0, Tor will try
2397 to detect how many CPUs you have, defaulting to 1 if it can’t tell.
2398 (Default: 0)
2399 ORPort [address:]PORT|auto [flags]
2401 Advertise this port to listen for connections from Tor clients and
2402 servers. This option is required to be a Tor server. Set it to
2403 "auto" to have Tor pick a port for you. Set it to 0 to not run an
2404 ORPort at all. This option can occur more than once. (Default: 0)
2405 Tor recognizes these flags on each ORPort:
2408 NoAdvertise
2410 By default, we bind to a port and tell our users about it. If
2411 NoAdvertise is specified, we don’t advertise, but listen
2412 anyway. This can be useful if the port everybody will be
2413 connecting to (for example, one that’s opened on our firewall)
2414 is somewhere else.
2415 NoListen
2417 By default, we bind to a port and tell our users about it. If
2418 NoListen is specified, we don’t bind, but advertise anyway.
2419 This can be useful if something else (for example, a firewall’s
2420 port forwarding configuration) is causing connections to reach
2421 us.
2422 IPv4Only
2424 If the address is absent, or resolves to both an IPv4 and an
2425 IPv6 address, only listen to the IPv4 address.
2426 IPv6Only
2428 If the address is absent, or resolves to both an IPv4 and an
2429 IPv6 address, only listen to the IPv6 address.
2430 For obvious reasons, NoAdvertise and NoListen are mutually
2432 exclusive, and IPv4Only and IPv6Only are mutually exclusive.
2433 PublishServerDescriptor 0|1|v3|bridge,...
2435 This option specifies which descriptors Tor will publish when
2436 acting as a relay. You can choose multiple arguments, separated by
2437 commas.
2438 If this option is set to 0, Tor will not publish its descriptors to
2441 any directories. (This is useful if you’re testing out your server,
2442 or if you’re using a Tor controller that handles directory
2443 publishing for you.) Otherwise, Tor will publish its descriptors of
2444 all type(s) specified. The default is "1", which means "if running
2445 as a relay or bridge, publish descriptors to the appropriate
2446 authorities". Other possibilities are "v3", meaning "publish as if
2447 you’re a relay", and "bridge", meaning "publish as if you’re a
2448 bridge".
2449 ShutdownWaitLength NUM
2451 When we get a SIGINT and we’re a server, we begin shutting down: we
2452 close listeners and start refusing new circuits. After NUM seconds,
2453 we exit. If we get a second SIGINT, we exit immediately. (Default:
2454 30 seconds)
2455 SSLKeyLifetime N minutes|hours|days|weeks
2457 When creating a link certificate for our outermost SSL handshake,
2458 set its lifetime to this amount of time. If set to 0, Tor will
2459 choose some reasonable random defaults. (Default: 0)
2460 HeartbeatPeriod N minutes|hours|days|weeks
2462 Log a heartbeat message every HeartbeatPeriod seconds. This is a
2463 log level notice message, designed to let you know your Tor server
2464 is still alive and doing useful things. Settings this to 0 will
2465 disable the heartbeat. Otherwise, it must be at least 30 minutes.
2466 (Default: 6 hours)
2467 MainloopStats 0|1
2469 Log main loop statistics every HeartbeatPeriod seconds. This is a
2470 log level notice message designed to help developers instrumenting
2471 Tor’s main event loop. (Default: 0)
2472 AccountingMax N
2474 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
2475 Limits the max number of bytes sent and received within a set time
2476 period using a given calculation rule (see: AccountingStart,
2477 AccountingRule). Useful if you need to stay under a specific
2478 bandwidth. By default, the number used for calculation is the max
2479 of either the bytes sent or received. For example, with
2480 AccountingMax set to 1 TByte, a server could send 900 GBytes and
2481 receive 800 GBytes and continue running. It will only hibernate
2482 once one of the two reaches 1 TByte. This can be changed to use the
2483 sum of the both bytes received and sent by setting the
2484 AccountingRule option to "sum" (total bandwidth in/out). When the
2485 number of bytes remaining gets low, Tor will stop accepting new
2486 connections and circuits. When the number of bytes is exhausted,
2487 Tor will hibernate until some time in the next accounting period.
2488 To prevent all servers from waking at the same time, Tor will also
2489 wait until a random point in each period before waking up. If you
2490 have bandwidth cost issues, enabling hibernation is preferable to
2491 setting a low bandwidth, since it provides users with a collection
2492 of fast servers that are up some of the time, which is more useful
2493 than a set of slow servers that are always "available".
2494 Note that (as also described in the Bandwidth section) Tor uses
2497 powers of two, not powers of ten: 1 GByte is 1024*1024*1024, not
2498 one billion. Be careful: some internet service providers might
2499 count GBytes differently.
2500 AccountingRule sum|max|in|out
2502 How we determine when our AccountingMax has been reached (when we
2503 should hibernate) during a time interval. Set to "max" to calculate
2504 using the higher of either the sent or received bytes (this is the
2505 default functionality). Set to "sum" to calculate using the sent
2506 plus received bytes. Set to "in" to calculate using only the
2507 received bytes. Set to "out" to calculate using only the sent
2508 bytes. (Default: max)
2509 AccountingStart day|week|month [day] HH:MM
2511 Specify how long accounting periods last. If month is given, each
2512 accounting period runs from the time HH:MM on the dayth day of one
2513 month to the same day and time of the next. The relay will go at
2514 full speed, use all the quota you specify, then hibernate for the
2515 rest of the period. (The day must be between 1 and 28.) If week is
2516 given, each accounting period runs from the time HH:MM of the dayth
2517 day of one week to the same day and time of the next week, with
2518 Monday as day 1 and Sunday as day 7. If day is given, each
2519 accounting period runs from the time HH:MM each day to the same
2520 time on the next day. All times are local, and given in 24-hour
2521 time. (Default: "month 1 0:00")
2522 RefuseUnknownExits 0|1|auto
2524 Prevent nodes that don’t appear in the consensus from exiting using
2525 this relay. If the option is 1, we always block exit attempts from
2526 such nodes; if it’s 0, we never do, and if the option is "auto",
2527 then we do whatever the authorities suggest in the consensus (and
2528 block if the consensus is quiet on the issue). (Default: auto)
2529 ServerDNSResolvConfFile filename
2531 Overrides the default DNS configuration with the configuration in
2532 filename. The file format is the same as the standard Unix
2533 "resolv.conf" file (7). This option, like all other ServerDNS
2534 options, only affects name lookups that your server does on behalf
2535 of clients. (Defaults to use the system DNS configuration or a
2536 localhost DNS service in case no nameservers are found in a given
2537 configuration.)
2538 ServerDNSAllowBrokenConfig 0|1
2540 If this option is false, Tor exits immediately if there are
2541 problems parsing the system DNS configuration or connecting to
2542 nameservers. Otherwise, Tor continues to periodically retry the
2543 system nameservers until it eventually succeeds. (Default: 1)
2544 ServerDNSSearchDomains 0|1
2546 If set to 1, then we will search for addresses in the local search
2547 domain. For example, if this system is configured to believe it is
2548 in "example.com", and a client tries to connect to "www", the
2549 client will be connected to "www.example.com". This option only
2550 affects name lookups that your server does on behalf of clients.
2551 (Default: 0)
2552 ServerDNSDetectHijacking 0|1
2554 When this option is set to 1, we will test periodically to
2555 determine whether our local nameservers have been configured to
2556 hijack failing DNS requests (usually to an advertising site). If
2557 they are, we will attempt to correct this. This option only affects
2558 name lookups that your server does on behalf of clients. (Default:
2559 1)
2560 ServerDNSTestAddresses hostname,hostname,...
2562 When we’re detecting DNS hijacking, make sure that these valid
2563 addresses aren’t getting redirected. If they are, then our DNS is
2564 completely useless, and we’ll reset our exit policy to "reject
2565 *:*". This option only affects name lookups that your server does
2566 on behalf of clients. (Default: "www.google.com, www.mit.edu,
2567 www.yahoo.com, www.slashdot.org")
2568 ServerDNSAllowNonRFC953Hostnames 0|1
2570 When this option is disabled, Tor does not try to resolve hostnames
2571 containing illegal characters (like @ and :) rather than sending
2572 them to an exit node to be resolved. This helps trap accidental
2573 attempts to resolve URLs and so on. This option only affects name
2574 lookups that your server does on behalf of clients. (Default: 0)
2575 BridgeRecordUsageByCountry 0|1
2577 When this option is enabled and BridgeRelay is also enabled, and we
2578 have GeoIP data, Tor keeps a per-country count of how many client
2579 addresses have contacted it so that it can help the bridge
2580 authority guess which countries have blocked access to it. If
2581 ExtraInfoStatistics is enabled, it will be published as part of
2582 extra-info document. (Default: 1)
2583 ServerDNSRandomizeCase 0|1
2585 When this option is set, Tor sets the case of each character
2586 randomly in outgoing DNS requests, and makes sure that the case
2587 matches in DNS replies. This so-called "0x20 hack" helps resist
2588 some types of DNS poisoning attack. For more information, see
2589 "Increased DNS Forgery Resistance through 0x20-Bit Encoding". This
2590 option only affects name lookups that your server does on behalf of
2591 clients. (Default: 1)
2592 GeoIPFile filename
2594 A filename containing IPv4 GeoIP data, for use with by-country
2595 statistics.
2596 GeoIPv6File filename
2598 A filename containing IPv6 GeoIP data, for use with by-country
2599 statistics.
2600 CellStatistics 0|1
2602 Relays only. When this option is enabled, Tor collects statistics
2603 about cell processing (i.e. mean time a cell is spending in a
2604 queue, mean number of cells in a queue and mean number of processed
2605 cells per circuit) and writes them into disk every 24 hours. Onion
2606 router operators may use the statistics for performance monitoring.
2607 If ExtraInfoStatistics is enabled, it will published as part of
2608 extra-info document. (Default: 0)
2609 PaddingStatistics 0|1
2611 Relays and bridges only. When this option is enabled, Tor collects
2612 statistics for padding cells sent and received by this relay, in
2613 addition to total cell counts. These statistics are rounded, and
2614 omitted if traffic is low. This information is important for load
2615 balancing decisions related to padding. If ExtraInfoStatistics is
2616 enabled, it will be published as a part of extra-info document.
2617 (Default: 1)
2618 DirReqStatistics 0|1
2620 Relays and bridges only. When this option is enabled, a Tor
2621 directory writes statistics on the number and response time of
2622 network status requests to disk every 24 hours. Enables relay and
2623 bridge operators to monitor how much their server is being used by
2624 clients to learn about Tor network. If ExtraInfoStatistics is
2625 enabled, it will published as part of extra-info document.
2626 (Default: 1)
2627 EntryStatistics 0|1
2629 Relays only. When this option is enabled, Tor writes statistics on
2630 the number of directly connecting clients to disk every 24 hours.
2631 Enables relay operators to monitor how much inbound traffic that
2632 originates from Tor clients passes through their server to go
2633 further down the Tor network. If ExtraInfoStatistics is enabled, it
2634 will be published as part of extra-info document. (Default: 0)
2635 ExitPortStatistics 0|1
2637 Exit relays only. When this option is enabled, Tor writes
2638 statistics on the number of relayed bytes and opened stream per
2639 exit port to disk every 24 hours. Enables exit relay operators to
2640 measure and monitor amounts of traffic that leaves Tor network
2641 through their exit node. If ExtraInfoStatistics is enabled, it will
2642 be published as part of extra-info document. (Default: 0)
2643 ConnDirectionStatistics 0|1
2645 Relays only. When this option is enabled, Tor writes statistics on
2646 the amounts of traffic it passes between itself and other relays to
2647 disk every 24 hours. Enables relay operators to monitor how much
2648 their relay is being used as middle node in the circuit. If
2649 ExtraInfoStatistics is enabled, it will be published as part of
2650 extra-info document. (Default: 0)
2651 HiddenServiceStatistics 0|1
2653 Relays only. When this option is enabled, a Tor relay writes
2654 obfuscated statistics on its role as hidden-service directory,
2655 introduction point, or rendezvous point to disk every 24 hours. If
2656 ExtraInfoStatistics is also enabled, these statistics are further
2657 published to the directory authorities. (Default: 1)
2658 ExtraInfoStatistics 0|1
2660 When this option is enabled, Tor includes previously gathered
2661 statistics in its extra-info documents that it uploads to the
2662 directory authorities. Disabling this option also removes bandwidth
2663 usage statistics, and GeoIPFile and GeoIPv6File hashes from the
2664 extra-info file. Bridge ServerTransportPlugin lines are always
2665 includes in the extra-info file, because they are required by
2666 BridgeDB. (Default: 1)
2667 ExtendAllowPrivateAddresses 0|1
2669 When this option is enabled, Tor will connect to relays on
2670 localhost, RFC1918 addresses, and so on. In particular, Tor will
2671 make direct OR connections, and Tor routers allow EXTEND requests,
2672 to these private addresses. (Tor will always allow connections to
2673 bridges, proxies, and pluggable transports configured on private
2674 addresses.) Enabling this option can create security issues; you
2675 should probably leave it off. (Default: 0)
2676 MaxMemInQueues N bytes|KB|MB|GB
2678 This option configures a threshold above which Tor will assume that
2679 it needs to stop queueing or buffering data because it’s about to
2680 run out of memory. If it hits this threshold, it will begin killing
2681 circuits until it has recovered at least 10% of this memory. Do not
2682 set this option too low, or your relay may be unreliable under
2683 load. This option only affects some queues, so the actual process
2684 size will be larger than this. If this option is set to 0, Tor will
2685 try to pick a reasonable default based on your system’s physical
2686 memory. (Default: 0)
2687 DisableOOSCheck 0|1
2689 This option disables the code that closes connections when Tor
2690 notices that it is running low on sockets. Right now, it is on by
2691 default, since the existing out-of-sockets mechanism tends to kill
2692 OR connections more than it should. (Default: 1)
2693 SigningKeyLifetime N days|weeks|months
2695 For how long should each Ed25519 signing key be valid? Tor uses a
2696 permanent master identity key that can be kept offline, and
2697 periodically generates new "signing" keys that it uses online. This
2698 option configures their lifetime. (Default: 30 days)
2699 OfflineMasterKey 0|1
2701 If non-zero, the Tor relay will never generate or load its master
2702 secret key. Instead, you’ll have to use "tor --keygen" to manage
2703 the permanent ed25519 master identity key, as well as the
2704 corresponding temporary signing keys and certificates. (Default: 0)
2705 KeyDirectory DIR
2707 Store secret keys in DIR. Can not be changed while tor is running.
2708 (Default: the "keys" subdirectory of DataDirectory.)
2709 KeyDirectoryGroupReadable 0|1
2711 If this option is set to 0, don’t allow the filesystem group to
2712 read the KeywDirectory. If the option is set to 1, make the
2713 KeyDirectory readable by the default GID. (Default: 0)
2714 RephistTrackTime N seconds|minutes|hours|days|weeks
2716 Tells an authority, or other node tracking node reliability and
2717 history, that fine-grained information about nodes can be discarded
2718 when it hasn’t changed for a given amount of time. (Default: 24
2719 hours)
2720
2722 The following options are useful only for directory servers. (Relays
2723 with enough bandwidth automatically become directory servers; see
2724 DirCache for details.)
2725 DirPortFrontPage FILENAME
2727 When this option is set, it takes an HTML file and publishes it as
2728 "/" on the DirPort. Now relay operators can provide a disclaimer
2729 without needing to set up a separate webserver. There’s a sample
2730 disclaimer in contrib/operator-tools/tor-exit-notice.html.
2731 DirPort [address:]PORT|auto [flags]
2733 If this option is nonzero, advertise the directory service on this
2734 port. Set it to "auto" to have Tor pick a port for you. This option
2735 can occur more than once, but only one advertised DirPort is
2736 supported: all but one DirPort must have the NoAdvertise flag set.
2737 (Default: 0)
2738 The same flags are supported here as are supported by ORPort.
2741 DirPolicy policy,policy,...
2743 Set an entrance policy for this server, to limit who can connect to
2744 the directory ports. The policies have the same form as exit
2745 policies above, except that port specifiers are ignored. Any
2746 address not matched by some entry in the policy is accepted.
2747 DirCache 0|1
2749 When this option is set, Tor caches all current directory documents
2750 except extra info documents, and accepts client requests for them.
2751 If DownloadExtraInfo is set, cached extra info documents are also
2752 cached. Setting DirPort is not required for DirCache, because
2753 clients connect via the ORPort by default. Setting either DirPort
2754 or BridgeRelay and setting DirCache to 0 is not supported.
2755 (Default: 1)
2756 MaxConsensusAgeForDiffs N minutes|hours|days|weeks
2758 When this option is nonzero, Tor caches will not try to generate
2759 consensus diffs for any consensus older than this amount of time.
2760 If this option is set to zero, Tor will pick a reasonable default
2761 from the current networkstatus document. You should not set this
2762 option unless your cache is severely low on disk space or CPU. If
2763 you need to set it, keeping it above 3 or 4 hours will help clients
2764 much more than setting it to zero. (Default: 0)
2765
2767 Tor has three built-in mitigation options that can be individually
2768 enabled/disabled and fine-tuned, but by default Tor directory
2769 authorities will define reasonable values for relays and no explicit
2770 configuration is required to make use of these protections. The
2771 mitigations take place at relays, and are as follows:
2772 1. If a single client address makes too many concurrent connections
2774 (this is configurable via DoSConnectionMaxConcurrentCount), hang up
2775 on further connections.
2776 2. If a single client IP address (v4 or v6) makes circuits too quickly
2778 (default values are more than 3 per second, with an allowed burst
2779 of 90, see DoSCircuitCreationRate and DoSCircuitCreationBurst)
2780 while also having too many connections open (default is 3, see
2781 DoSCircuitCreationMinConnections), tor will refuse any new circuit
2782 (CREATE cells) for the next while (random value between 1 and 2
2783 hours).
2784 3. If a client asks to establish a rendezvous point to you directly
2786 (ex: Tor2Web client), ignore the request.
2787 These defenses can be manually controlled by torrc options, but relays
2789 will also take guidance from consensus parameters using these same
2790 names, so there’s no need to configure anything manually. In doubt, do
2791 not change those values.
2792 The values set by the consensus, if any, can be found here:
2794 https://consensus-health.torproject.org/#consensusparams
2795 If any of the DoS mitigations are enabled, a heartbeat message will
2797 appear in your log at NOTICE level which looks like:
2798 DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses.
2800 2238 connections closed. 8052 single hop clients refused.
2801 The following options are useful only for a public relay. They control
2803 the Denial of Service mitigation subsystem described above.
2804 DoSCircuitCreationEnabled 0|1|auto
2806 Enable circuit creation DoS mitigation. If set to 1 (enabled), tor
2807 will cache client IPs along with statistics in order to detect
2808 circuit DoS attacks. If an address is positively identified, tor
2809 will activate defenses against the address. See the
2810 DoSCircuitCreationDefenseType option for more details. This is a
2811 client to relay detection only. "auto" means use the consensus
2812 parameter. If not defined in the consensus, the value is 0.
2813 (Default: auto)
2814 DoSCircuitCreationMinConnections NUM
2816 Minimum threshold of concurrent connections before a client address
2817 can be flagged as executing a circuit creation DoS. In other words,
2818 once a client address reaches the circuit rate and has a minimum of
2819 NUM concurrent connections, a detection is positive. "0" means use
2820 the consensus parameter. If not defined in the consensus, the value
2821 is 3. (Default: 0)
2822 DoSCircuitCreationRate NUM
2824 The allowed circuit creation rate per second applied per client IP
2825 address. If this option is 0, it obeys a consensus parameter. If
2826 not defined in the consensus, the value is 3. (Default: 0)
2827 DoSCircuitCreationBurst NUM
2829 The allowed circuit creation burst per client IP address. If the
2830 circuit rate and the burst are reached, a client is marked as
2831 executing a circuit creation DoS. "0" means use the consensus
2832 parameter. If not defined in the consensus, the value is 90.
2833 (Default: 0)
2834 DoSCircuitCreationDefenseType NUM
2836 This is the type of defense applied to a detected client address.
2837 The possible values are:
2838 1: No defense.
2840 2: Refuse circuit creation for the
2842 DoSCircuitCreationDefenseTimePeriod period of time.
2843 "0" means use the consensus parameter. If not defined in the
2845 consensus, the value is 2. (Default: 0)
2846 DoSCircuitCreationDefenseTimePeriod N seconds|minutes|hours
2848 The base time period in seconds that the DoS defense is activated
2849 for. The actual value is selected randomly for each activation from
2850 N+1 to 3/2 * N. "0" means use the consensus parameter. If not
2851 defined in the consensus, the value is 3600 seconds (1 hour).
2852 (Default: 0)
2853 DoSConnectionEnabled 0|1|auto
2855 Enable the connection DoS mitigation. If set to 1 (enabled), for
2856 client address only, this allows tor to mitigate against large
2857 number of concurrent connections made by a single IP address.
2858 "auto" means use the consensus parameter. If not defined in the
2859 consensus, the value is 0. (Default: auto)
2860 DoSConnectionMaxConcurrentCount NUM
2862 The maximum threshold of concurrent connection from a client IP
2863 address. Above this limit, a defense selected by
2864 DoSConnectionDefenseType is applied. "0" means use the consensus
2865 parameter. If not defined in the consensus, the value is 100.
2866 (Default: 0)
2867 DoSConnectionDefenseType NUM
2869 This is the type of defense applied to a detected client address
2870 for the connection mitigation. The possible values are:
2871 1: No defense.
2873 2: Immediately close new connections.
2875 "0" means use the consensus parameter. If not defined in the
2877 consensus, the value is 2. (Default: 0)
2878 DoSRefuseSingleHopClientRendezvous 0|1|auto
2880 Refuse establishment of rendezvous points for single hop clients.
2881 In other words, if a client directly connects to the relay and
2882 sends an ESTABLISH_RENDEZVOUS cell, it is silently dropped. "auto"
2883 means use the consensus parameter. If not defined in the consensus,
2884 the value is 0. (Default: auto)
2885
2887 The following options enable operation as a directory authority, and
2888 control how Tor behaves as a directory authority. You should not need
2889 to adjust any of them if you’re running a regular relay or exit server
2890 on the public Tor network.
2891 AuthoritativeDirectory 0|1
2893 When this option is set to 1, Tor operates as an authoritative
2894 directory server. Instead of caching the directory, it generates
2895 its own list of good servers, signs it, and sends that to the
2896 clients. Unless the clients already have you listed as a trusted
2897 directory, you probably do not want to set this option.
2898 V3AuthoritativeDirectory 0|1
2900 When this option is set in addition to AuthoritativeDirectory, Tor
2901 generates version 3 network statuses and serves descriptors, etc as
2902 described in dir-spec.txt file of torspec (for Tor clients and
2903 servers running at least 0.2.0.x).
2904 VersioningAuthoritativeDirectory 0|1
2906 When this option is set to 1, Tor adds information on which
2907 versions of Tor are still believed safe for use to the published
2908 directory. Each version 1 authority is automatically a versioning
2909 authority; version 2 authorities provide this service optionally.
2910 See RecommendedVersions, RecommendedClientVersions, and
2911 RecommendedServerVersions.
2912 RecommendedVersions STRING
2914 STRING is a comma-separated list of Tor versions currently believed
2915 to be safe. The list is included in each directory, and nodes which
2916 pull down the directory learn whether they need to upgrade. This
2917 option can appear multiple times: the values from multiple lines
2918 are spliced together. When this is set then
2919 VersioningAuthoritativeDirectory should be set too.
2920 RecommendedClientVersions STRING
2922 STRING is a comma-separated list of Tor versions currently believed
2923 to be safe for clients to use. This information is included in
2924 version 2 directories. If this is not set then the value of
2925 RecommendedVersions is used. When this is set then
2926 VersioningAuthoritativeDirectory should be set too.
2927 BridgeAuthoritativeDir 0|1
2929 When this option is set in addition to AuthoritativeDirectory, Tor
2930 accepts and serves server descriptors, but it caches and serves the
2931 main networkstatus documents rather than generating its own.
2932 (Default: 0)
2933 MinUptimeHidServDirectoryV2 N seconds|minutes|hours|days|weeks
2935 Minimum uptime of a v2 hidden service directory to be accepted as
2936 such by authoritative directories. (Default: 25 hours)
2937 RecommendedServerVersions STRING
2939 STRING is a comma-separated list of Tor versions currently believed
2940 to be safe for servers to use. This information is included in
2941 version 2 directories. If this is not set then the value of
2942 RecommendedVersions is used. When this is set then
2943 VersioningAuthoritativeDirectory should be set too.
2944 ConsensusParams STRING
2946 STRING is a space-separated list of key=value pairs that Tor will
2947 include in the "params" line of its networkstatus vote.
2948 DirAllowPrivateAddresses 0|1
2950 If set to 1, Tor will accept server descriptors with arbitrary
2951 "Address" elements. Otherwise, if the address is not an IP address
2952 or is a private IP address, it will reject the server descriptor.
2953 Additionally, Tor will allow exit policies for private networks to
2954 fulfill Exit flag requirements. (Default: 0)
2955 AuthDirBadExit AddressPattern...
2957 Authoritative directories only. A set of address patterns for
2958 servers that will be listed as bad exits in any network status
2959 document this authority publishes, if AuthDirListBadExits is set.
2960 (The address pattern syntax here and in the options below is the
2963 same as for exit policies, except that you don’t need to say
2964 "accept" or "reject", and ports are not needed.)
2965 AuthDirInvalid AddressPattern...
2967 Authoritative directories only. A set of address patterns for
2968 servers that will never be listed as "valid" in any network status
2969 document that this authority publishes.
2970 AuthDirReject AddressPattern...
2972 Authoritative directories only. A set of address patterns for
2973 servers that will never be listed at all in any network status
2974 document that this authority publishes, or accepted as an OR
2975 address in any descriptor submitted for publication by this
2976 authority.
2977 AuthDirBadExitCCs CC,...
2979 AuthDirInvalidCCs CC,...
2981 AuthDirRejectCCs CC,...
2983 Authoritative directories only. These options contain a
2984 comma-separated list of country codes such that any server in one
2985 of those country codes will be marked as a bad exit/invalid for
2986 use, or rejected entirely.
2987 AuthDirListBadExits 0|1
2989 Authoritative directories only. If set to 1, this directory has
2990 some opinion about which nodes are unsuitable as exit nodes. (Do
2991 not set this to 1 unless you plan to list non-functioning exits as
2992 bad; otherwise, you are effectively voting in favor of every
2993 declared exit as an exit.)
2994 AuthDirMaxServersPerAddr NUM
2996 Authoritative directories only. The maximum number of servers that
2997 we will list as acceptable on a single IP address. Set this to "0"
2998 for "no limit". (Default: 2)
2999 AuthDirFastGuarantee N
3001 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3002 Authoritative directories only. If non-zero, always vote the Fast
3003 flag for any relay advertising this amount of capacity or more.
3004 (Default: 100 KBytes)
3005 AuthDirGuardBWGuarantee N
3007 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3008 Authoritative directories only. If non-zero, this advertised
3009 capacity or more is always sufficient to satisfy the bandwidth
3010 requirement for the Guard flag. (Default: 2 MBytes)
3011 AuthDirPinKeys 0|1
3013 Authoritative directories only. If non-zero, do not allow any relay
3014 to publish a descriptor if any other relay has reserved its
3015 <Ed25519,RSA> identity keypair. In all cases, Tor records every
3016 keypair it accepts in a journal if it is new, or if it differs from
3017 the most recently accepted pinning for one of the keys it contains.
3018 (Default: 1)
3019 AuthDirSharedRandomness 0|1
3021 Authoritative directories only. Switch for the shared random
3022 protocol. If zero, the authority won’t participate in the protocol.
3023 If non-zero (default), the flag "shared-rand-participate" is added
3024 to the authority vote indicating participation in the protocol.
3025 (Default: 1)
3026 AuthDirTestEd25519LinkKeys 0|1
3028 Authoritative directories only. If this option is set to 0, then we
3029 treat relays as "Running" if their RSA key is correct when we probe
3030 them, regardless of their Ed25519 key. We should only ever set this
3031 option to 0 if there is some major bug in Ed25519 link
3032 authentication that causes us to label all the relays as not
3033 Running. (Default: 1)
3034 BridgePassword Password
3036 If set, contains an HTTP authenticator that tells a bridge
3037 authority to serve all requested bridge information. Used by the
3038 (only partially implemented) "bridge community" design, where a
3039 community of bridge relay operators all use an alternate bridge
3040 directory authority, and their target user audience can
3041 periodically fetch the list of available community bridges to stay
3042 up-to-date. (Default: not set)
3043 V3AuthVotingInterval N minutes|hours
3045 V3 authoritative directories only. Configures the server’s
3046 preferred voting interval. Note that voting will actually happen at
3047 an interval chosen by consensus from all the authorities' preferred
3048 intervals. This time SHOULD divide evenly into a day. (Default: 1
3049 hour)
3050 V3AuthVoteDelay N minutes|hours
3052 V3 authoritative directories only. Configures the server’s
3053 preferred delay between publishing its vote and assuming it has all
3054 the votes from all the other authorities. Note that the actual time
3055 used is not the server’s preferred time, but the consensus of all
3056 preferences. (Default: 5 minutes)
3057 V3AuthDistDelay N minutes|hours
3059 V3 authoritative directories only. Configures the server’s
3060 preferred delay between publishing its consensus and signature and
3061 assuming it has all the signatures from all the other authorities.
3062 Note that the actual time used is not the server’s preferred time,
3063 but the consensus of all preferences. (Default: 5 minutes)
3064 V3AuthNIntervalsValid NUM
3066 V3 authoritative directories only. Configures the number of
3067 VotingIntervals for which each consensus should be valid for.
3068 Choosing high numbers increases network partitioning risks;
3069 choosing low numbers increases directory traffic. Note that the
3070 actual number of intervals used is not the server’s preferred
3071 number, but the consensus of all preferences. Must be at least 2.
3072 (Default: 3)
3073 V3BandwidthsFile FILENAME
3075 V3 authoritative directories only. Configures the location of the
3076 bandwidth-authority generated file storing information on relays'
3077 measured bandwidth capacities. To avoid inconsistent reads,
3078 bandwidth data should be written to temporary file, then renamed to
3079 the configured filename. (Default: unset)
3080 V3AuthUseLegacyKey 0|1
3082 If set, the directory authority will sign consensuses not only with
3083 its own signing key, but also with a "legacy" key and certificate
3084 with a different identity. This feature is used to migrate
3085 directory authority keys in the event of a compromise. (Default: 0)
3086 AuthDirHasIPv6Connectivity 0|1
3088 Authoritative directories only. When set to 0, OR ports with an
3089 IPv6 address are not included in the authority’s votes. When set to
3090 1, IPv6 OR ports are tested for reachability like IPv4 OR ports. If
3091 the reachability test succeeds, the authority votes for the IPv6
3092 ORPort, and votes Running for the relay. If the reachability test
3093 fails, the authority does not vote for the IPv6 ORPort, and does
3094 not vote Running (Default: 0)
3095 The content of the consensus depends on the number of voting authorities
3098 that set AuthDirHasIPv6Connectivity:
3099 If no authorities set AuthDirHasIPv6Connectivity 1, there will be no
3101 IPv6 ORPorts in the consensus.
3102 If a minority of authorities set AuthDirHasIPv6Connectivity 1,
3104 unreachable IPv6 ORPorts will be removed from the consensus. But the
3105 majority of IPv4-only authorities will still vote the relay as Running.
3106 Reachable IPv6 ORPort lines will be included in the consensus
3107 If a majority of voting authorities set AuthDirHasIPv6Connectivity 1,
3109 relays with unreachable IPv6 ORPorts will not be listed as Running.
3110 Reachable IPv6 ORPort lines will be included in the consensus
3111 (To ensure that any valid majority will vote relays with unreachable
3112 IPv6 ORPorts not Running, 75% of authorities must set
3113 AuthDirHasIPv6Connectivity 1.)
3114 MinMeasuredBWsForAuthToIgnoreAdvertised N
3116 A total value, in abstract bandwidth units, describing how much
3117 measured total bandwidth an authority should have observed on the
3118 network before it will treat advertised bandwidths as wholly
3119 unreliable. (Default: 500)
3120 AuthDirRejectRequestsUnderLoad 0|1
3122 If set, the directory authority will start rejecting directory
3123 requests from non relay connections by sending a 503 error code if
3124 it is under bandwidth pressure (reaching the configured limit if
3125 any). Relays will always tried to be answered even if this is on.
3126 (Default: 1)
3127
3129 The following options are used to configure a hidden service. Some
3130 options apply per service and some apply for the whole tor instance.
3131 The next section describes the per service options that can only be set
3133 after the HiddenServiceDir directive
3134 PER SERVICE OPTIONS:
3136 HiddenServiceDir DIRECTORY
3138 Store data files for a hidden service in DIRECTORY. Every hidden
3139 service must have a separate directory. You may use this option
3140 multiple times to specify multiple services. If DIRECTORY does not
3141 exist, Tor will create it. Please note that you cannot add new
3142 Onion Service to already running Tor instance if Sandbox is
3143 enabled. (Note: in current versions of Tor, if DIRECTORY is a
3144 relative path, it will be relative to the current working directory
3145 of Tor instance, not to its DataDirectory. Do not rely on this
3146 behavior; it is not guaranteed to remain the same in future
3147 versions.)
3148 HiddenServicePort VIRTPORT [TARGET]
3150 Configure a virtual port VIRTPORT for a hidden service. You may use
3151 this option multiple times; each time applies to the service using
3152 the most recent HiddenServiceDir. By default, this option maps the
3153 virtual port to the same port on 127.0.0.1 over TCP. You may
3154 override the target port, address, or both by specifying a target
3155 of addr, port, addr:port, or unix:path. (You can specify an IPv6
3156 target as [addr]:port. Unix paths may be quoted, and may use
3157 standard C escapes.) You may also have multiple lines with the same
3158 VIRTPORT: when a user connects to that VIRTPORT, one of the TARGETs
3159 from those lines will be chosen at random. Note that address-port
3160 pairs have to be comma-separated.
3161 HiddenServiceVersion 2|3
3163 A list of rendezvous service descriptor versions to publish for the
3164 hidden service. Currently, versions 2 and 3 are supported.
3165 (Default: 3)
3166 HiddenServiceAuthorizeClient auth-type client-name,client-name,...
3168 If configured, the v2 hidden service is accessible for authorized
3169 clients only. The auth-type can either be 'basic' for a
3170 general-purpose authorization protocol or 'stealth' for a less
3171 scalable protocol that also hides service activity from
3172 unauthorized clients. Only clients that are listed here are
3173 authorized to access the hidden service. Valid client names are 1
3174 to 16 characters long and only use characters in A-Za-z0-9+-_ (no
3175 spaces). If this option is set, the hidden service is not
3176 accessible for clients without authorization any more. Generated
3177 authorization data can be found in the hostname file. Clients need
3178 to put this authorization data in their configuration file using
3179 HidServAuth. This option is only for v2 services; v3 services
3180 configure client authentication in a subdirectory of
3181 HiddenServiceDir instead (see the Client Authorization section).
3182 HiddenServiceAllowUnknownPorts 0|1
3184 If set to 1, then connections to unrecognized ports do not cause
3185 the current hidden service to close rendezvous circuits. (Setting
3186 this to 0 is not an authorization mechanism; it is instead meant to
3187 be a mild inconvenience to port-scanners.) (Default: 0)
3188 HiddenServiceExportCircuitID protocol
3190 The onion service will use the given protocol to expose the global
3191 circuit identifier of each inbound client circuit. The only
3192 protocol supported right now 'haproxy'. This option is only for v3
3193 services. (Default: none)
3194 The haproxy option works in the following way: when the feature is
3197 enabled, the Tor process will write a header line when a client is
3198 connecting to the onion service. The header will look like this:
3199 "PROXY TCP6 fc00:dead:beef:4dad::ffff:ffff ::1 65535 42\r\n"
3202 We encode the "global circuit identifier" as the last 32-bits of
3205 the first IPv6 address. All other values in the header can safely
3206 be ignored. You can compute the global circuit identifier using the
3207 following formula given the IPv6 address
3208 "fc00:dead:beef:4dad::AABB:CCDD":
3209 global_circuit_id = (0xAA << 24) + (0xBB << 16) + (0xCC << 8) +
3212 0xDD;
3213 In the case above, where the last 32-bits are 0xffffffff, the
3216 global circuit identifier would be 4294967295. You can use this
3217 value together with Tor’s control port to terminate particular
3218 circuits using their global circuit identifiers. For more
3219 information about this see control-spec.txt.
3220 The HAProxy version 1 protocol is described in detail at
3223 https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
3224 HiddenServiceMaxStreams N
3226 The maximum number of simultaneous streams (connections) per
3227 rendezvous circuit. The maximum value allowed is 65535. (Setting
3228 this to 0 will allow an unlimited number of simultaneous streams.)
3229 (Default: 0)
3230 HiddenServiceMaxStreamsCloseCircuit 0|1
3232 If set to 1, then exceeding HiddenServiceMaxStreams will cause the
3233 offending rendezvous circuit to be torn down, as opposed to stream
3234 creation requests that exceed the limit being silently ignored.
3235 (Default: 0)
3236 RendPostPeriod N seconds|minutes|hours|days|weeks
3238 Every time the specified period elapses, Tor uploads any rendezvous
3239 service descriptors to the directory servers. This information is
3240 also uploaded whenever it changes. Minimum value allowed is 10
3241 minutes and maximum is 3.5 days. This option is only for v2
3242 services. (Default: 1 hour)
3243 HiddenServiceDirGroupReadable 0|1
3245 If this option is set to 1, allow the filesystem group to read the
3246 hidden service directory and hostname file. If the option is set to
3247 0, only owner is able to read the hidden service directory.
3248 (Default: 0) Has no effect on Windows.
3249 HiddenServiceNumIntroductionPoints NUM
3251 Number of introduction points the hidden service will have. You
3252 can’t have more than 10 for v2 service and 20 for v3. (Default: 3)
3253 HiddenServiceEnableIntroDoSDefense 0|1
3255 Enable DoS defense at the intropoint level. When this is enabled,
3256 the rate and burst parameter (see below) will be sent to the intro
3257 point which will then use them to apply rate limiting for
3258 introduction request to this service.
3259 The introduction point honors the consensus parameters except if
3261 this is specifically set by the service operator using this option.
3262 The service never looks at the consensus parameters in order to
3263 enable or disable this defense. (Default: 0)
3264 HiddenServiceEnableIntroDoSRatePerSec NUM
3266 The allowed client introduction rate per second at the introduction
3267 point. If this option is 0, it is considered infinite and thus if
3268 HiddenServiceEnableIntroDoSDefense is set, it then effectively
3269 disables the defenses. (Default: 25)
3270 HiddenServiceEnableIntroDoSBurstPerSec NUM
3272 The allowed client introduction burst per second at the
3273 introduction point. If this option is 0, it is considered infinite
3274 and thus if HiddenServiceEnableIntroDoSDefense is set, it then
3275 effectively disables the defenses. (Default: 200)
3276 PER INSTANCE OPTIONS:
3278 PublishHidServDescriptors 0|1
3280 If set to 0, Tor will run any hidden services you configure, but it
3281 won’t advertise them to the rendezvous directory. This option is
3282 only useful if you’re using a Tor controller that handles hidserv
3283 publishing for you. (Default: 1)
3284 HiddenServiceSingleHopMode 0|1
3286 Experimental - Non Anonymous Hidden Services on a tor instance in
3287 HiddenServiceSingleHopMode make one-hop (direct) circuits between
3288 the onion service server, and the introduction and rendezvous
3289 points. (Onion service descriptors are still posted using 3-hop
3290 paths, to avoid onion service directories blocking the service.)
3291 This option makes every hidden service instance hosted by a tor
3292 instance a Single Onion Service. One-hop circuits make Single Onion
3293 servers easily locatable, but clients remain location-anonymous.
3294 However, the fact that a client is accessing a Single Onion rather
3295 than a Hidden Service may be statistically distinguishable.
3296 WARNING: Once a hidden service directory has been used by a tor
3299 instance in HiddenServiceSingleHopMode, it can NEVER be used again
3300 for a hidden service. It is best practice to create a new hidden
3301 service directory, key, and address for each new Single Onion
3302 Service and Hidden Service. It is not possible to run Single Onion
3303 Services and Hidden Services from the same tor instance: they
3304 should be run on different servers with different IP addresses.
3305 HiddenServiceSingleHopMode requires HiddenServiceNonAnonymousMode
3308 to be set to 1. Since a Single Onion service is non-anonymous, you
3309 can not configure a SOCKSPort on a tor instance that is running in
3310 HiddenServiceSingleHopMode. Can not be changed while tor is
3311 running. (Default: 0)
3312 HiddenServiceNonAnonymousMode 0|1
3314 Makes hidden services non-anonymous on this tor instance. Allows
3315 the non-anonymous HiddenServiceSingleHopMode. Enables direct
3316 connections in the server-side hidden service protocol. If you are
3317 using this option, you need to disable all client-side services on
3318 your Tor instance, including setting SOCKSPort to "0". Can not be
3319 changed while tor is running. (Default: 0)
3320
3322 (Version 3 only)
3323 Service side:
3325 To configure client authorization on the service side, the
3327 "<HiddenServiceDir>/authorized_clients/" directory needs to exist. Each file
3328 in that directory should be suffixed with ".auth" (i.e. "alice.auth"; the
3329 file name is irrelevant) and its content format MUST be:
3330 <auth-type>:<key-type>:<base32-encoded-public-key>
3332 The supported <auth-type> are: "descriptor". The supported <key-type> are:
3334 "x25519". The <base32-encoded-public-key> is the base32 representation of
3335 the raw key bytes only (32 bytes for x25519).
3336 Each file MUST contain one line only. Any malformed file will be
3338 ignored. Client authorization will only be enabled for the service if tor
3339 successfully loads at least one authorization file.
3340 Note that once you've configured client authorization, anyone else with the
3342 address won't be able to access it from this point on. If no authorization is
3343 configured, the service will be accessible to anyone with the onion address.
3344 Revoking a client can be done by removing their ".auth" file, however the
3346 revocation will be in effect only after the tor process gets restarted even if
3347 a SIGHUP takes place.
3348 Client side:
3350 To access a v3 onion service with client authorization as a client, make sure
3352 you have ClientOnionAuthDir set in your torrc. Then, in the
3353 <ClientOnionAuthDir> directory, create an .auth_private file for the onion
3354 service corresponding to this key (i.e. 'bob_onion.auth_private'). The
3355 contents of the <ClientOnionAuthDir>/<user>.auth_private file should look like:
3356 <56-char-onion-addr-without-.onion-part>:descriptor:x25519:<x25519 private key in base32>
3358 For more information, please see
3360 https://2019.www.torproject.org/docs/tor-onion-service.html.en#ClientAuthorization
3361 .
3362
3364 The following options are used for running a testing Tor network.
3365 TestingTorNetwork 0|1
3367 If set to 1, Tor adjusts default values of the configuration
3368 options below, so that it is easier to set up a testing Tor
3369 network. May only be set if non-default set of DirAuthorities is
3370 set. Cannot be unset while Tor is running. (Default: 0)
3371 ServerDNSAllowBrokenConfig 1
3374 DirAllowPrivateAddresses 1
3375 EnforceDistinctSubnets 0
3376 AssumeReachable 1
3377 AuthDirMaxServersPerAddr 0
3378 AuthDirMaxServersPerAuthAddr 0
3379 ClientBootstrapConsensusAuthorityDownloadInitialDelay 0
3380 ClientBootstrapConsensusFallbackDownloadInitialDelay 0
3381 ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay 0
3382 ClientDNSRejectInternalAddresses 0
3383 ClientRejectInternalAddresses 0
3384 CountPrivateBandwidth 1
3385 ExitPolicyRejectPrivate 0
3386 ExtendAllowPrivateAddresses 1
3387 V3AuthVotingInterval 5 minutes
3388 V3AuthVoteDelay 20 seconds
3389 V3AuthDistDelay 20 seconds
3390 MinUptimeHidServDirectoryV2 0 seconds
3391 TestingV3AuthInitialVotingInterval 5 minutes
3392 TestingV3AuthInitialVoteDelay 20 seconds
3393 TestingV3AuthInitialDistDelay 20 seconds
3394 TestingAuthDirTimeToLearnReachability 0 minutes
3395 TestingEstimatedDescriptorPropagationTime 0 minutes
3396 TestingServerDownloadInitialDelay 0
3397 TestingClientDownloadInitialDelay 0
3398 TestingServerConsensusDownloadInitialDelay 0
3399 TestingClientConsensusDownloadInitialDelay 0
3400 TestingBridgeDownloadInitialDelay 10
3401 TestingBridgeBootstrapDownloadInitialDelay 0
3402 TestingClientMaxIntervalWithoutRequest 5 seconds
3403 TestingDirConnectionMaxStall 30 seconds
3404 TestingEnableConnBwEvent 1
3405 TestingEnableCellStatsEvent 1
3406 TestingV3AuthInitialVotingInterval N minutes|hours
3408 Like V3AuthVotingInterval, but for initial voting interval before
3409 the first consensus has been created. Changing this requires that
3410 TestingTorNetwork is set. (Default: 30 minutes)
3411 TestingV3AuthInitialVoteDelay N minutes|hours
3413 Like V3AuthVoteDelay, but for initial voting interval before the
3414 first consensus has been created. Changing this requires that
3415 TestingTorNetwork is set. (Default: 5 minutes)
3416 TestingV3AuthInitialDistDelay N minutes|hours
3418 Like V3AuthDistDelay, but for initial voting interval before the
3419 first consensus has been created. Changing this requires that
3420 TestingTorNetwork is set. (Default: 5 minutes)
3421 TestingV3AuthVotingStartOffset N seconds|minutes|hours
3423 Directory authorities offset voting start time by this much.
3424 Changing this requires that TestingTorNetwork is set. (Default: 0)
3425 TestingAuthDirTimeToLearnReachability N minutes|hours
3427 After starting as an authority, do not make claims about whether
3428 routers are Running until this much time has passed. Changing this
3429 requires that TestingTorNetwork is set. (Default: 30 minutes)
3430 TestingEstimatedDescriptorPropagationTime N minutes|hours
3432 Clients try downloading server descriptors from directory caches
3433 after this time. Changing this requires that TestingTorNetwork is
3434 set. (Default: 10 minutes)
3435 TestingMinFastFlagThreshold N
3437 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3438 Minimum value for the Fast flag. Overrides the ordinary minimum
3439 taken from the consensus when TestingTorNetwork is set. (Default:
3440 0.)
3441 TestingServerDownloadInitialDelay N
3443 Initial delay in seconds for when servers should download things in
3444 general. Changing this requires that TestingTorNetwork is set.
3445 (Default: 0)
3446 TestingClientDownloadInitialDelay N
3448 Initial delay in seconds for when clients should download things in
3449 general. Changing this requires that TestingTorNetwork is set.
3450 (Default: 0)
3451 TestingServerConsensusDownloadInitialDelay N
3453 Initial delay in seconds for when servers should download
3454 consensuses. Changing this requires that TestingTorNetwork is set.
3455 (Default: 0)
3456 TestingClientConsensusDownloadInitialDelay N
3458 Initial delay in seconds for when clients should download
3459 consensuses. Changing this requires that TestingTorNetwork is set.
3460 (Default: 0)
3461 TestingBridgeDownloadInitialDelay N
3463 Initial delay in seconds for when clients should download each
3464 bridge descriptor when they know that one or more of their
3465 configured bridges are running. Changing this requires that
3466 TestingTorNetwork is set. (Default: 10800)
3467 TestingBridgeBootstrapDownloadInitialDelay N
3469 Initial delay in seconds for when clients should download each
3470 bridge descriptor when they have just started, or when they can not
3471 contact any of their bridges. Changing this requires that
3472 TestingTorNetwork is set. (Default: 0)
3473 TestingClientMaxIntervalWithoutRequest N seconds|minutes
3475 When directory clients have only a few descriptors to request, they
3476 batch them until they have more, or until this amount of time has
3477 passed. Changing this requires that TestingTorNetwork is set.
3478 (Default: 10 minutes)
3479 TestingDirConnectionMaxStall N seconds|minutes
3481 Let a directory connection stall this long before expiring it.
3482 Changing this requires that TestingTorNetwork is set. (Default: 5
3483 minutes)
3484 TestingDirAuthVoteExit node,node,...
3486 A list of identity fingerprints, country codes, and address
3487 patterns of nodes to vote Exit for regardless of their uptime,
3488 bandwidth, or exit policy. See the ExcludeNodes option for more
3489 information on how to specify nodes.
3490 In order for this option to have any effect, TestingTorNetwork has
3493 to be set. See the ExcludeNodes option for more information on how
3494 to specify nodes.
3495 TestingDirAuthVoteExitIsStrict 0|1
3497 If True (1), a node will never receive the Exit flag unless it is
3498 specified in the TestingDirAuthVoteExit list, regardless of its
3499 uptime, bandwidth, or exit policy.
3500 In order for this option to have any effect, TestingTorNetwork has
3503 to be set.
3504 TestingDirAuthVoteGuard node,node,...
3506 A list of identity fingerprints and country codes and address
3507 patterns of nodes to vote Guard for regardless of their uptime and
3508 bandwidth. See the ExcludeNodes option for more information on how
3509 to specify nodes.
3510 In order for this option to have any effect, TestingTorNetwork has
3513 to be set.
3514 TestingDirAuthVoteGuardIsStrict 0|1
3516 If True (1), a node will never receive the Guard flag unless it is
3517 specified in the TestingDirAuthVoteGuard list, regardless of its
3518 uptime and bandwidth.
3519 In order for this option to have any effect, TestingTorNetwork has
3522 to be set.
3523 TestingDirAuthVoteHSDir node,node,...
3525 A list of identity fingerprints and country codes and address
3526 patterns of nodes to vote HSDir for regardless of their uptime and
3527 DirPort. See the ExcludeNodes option for more information on how to
3528 specify nodes.
3529 In order for this option to have any effect, TestingTorNetwork must
3532 be set.
3533 TestingDirAuthVoteHSDirIsStrict 0|1
3535 If True (1), a node will never receive the HSDir flag unless it is
3536 specified in the TestingDirAuthVoteHSDir list, regardless of its
3537 uptime and DirPort.
3538 In order for this option to have any effect, TestingTorNetwork has
3541 to be set.
3542 TestingEnableConnBwEvent 0|1
3544 If this option is set, then Tor controllers may register for
3545 CONN_BW events. Changing this requires that TestingTorNetwork is
3546 set. (Default: 0)
3547 TestingEnableCellStatsEvent 0|1
3549 If this option is set, then Tor controllers may register for
3550 CELL_STATS events. Changing this requires that TestingTorNetwork is
3551 set. (Default: 0)
3552 TestingMinExitFlagThreshold N
3554 KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3555 Sets a lower-bound for assigning an exit flag when running as an
3556 authority on a testing network. Overrides the usual default lower
3557 bound of 4 KB. (Default: 0)
3558 TestingLinkCertLifetime N seconds|minutes|hours|days|weeks|months
3560 Overrides the default lifetime for the certificates used to
3561 authenticate our X509 link cert with our ed25519 signing key.
3562 (Default: 2 days)
3563 TestingAuthKeyLifetime N seconds|minutes|hours|days|weeks|months
3565 Overrides the default lifetime for a signing Ed25519 TLS Link
3566 authentication key. (Default: 2 days)
3567 TestingLinkKeySlop N seconds|minutes|hours
3569 TestingAuthKeySlop N seconds|minutes|hours
3571 TestingSigningKeySlop N seconds|minutes|hours
3573 How early before the official expiration of a an Ed25519 signing
3574 key do we replace it and issue a new key? (Default: 3 hours for
3575 link and auth; 1 day for signing.)
3576
3578 These options are not saved to the torrc file by the "SAVECONF"
3579 controller command. Other options of this type are documented in
3580 control-spec.txt, section 5.4. End-users should mostly ignore them.
3581 __ControlPort, __DirPort, __DNSPort, __ExtORPort, __NATDPort, __ORPort,
3583 __SocksPort, \_\_TransPort
3584 These underscore-prefixed options are variants of the regular Port
3585 options. They behave the same, except they are not saved to the
3586 torrc file by the controller’s SAVECONF command.
3587
3589 Tor catches the following signals:
3590 SIGTERM
3592 Tor will catch this, clean up and sync to disk if necessary, and
3593 exit.
3594 SIGINT
3596 Tor clients behave as with SIGTERM; but Tor servers will do a
3597 controlled slow shutdown, closing listeners and waiting 30 seconds
3598 before exiting. (The delay can be configured with the
3599 ShutdownWaitLength config option.)
3600 SIGHUP
3602 The signal instructs Tor to reload its configuration (including
3603 closing and reopening logs), and kill and restart its helper
3604 processes if applicable.
3605 SIGUSR1
3607 Log statistics about current connections, past connections, and
3608 throughput.
3609 SIGUSR2
3611 Switch all logs to loglevel debug. You can go back to the old
3612 loglevels by sending a SIGHUP.
3613 SIGCHLD
3615 Tor receives this signal when one of its helper processes has
3616 exited, so it can clean up.
3617 SIGPIPE
3619 Tor catches this signal and ignores it.
3620 SIGXFSZ
3622 If this signal exists on your platform, Tor catches and ignores it.
3623
3625 /etc/tor/torrc
3626 The configuration file, which contains "option value" pairs.
3627 $HOME/.torrc
3629 Fallback location for torrc, if /etc/tor/torrc is not found.
3630 /var/lib/tor/
3632 The tor process stores keys and other data here.
3633 CacheDirectory/cached-certs
3635 This file holds downloaded directory key certificates that are used
3636 to verify authenticity of documents generated by Tor directory
3637 authorities.
3638 CacheDirectory/cached-consensus and/or cached-microdesc-consensus
3640 The most recent consensus network status document we’ve downloaded.
3641 CacheDirectory/cached-descriptors and cached-descriptors.new
3643 These files hold downloaded router statuses. Some routers may
3644 appear more than once; if so, the most recently published
3645 descriptor is used. Lines beginning with @-signs are annotations
3646 that contain more information about a given router. The ".new" file
3647 is an append-only journal; when it gets too large, all entries are
3648 merged into a new cached-descriptors file.
3649 CacheDirectory/cached-extrainfo and cached-extrainfo.new
3651 As "cached-descriptors", but holds optionally-downloaded
3652 "extra-info" documents. Relays use these documents to send
3653 inessential information about statistics, bandwidth history, and
3654 network health to the authorities. They aren’t fetched by default;
3655 see the DownloadExtraInfo option for more info.
3656 CacheDirectory/cached-microdescs and cached-microdescs.new
3658 These files hold downloaded microdescriptors. Lines beginning with
3659 @-signs are annotations that contain more information about a given
3660 router. The ".new" file is an append-only journal; when it gets too
3661 large, all entries are merged into a new cached-microdescs file.
3662 DataDirectory/state
3664 A set of persistent key-value mappings. These are documented in the
3665 file. These include:
3666 · The current entry guards and their status.
3668 · The current bandwidth accounting values.
3670 · When the file was last written
3672 · What version of Tor generated the state file
3674 · A short history of bandwidth usage, as produced in the server
3676 descriptors.
3677 DataDirectory/sr-state
3679 Authority only. State file used to record information about the
3680 current status of the shared-random-value voting state.
3681 CacheDirectory/diff-cache
3683 Directory cache only. Holds older consensuses, and diffs from older
3684 consensuses to the most recent consensus of each type, compressed
3685 in various ways. Each file contains a set of key-value arguments
3686 describing its contents, followed by a single NUL byte, followed by
3687 the main file contents.
3688 DataDirectory/bw_accounting
3690 Used to track bandwidth accounting values (when the current period
3691 starts and ends; how much has been read and written so far this
3692 period). This file is obsolete, and the data is now stored in the
3693 'state' file instead.
3694 DataDirectory/control_auth_cookie
3696 Used for cookie authentication with the controller. Location can be
3697 overridden by the CookieAuthFile config option. Regenerated on
3698 startup. See control-spec.txt in torspec for details. Only used
3699 when cookie authentication is enabled.
3700 DataDirectory/lock
3702 This file is used to prevent two Tor instances from using same data
3703 directory. If access to this file is locked, data directory is
3704 already in use by Tor.
3705 DataDirectory/key-pinning-journal
3707 Used by authorities. A line-based file that records mappings
3708 between RSA1024 identity keys and Ed25519 identity keys.
3709 Authorities enforce these mappings, so that once a relay has picked
3710 an Ed25519 key, stealing or factoring the RSA1024 key will no
3711 longer let an attacker impersonate the relay.
3712 KeyDirectory/authority_identity_key
3714 A v3 directory authority’s master identity key, used to
3715 authenticate its signing key. Tor doesn’t use this while it’s
3716 running. The tor-gencert program uses this. If you’re running an
3717 authority, you should keep this key offline, and not actually put
3718 it here.
3719 KeyDirectory/authority_certificate
3721 A v3 directory authority’s certificate, which authenticates the
3722 authority’s current vote- and consensus-signing key using its
3723 master identity key. Only directory authorities use this file.
3724 KeyDirectory/authority_signing_key
3726 A v3 directory authority’s signing key, used to sign votes and
3727 consensuses. Only directory authorities use this file. Corresponds
3728 to the authority_certificate cert.
3729 KeyDirectory/legacy_certificate
3731 As authority_certificate: used only when V3AuthUseLegacyKey is set.
3732 See documentation for V3AuthUseLegacyKey.
3733 KeyDirectory/legacy_signing_key
3735 As authority_signing_key: used only when V3AuthUseLegacyKey is set.
3736 See documentation for V3AuthUseLegacyKey.
3737 KeyDirectory/secret_id_key
3739 A relay’s RSA1024 permanent identity key, including private and
3740 public components. Used to sign router descriptors, and to sign
3741 other keys.
3742 KeyDirectory/ed25519_master_id_public_key
3744 The public part of a relay’s Ed25519 permanent identity key.
3745 KeyDirectory/ed25519_master_id_secret_key
3747 The private part of a relay’s Ed25519 permanent identity key. This
3748 key is used to sign the medium-term ed25519 signing key. This file
3749 can be kept offline, or kept encrypted. If so, Tor will not be able
3750 to generate new signing keys itself; you’ll need to use tor
3751 --keygen yourself to do so.
3752 KeyDirectory/ed25519_signing_secret_key
3754 The private and public components of a relay’s medium-term Ed25519
3755 signing key. This key is authenticated by the Ed25519 master key,
3756 in turn authenticates other keys (and router descriptors).
3757 KeyDirectory/ed25519_signing_cert
3759 The certificate which authenticates "ed25519_signing_secret_key" as
3760 having been signed by the Ed25519 master key.
3761 KeyDirectory/secret_onion_key and secret_onion_key.old
3763 A relay’s RSA1024 short-term onion key. Used to decrypt old-style
3764 ("TAP") circuit extension requests. The ".old" file holds the
3765 previously generated key, which the relay uses to handle any
3766 requests that were made by clients that didn’t have the new one.
3767 KeyDirectory/secret_onion_key_ntor and secret_onion_key_ntor.old
3769 A relay’s Curve25519 short-term onion key. Used to handle modern
3770 ("ntor") circuit extension requests. The ".old" file holds the
3771 previously generated key, which the relay uses to handle any
3772 requests that were made by clients that didn’t have the new one.
3773 DataDirectory/fingerprint
3775 Only used by servers. Holds the fingerprint of the server’s
3776 identity key.
3777 DataDirectory/hashed-fingerprint
3779 Only used by bridges. Holds the hashed fingerprint of the bridge’s
3780 identity key. (That is, the hash of the hash of the identity key.)
3781 DataDirectory/approved-routers
3783 Only used by authoritative directory servers. This file lists the
3784 status of routers by their identity fingerprint. Each line lists a
3785 status and a fingerprint separated by whitespace. See your
3786 fingerprint file in the DataDirectory for an example line. If the
3787 status is !reject then descriptors from the given identity
3788 (fingerprint) are rejected by this server. If it is !invalid then
3789 descriptors are accepted but marked in the directory as not valid,
3790 that is, not recommended.
3791 DataDirectory/v3-status-votes
3793 Only for v3 authoritative directory servers. This file contains
3794 status votes from all the authoritative directory servers.
3795 CacheDirectory/unverified-consensus
3797 This file contains a network consensus document that has been
3798 downloaded, but which we didn’t have the right certificates to
3799 check yet.
3800 CacheDirectory/unverified-microdesc-consensus
3802 This file contains a microdescriptor-flavored network consensus
3803 document that has been downloaded, but which we didn’t have the
3804 right certificates to check yet.
3805 DataDirectory/unparseable-desc
3807 Onion server descriptors that Tor was unable to parse are dumped to
3808 this file. Only used for debugging.
3809 DataDirectory/router-stability
3811 Only used by authoritative directory servers. Tracks measurements
3812 for router mean-time-between-failures so that authorities have a
3813 good idea of how to set their Stable flags.
3814 DataDirectory/stats/dirreq-stats
3816 Only used by directory caches and authorities. This file is used to
3817 collect directory request statistics.
3818 DataDirectory/stats/entry-stats
3820 Only used by servers. This file is used to collect incoming
3821 connection statistics by Tor entry nodes.
3822 DataDirectory/stats/bridge-stats
3824 Only used by servers. This file is used to collect incoming
3825 connection statistics by Tor bridges.
3826 DataDirectory/stats/exit-stats
3828 Only used by servers. This file is used to collect outgoing
3829 connection statistics by Tor exit routers.
3830 DataDirectory/stats/buffer-stats
3832 Only used by servers. This file is used to collect buffer usage
3833 history.
3834 DataDirectory/stats/conn-stats
3836 Only used by servers. This file is used to collect approximate
3837 connection history (number of active connections over time).
3838 DataDirectory/stats/hidserv-stats
3840 Only used by servers. This file is used to collect approximate
3841 counts of what fraction of the traffic is hidden service rendezvous
3842 traffic, and approximately how many hidden services the relay has
3843 seen.
3844 DataDirectory/networkstatus-bridges
3846 Only used by authoritative bridge directories. Contains information
3847 about bridges that have self-reported themselves to the bridge
3848 authority.
3849 DataDirectory/approved-routers
3851 Authorities only. This file is used to configure which relays are
3852 known to be valid, invalid, and so forth.
3853 HiddenServiceDirectory/hostname
3855 The <base32-encoded-fingerprint>.onion domain name for this hidden
3856 service. If the hidden service is restricted to authorized clients
3857 only, this file also contains authorization data for all clients.
3858 Note that clients will ignore any extra subdomains prepended to a
3860 hidden service hostname. So if you have "xyz.onion" as your
3861 hostname, you can tell clients to connect to "www.xyz.onion" or
3862 "irc.xyz.onion" for virtual-hosting purposes.
3863 HiddenServiceDirectory/private_key
3865 The private key for this hidden service.
3866 HiddenServiceDirectory/client_keys
3868 Authorization data for a hidden service that is only accessible by
3869 authorized clients.
3870 HiddenServiceDirectory/onion_service_non_anonymous
3872 This file is present if a hidden service key was created in
3873 HiddenServiceNonAnonymousMode.
3874
3876 torsocks(1), torify(1)
3877 https://www.torproject.org/
3879 torspec: https://spec.torproject.org
3881
3883 Plenty, probably. Tor is still in development. Please report them at
3884 https://trac.torproject.org/.
3885
3887 Roger Dingledine [arma at mit.edu], Nick Mathewson [nickm at
3888 alum.mit.edu].
3889Tor 03/17/2020 TOR(1)