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. Each node in a virtual circuit
15 knows its predecessor and successor nodes, but no other nodes. Traffic
16 flowing down the circuit is unwrapped by a symmetric key at each node,
17 which reveals the downstream node.
18 Basically, Tor provides a distributed network of servers or relays
20 ("onion routers"). Users bounce their TCP streams, including web
21 traffic, ftp, ssh, etc., around the network, so that recipients,
22 observers, and even the relays themselves have difficulty tracking the
23 source of the stream.
24 Note
26 By default, tor acts as a client only. To help the network by
27 providing bandwidth as a relay, change the ORPort configuration
28 option as mentioned below. Please also consult the documentation on
29 the Tor Project’s website.
30
32 Tor has a powerful command-line interface. This section lists optional
33 arguments you can specify at the command line using the tor command.
34 Configuration options can be specified on the command line in the
36 format --OptionName OptionValue, on the command line in the format
37 OptionName OptionValue, or in a configuration file. For instance, you
38 can tell Tor to start listening for SOCKS connections on port 9999 by
39 passing either --SocksPort 9999 or SocksPort 9999 on the command line,
40 or by specifying SocksPort 9999 in the configuration file. On the
41 command line, quote option values that contain spaces. For instance, if
42 you want Tor to log all debugging messages to debug.log, you must
43 specify --Log "debug file debug.log".
44 Note
46 Configuration options on the command line override those in
47 configuration files. See THE CONFIGURATION FILE FORMAT for more
48 information.
49 The following options in this section are only recognized on the tor
51 command line, not in a configuration file.
52 -h, --help
54 Display a short help message and exit.
55 -f, --torrc-file FILE
57 Specify a new configuration file to contain further Tor
58 configuration options, or pass - to make Tor read its configuration
59 from standard input. (Default: /etc/tor/torrc, or $HOME/.torrc if
60 that file is not found.)
61 --allow-missing-torrc
63 Allow the configuration file specified by -f to be missing, if the
64 defaults-torrc file (see below) is accessible.
65 --defaults-torrc FILE
67 Specify a file in which to find default values for Tor options. The
68 contents of this file are overridden by those in the regular
69 configuration file, and by those on the command line. (Default:
70 /etc/tor/torrc-defaults.)
71 --ignore-missing-torrc
73 Specify that Tor should treat a missing torrc file as though it
74 were empty. Ordinarily, Tor does this for missing default torrc
75 files, but not for those specified on the command line.
76 --hash-password PASSWORD
78 Generate a hashed password for control port access.
79 --list-fingerprint [key type]
81 Generate your keys and output your nickname and fingerprint.
82 Optionally, you can specify the key type as rsa (default) or
83 ed25519.
84 --verify-config
86 Verify whether the configuration file is valid.
87 --dump-config short|full
89 Write a list of Tor’s configured options to standard output. When
90 the short flag is selected, only write the options that are
91 different from their default values. When full is selected, write
92 every option.
93 --service install [--options command-line options]
95 Install an instance of Tor as a Windows service, with the provided
96 command-line options. Current instructions can be found at
97 https://www.torproject.org/docs/faq#NTService
98 --service remove|start|stop
100 Remove, start, or stop a configured Tor Windows service.
101 --nt-service
103 Used internally to implement a Windows service.
104 --list-torrc-options
106 List all valid options.
107 --list-deprecated-options
109 List all valid options that are scheduled to become obsolete in a
110 future version. (This is a warning, not a promise.)
111 --list-modules
113 List whether each optional module has been compiled into Tor. (Any
114 module not listed is not optional in this version of Tor.)
115 --version
117 Display Tor version and exit. The output is a single line of the
118 format "Tor version [version number]." (The version number format
119 is as specified in version-spec.txt.)
120 --quiet|--hush
122 Override the default console logging behavior. By default, Tor
123 starts out logging messages at level "notice" and higher to the
124 console. It stops doing so after it parses its configuration, if
125 the configuration tells it to log anywhere else. These options
126 override the default console logging behavior. Use the --hush
127 option if you want Tor to log only warnings and errors to the
128 console, or use the --quiet option if you want Tor not to log to
129 the console at all.
130 --keygen [--newpass]
132 Running tor --keygen creates a new ed25519 master identity key for
133 a relay, or only a fresh temporary signing key and certificate, if
134 you already have a master key. Optionally, you can encrypt the
135 master identity key with a passphrase. When Tor asks you for a
136 passphrase and you don’t want to encrypt the master key, just don’t
137 enter any passphrase when asked.
138 Use the --newpass option with --keygen only when you need to add,
141 change, or remove a passphrase on an existing ed25519 master
142 identity key. You will be prompted for the old passphrase (if any),
143 and the new passphrase (if any).
144 Note
146 When generating a master key, you may want to use
147 --DataDirectory to control where the keys and certificates will
148 be stored, and --SigningKeyLifetime to control their lifetimes.
149 See SERVER OPTIONS to learn more about the behavior of these
150 options. You must have write access to the specified
151 DataDirectory.
152 To use the generated files, you must copy them to the
153 DataDirectory/keys directory of your Tor daemon, and make sure that
154 they are owned by the user actually running the Tor daemon on your
155 system.
156 --passphrase-fd FILEDES
158 File descriptor to read the passphrase from. Note that unlike with
159 the tor-gencert program, the entire file contents are read and used
160 as the passphrase, including any trailing newlines. If the file
161 descriptor is not specified, the passphrase is read from the
162 terminal by default.
163 --key-expiration [purpose] [--format iso8601|timestamp]
165 The purpose specifies which type of key certificate to determine
166 the expiration of. The only currently recognised purpose is "sign".
167 Running tor --key-expiration sign will attempt to find your signing
170 key certificate and will output, both in the logs as well as to
171 stdout. The optional --format argument lets you specify the time
172 format. Currently, iso8601 and timestamp are supported. If --format
173 is not specified, the signing key certificate’s expiration time
174 will be in ISO-8601 format. For example, the output sent to stdout
175 will be of the form: "signing-cert-expiry: 2017-07-25 08:30:15
176 UTC". If --format timestamp is specified, the signing key
177 certificate’s expiration time will be in Unix timestamp format. For
178 example, the output sent to stdout will be of the form:
179 "signing-cert-expiry: 1500971415".
180 --dbg-...
182 Tor may support other options beginning with the string "dbg".
183 These are intended for use by developers to debug and test Tor.
184 They are not supported or guaranteed to be stable, and you should
185 probably not use them.
186
188 All configuration options in a configuration are written on a single
189 line by default. They take the form of an option name and a value, or
190 an option name and a quoted value (option value or option "value").
191 Anything after a # character is treated as a comment. Options are
192 case-insensitive. C-style escaped characters are allowed inside quoted
193 values. To split one configuration entry into multiple lines, use a
194 single backslash character (\) before the end of the line. Comments can
195 be used in such multiline entries, but they must start at the beginning
196 of a line.
197 Configuration options can be imported from files or folders using the
199 %include option with the value being a path. This path can have
200 wildcards. Wildcards are expanded first, then sorted using lexical
201 order. Then, for each matching file or folder, the following rules are
202 followed: if the path is a file, the options from the file will be
203 parsed as if they were written where the %include option is. If the
204 path is a folder, all files on that folder will be parsed following
205 lexical order. Files starting with a dot are ignored. Files in
206 subfolders are ignored. The %include option can be used recursively.
207 New configuration files or directories cannot be added to already
208 running Tor instance if Sandbox is enabled.
209 The supported wildcards are * meaning any number of characters
211 including none and ? meaning exactly one character. These characters
212 can be escaped by preceding them with a backslash, except on Windows.
213 Files starting with a dot are not matched when expanding wildcards
214 unless the starting dot is explicitly in the pattern, except on
215 Windows.
216 By default, an option on the command line overrides an option found in
218 the configuration file, and an option in a configuration file overrides
219 one in the defaults file.
220 This rule is simple for options that take a single value, but it can
222 become complicated for options that are allowed to occur more than
223 once: if you specify four SocksPorts in your configuration file, and
224 one more SocksPort on the command line, the option on the command line
225 will replace all of the SocksPorts in the configuration file. If this
226 isn’t what you want, prefix the option name with a plus sign (+), and
227 it will be appended to the previous set of options instead. For
228 example, setting SocksPort 9100 will use only port 9100, but setting
229 +SocksPort 9100 will use ports 9100 and 9050 (because this is the
230 default).
231 Alternatively, you might want to remove every instance of an option in
233 the configuration file, and not replace it at all: you might want to
234 say on the command line that you want no SocksPorts at all. To do that,
235 prefix the option name with a forward slash (/). You can use the plus
236 sign (+) and the forward slash (/) in the configuration file and on the
237 command line.
238
240 AccelDir DIR
241 Specify this option if using dynamic hardware acceleration and the
242 engine implementation library resides somewhere other than the
243 OpenSSL default. Can not be changed while tor is running.
244 AccelName NAME
246 When using OpenSSL hardware crypto acceleration attempt to load the
247 dynamic engine of this name. This must be used for any dynamic
248 hardware engine. Names can be verified with the openssl engine
249 command. Can not be changed while tor is running.
250 If the engine name is prefixed with a "!", then Tor will exit if
253 the engine cannot be loaded.
254 AlternateBridgeAuthority [nickname] [flags] ipv4address:port
256 fingerprint, AlternateDirAuthority [nickname] [flags] ipv4address:port
257 fingerprint
258 These options behave as DirAuthority, but they replace fewer of the
259 default directory authorities. Using AlternateDirAuthority replaces
260 the default Tor directory authorities, but leaves the default
261 bridge authorities in place. Similarly, AlternateBridgeAuthority
262 replaces the default bridge authority, but leaves the directory
263 authorities alone.
264 AvoidDiskWrites 0|1
266 If non-zero, try to write to disk less frequently than we would
267 otherwise. This is useful when running on flash memory or other
268 media that support only a limited number of writes. (Default: 0)
269 BandwidthBurst N
271 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
272 Limit the maximum token bucket size (also known as the burst) to
273 the given number of bytes in each direction. (Default: 1 GByte)
274 BandwidthRate N
276 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
277 A token bucket limits the average incoming bandwidth usage on this
278 node to the specified number of bytes per second, and the average
279 outgoing bandwidth usage to that same value. If you want to run a
280 relay in the public network, this needs to be at the very least 75
281 KBytes for a relay (that is, 600 kbits) or 50 KBytes for a bridge
282 (400 kbits) — but of course, more is better; we recommend at least
283 250 KBytes (2 mbits) if possible. (Default: 1 GByte)
284 Note that this option, and other bandwidth-limiting options, apply
287 to TCP data only: They do not count TCP headers or DNS traffic.
288 Tor uses powers of two, not powers of ten, so 1 GByte is
291 1024*1024*1024 bytes as opposed to 1 billion bytes.
292 With this option, and in other options that take arguments in
295 bytes, KBytes, and so on, other formats are also supported.
296 Notably, "KBytes" can also be written as "kilobytes" or "kb";
297 "MBytes" can be written as "megabytes" or "MB"; "kbits" can be
298 written as "kilobits"; and so forth. Case doesn’t matter. Tor also
299 accepts "byte" and "bit" in the singular. The prefixes "tera" and
300 "T" are also recognized. If no units are given, we default to
301 bytes. To avoid confusion, we recommend writing "bytes" or "bits"
302 explicitly, since it’s easy to forget that "B" means bytes, not
303 bits.
304 CacheDirectory DIR
306 Store cached directory data in DIR. Can not be changed while tor is
307 running. (Default: uses the value of DataDirectory.)
308 CacheDirectoryGroupReadable 0|1|auto
310 If this option is set to 0, don’t allow the filesystem group to
311 read the CacheDirectory. If the option is set to 1, make the
312 CacheDirectory readable by the default GID. If the option is
313 "auto", then we use the setting for DataDirectoryGroupReadable when
314 the CacheDirectory is the same as the DataDirectory, and 0
315 otherwise. (Default: auto)
316 CircuitPriorityHalflife NUM
318 If this value is set, we override the default algorithm for
319 choosing which circuit’s cell to deliver or relay next. It is
320 delivered first to the circuit that has the lowest weighted cell
321 count, where cells are weighted exponentially according to this
322 value (in seconds). If the value is -1, it is taken from the
323 consensus if possible else it will fallback to the default value of
324 30. Minimum: 1, Maximum: 2147483647. This can be defined as a float
325 value. This is an advanced option; you generally shouldn’t have to
326 mess with it. (Default: -1)
327 ClientTransportPlugin transport socks4|socks5 IP:PORT,
329 ClientTransportPlugin transport exec path-to-binary [options]
330 In its first form, when set along with a corresponding Bridge line,
331 the Tor client forwards its traffic to a SOCKS-speaking proxy on
332 "IP:PORT". (IPv4 addresses should written as-is; IPv6 addresses
333 should be wrapped in square brackets.) It’s the duty of that proxy
334 to properly forward the traffic to the bridge.
335 In its second form, when set along with a corresponding Bridge
338 line, the Tor client launches the pluggable transport proxy
339 executable in path-to-binary using options as its command-line
340 options, and forwards its traffic to it. It’s the duty of that
341 proxy to properly forward the traffic to the bridge. (Default:
342 none)
343 ConfluxEnabled 0|1|auto
345 If this option is set to 1, general purpose traffic will use
346 Conflux which is traffic splitting among multiple legs (circuits).
347 Onion services are not supported at the moment. Default value is
348 set to "auto" meaning the consensus is used to decide unless set.
349 (Default: auto)
350 ConfluxClientUX throughput|latency|throughput_lowmem|latency_lowmem
352 This option configures the user experience that the client requests
353 from the exit, for data that the exit sends to the client. The
354 default is "throughput", which maximizes throughput. "Latency" will
355 tell the exit to only use the circuit with lower latency for all
356 data. The lowmem versions minimize queue usage memory at the
357 client. (Default: "throughput")
358 ConnLimit NUM
360 The minimum number of file descriptors that must be available to
361 the Tor process before it will start. Tor will ask the OS for as
362 many file descriptors as the OS will allow (you can find this by
363 "ulimit -H -n"). If this number is less than ConnLimit, then Tor
364 will refuse to start.
365 Tor relays need thousands of sockets, to connect to every other
368 relay. If you are running a private bridge, you can reduce the
369 number of sockets that Tor uses. For example, to limit Tor to 500
370 sockets, run "ulimit -n 500" in a shell. Then start tor in the same
371 shell, with ConnLimit 500. You may also need to set DisableOOSCheck
372 0.
373 Unless you have severely limited sockets, you probably don’t need
376 to adjust ConnLimit itself. It has no effect on Windows, since that
377 platform lacks getrlimit(). (Default: 1000)
378 ConstrainedSockets 0|1
380 If set, Tor will tell the kernel to attempt to shrink the buffers
381 for all sockets to the size specified in ConstrainedSockSize. This
382 is useful for virtual servers and other environments where system
383 level TCP buffers may be limited. If you’re on a virtual server,
384 and you encounter the "Error creating network socket: No buffer
385 space available" message, you are likely experiencing this problem.
386 The preferred solution is to have the admin increase the buffer
389 pool for the host itself via /proc/sys/net/ipv4/tcp_mem or
390 equivalent facility; this configuration option is a second-resort.
391 The DirPort option should also not be used if TCP buffers are
394 scarce. The cached directory requests consume additional sockets
395 which exacerbates the problem.
396 You should not enable this feature unless you encounter the "no
399 buffer space available" issue. Reducing the TCP buffers affects
400 window size for the TCP stream and will reduce throughput in
401 proportion to round trip time on long paths. (Default: 0)
402 ConstrainedSockSize N bytes|KBytes
404 When ConstrainedSockets is enabled the receive and transmit buffers
405 for all sockets will be set to this limit. Must be a value between
406 2048 and 262144, in 1024 byte increments. Default of 8192 is
407 recommended.
408 ControlPort [address:]port|unix:path|auto [flags]
410 If set, Tor will accept connections on this port and allow those
411 connections to control the Tor process using the Tor Control
412 Protocol (described in control-spec.txt in torspec). Note: unless
413 you also specify one or more of HashedControlPassword or
414 CookieAuthentication, setting this option will cause Tor to allow
415 any process on the local host to control it. (Setting both
416 authentication methods means either method is sufficient to
417 authenticate to Tor.) This option is required for many Tor
418 controllers; most use the value of 9051. If a unix domain socket is
419 used, you may quote the path using standard C escape sequences. You
420 can specify this directive multiple times, to bind to multiple
421 address/port pairs. Set it to "auto" to have Tor pick a port for
422 you. (Default: 0)
423 Recognized flags are:
426 GroupWritable
428 Unix domain sockets only: makes the socket get created as
429 group-writable.
430 WorldWritable
432 Unix domain sockets only: makes the socket get created as
433 world-writable.
434 RelaxDirModeCheck
436 Unix domain sockets only: Do not insist that the directory that
437 holds the socket be read-restricted.
438 ControlPortFileGroupReadable 0|1
440 If this option is set to 0, don’t allow the filesystem group to
441 read the control port file. If the option is set to 1, make the
442 control port file readable by the default GID. (Default: 0)
443 ControlPortWriteToFile Path
445 If set, Tor writes the address and port of any control port it
446 opens to this address. Usable by controllers to learn the actual
447 control port when ControlPort is set to "auto".
448 ControlSocket Path
450 Like ControlPort, but listens on a Unix domain socket, rather than
451 a TCP socket. 0 disables ControlSocket. (Unix and Unix-like
452 systems only.) (Default: 0)
453 ControlSocketsGroupWritable 0|1
455 If this option is set to 0, don’t allow the filesystem group to
456 read and write unix sockets (e.g. ControlSocket). If the option is
457 set to 1, make the control socket readable and writable by the
458 default GID. (Default: 0)
459 CookieAuthentication 0|1
461 If this option is set to 1, allow connections on the control port
462 when the connecting process knows the contents of a file named
463 "control_auth_cookie", which Tor will create in its data directory.
464 This authentication method should only be used on systems with good
465 filesystem security. (Default: 0)
466 CookieAuthFile Path
468 If set, this option overrides the default location and file name
469 for Tor’s cookie file. (See CookieAuthentication.)
470 CookieAuthFileGroupReadable 0|1
472 If this option is set to 0, don’t allow the filesystem group to
473 read the cookie file. If the option is set to 1, make the cookie
474 file readable by the default GID. [Making the file readable by
475 other groups is not yet implemented; let us know if you need this
476 for some reason.] (Default: 0)
477 CountPrivateBandwidth 0|1
479 If this option is set, then Tor’s rate-limiting applies not only to
480 remote connections, but also to connections to private addresses
481 like 127.0.0.1 or 10.0.0.1. This is mostly useful for debugging
482 rate-limiting. (Default: 0)
483 DataDirectory DIR
485 Store working data in DIR. Can not be changed while tor is running.
486 (Default: ~/.tor if your home directory is not /; otherwise,
487 /var/lib/tor. On Windows, the default is your ApplicationData
488 folder.)
489 DataDirectoryGroupReadable 0|1
491 If this option is set to 0, don’t allow the filesystem group to
492 read the DataDirectory. If the option is set to 1, make the
493 DataDirectory readable by the default GID. (Default: 0)
494 DirAuthority [nickname] [flags] ipv4address:dirport fingerprint
496 Use a nonstandard authoritative directory server at the provided
497 address and port, with the specified key fingerprint. This option
498 can be repeated many times, for multiple authoritative directory
499 servers. Flags are separated by spaces, and determine what kind of
500 an authority this directory is. By default, an authority is not
501 authoritative for any directory style or version unless an
502 appropriate flag is given.
503 Tor will use this authority as a bridge authoritative directory if
506 the "bridge" flag is set. If a flag "orport=orport" is given, Tor
507 will use the given port when opening encrypted tunnels to the
508 dirserver. If a flag "weight=num" is given, then the directory
509 server is chosen randomly with probability proportional to that
510 weight (default 1.0). If a flag "v3ident=fp" is given, the
511 dirserver is a v3 directory authority whose v3 long-term signing
512 key has the fingerprint fp. Lastly, if an
513 "ipv6=[ipv6address]:orport" flag is present, then the directory
514 authority is listening for IPv6 connections on the indicated IPv6
515 address and OR Port.
516 Tor will contact the authority at ipv4address to download directory
519 documents. Clients always use the ORPort. Relays usually use the
520 DirPort, but will use the ORPort in some circumstances. If an IPv6
521 ORPort is supplied, clients will also download directory documents
522 at the IPv6 ORPort, if they are configured to use IPv6.
523 If no DirAuthority line is given, Tor will use the default
526 directory authorities. NOTE: this option is intended for setting up
527 a private Tor network with its own directory authorities. If you
528 use it, you will be distinguishable from other users, because you
529 won’t believe the same authorities they do.
530 DirAuthorityFallbackRate NUM
532 When configured to use both directory authorities and fallback
533 directories, the directory authorities also work as fallbacks. They
534 are chosen with their regular weights, multiplied by this number,
535 which should be 1.0 or less. The default is less than 1, to reduce
536 load on authorities. (Default: 0.1)
537 DisableAllSwap 0|1
539 If set to 1, Tor will attempt to lock all current and future memory
540 pages, so that memory cannot be paged out. Windows, OS X and
541 Solaris are currently not supported. We believe that this feature
542 works on modern Gnu/Linux distributions, and that it should work on
543 *BSD systems (untested). This option requires that you start your
544 Tor as root, and you should use the User option to properly reduce
545 Tor’s privileges. Can not be changed while tor is running.
546 (Default: 0)
547 DisableDebuggerAttachment 0|1
549 If set to 1, Tor will attempt to prevent basic debugging attachment
550 attempts by other processes. This may also keep Tor from generating
551 core files if it crashes. It has no impact for users who wish to
552 attach if they have CAP_SYS_PTRACE or if they are root. We believe
553 that this feature works on modern Gnu/Linux distributions, and that
554 it may also work on *BSD systems (untested). Some modern Gnu/Linux
555 systems such as Ubuntu have the kernel.yama.ptrace_scope sysctl and
556 by default enable it as an attempt to limit the PTRACE scope for
557 all user processes by default. This feature will attempt to limit
558 the PTRACE scope for Tor specifically - it will not attempt to
559 alter the system wide ptrace scope as it may not even exist. If you
560 wish to attach to Tor with a debugger such as gdb or strace you
561 will want to set this to 0 for the duration of your debugging.
562 Normal users should leave it on. Disabling this option while Tor is
563 running is prohibited. (Default: 1)
564 DisableNetwork 0|1
566 When this option is set, we don’t listen for or accept any
567 connections other than controller connections, and we close (and
568 don’t reattempt) any outbound connections. Controllers sometimes
569 use this option to avoid using the network until Tor is fully
570 configured. Tor will make still certain network-related calls (like
571 DNS lookups) as a part of its configuration process, even if
572 DisableNetwork is set. (Default: 0)
573 ExtendByEd25519ID 0|1|auto
575 If this option is set to 1, we always try to include a relay’s
576 Ed25519 ID when telling the preceding relay in a circuit to extend
577 to it. If this option is set to 0, we never include Ed25519 IDs
578 when extending circuits. If the option is set to "auto", we obey a
579 parameter in the consensus document. (Default: auto)
580 ExtORPort [address:]port|auto
582 Open this port to listen for Extended ORPort connections from your
583 pluggable transports.
584 (Default: DataDirectory/extended_orport_auth_cookie)
586 ExtORPortCookieAuthFile Path
588 If set, this option overrides the default location and file name
589 for the Extended ORPort’s cookie file — the cookie file is needed
590 for pluggable transports to communicate through the Extended
591 ORPort.
592 ExtORPortCookieAuthFileGroupReadable 0|1
594 If this option is set to 0, don’t allow the filesystem group to
595 read the Extended OR Port cookie file. If the option is set to 1,
596 make the cookie file readable by the default GID. [Making the file
597 readable by other groups is not yet implemented; let us know if you
598 need this for some reason.] (Default: 0)
599 FallbackDir ipv4address:dirport orport=orport id=fingerprint
601 [weight=num] [ipv6=[ipv6address]:orport]
602 When tor is unable to connect to any directory cache for directory
603 info (usually because it doesn’t know about any yet) it tries a
604 hard-coded directory. Relays try one directory authority at a time.
605 Clients try multiple directory authorities and FallbackDirs, to
606 avoid hangs on startup if a hard-coded directory is down. Clients
607 wait for a few seconds between each attempt, and retry FallbackDirs
608 more often than directory authorities, to reduce the load on the
609 directory authorities.
610 FallbackDirs should be stable relays with stable IP addresses,
613 ports, and identity keys. They must have a DirPort.
614 By default, the directory authorities are also FallbackDirs.
617 Specifying a FallbackDir replaces Tor’s default hard-coded
618 FallbackDirs (if any). (See DirAuthority for an explanation of each
619 flag.)
620 FetchDirInfoEarly 0|1
622 If set to 1, Tor will always fetch directory information like other
623 directory caches, even if you don’t meet the normal criteria for
624 fetching early. Normal users should leave it off. (Default: 0)
625 FetchDirInfoExtraEarly 0|1
627 If set to 1, Tor will fetch directory information before other
628 directory caches. It will attempt to download directory information
629 closer to the start of the consensus period. Normal users should
630 leave it off. (Default: 0)
631 FetchHidServDescriptors 0|1
633 If set to 0, Tor will never fetch any hidden service descriptors
634 from the rendezvous directories. This option is only useful if
635 you’re using a Tor controller that handles hidden service fetches
636 for you. (Default: 1)
637 FetchServerDescriptors 0|1
639 If set to 0, Tor will never fetch any network status summaries or
640 server descriptors from the directory servers. This option is only
641 useful if you’re using a Tor controller that handles directory
642 fetches for you. (Default: 1)
643 FetchUselessDescriptors 0|1
645 If set to 1, Tor will fetch every consensus flavor, and all server
646 descriptors and authority certificates referenced by those
647 consensuses, except for extra info descriptors. When this option is
648 1, Tor will also keep fetching descriptors, even when idle. If set
649 to 0, Tor will avoid fetching useless descriptors: flavors that it
650 is not using to build circuits, and authority certificates it does
651 not trust. When Tor hasn’t built any application circuits, it will
652 go idle, and stop fetching descriptors. This option is useful if
653 you’re using a tor client with an external parser that uses a full
654 consensus. This option fetches all documents except extrainfo
655 descriptors, DirCache fetches and serves all documents except
656 extrainfo descriptors, DownloadExtraInfo* fetches extrainfo
657 documents, and serves them if DirCache is on, and
658 UseMicrodescriptors changes the flavor of consensuses and
659 descriptors that is fetched and used for building circuits.
660 (Default: 0)
661 HardwareAccel 0|1
663 If non-zero, try to use built-in (static) crypto hardware
664 acceleration when available. Can not be changed while tor is
665 running. (Default: 0)
666 HashedControlPassword hashed_password
668 Allow connections on the control port if they present the password
669 whose one-way hash is hashed_password. You can compute the hash of
670 a password by running "tor --hash-password password". You can
671 provide several acceptable passwords by using more than one
672 HashedControlPassword line.
673 HTTPProxy host[:port]
675 Tor will make all its directory requests through this host:port (or
676 host:80 if port is not specified), rather than connecting directly
677 to any directory servers. (DEPRECATED: As of 0.3.1.0-alpha you
678 should use HTTPSProxy.)
679 HTTPProxyAuthenticator username:password
681 If defined, Tor will use this username:password for Basic HTTP
682 proxy authentication, as in RFC 2617. This is currently the only
683 form of HTTP proxy authentication that Tor supports; feel free to
684 submit a patch if you want it to support others. (DEPRECATED: As of
685 0.3.1.0-alpha you should use HTTPSProxyAuthenticator.)
686 HTTPSProxy host[:port]
688 Tor will make all its OR (SSL) connections through this host:port
689 (or host:443 if port is not specified), via HTTP CONNECT rather
690 than connecting directly to servers. You may want to set
691 FascistFirewall to restrict the set of ports you might try to
692 connect to, if your HTTPS proxy only allows connecting to certain
693 ports.
694 HTTPSProxyAuthenticator username:password
696 If defined, Tor will use this username:password for Basic HTTPS
697 proxy authentication, as in RFC 2617. This is currently the only
698 form of HTTPS proxy authentication that Tor supports; feel free to
699 submit a patch if you want it to support others.
700 KeepalivePeriod NUM
702 To keep firewalls from expiring connections, send a padding
703 keepalive cell every NUM seconds on open connections that are in
704 use. (Default: 5 minutes)
705 KeepBindCapabilities 0|1|auto
707 On Linux, when we are started as root and we switch our identity
708 using the User option, the KeepBindCapabilities option tells us
709 whether to try to retain our ability to bind to low ports. If this
710 value is 1, we try to keep the capability; if it is 0 we do not;
711 and if it is auto, we keep the capability only if we are configured
712 to listen on a low port. Can not be changed while tor is running.
713 (Default: auto.)
714 Log minSeverity[-maxSeverity] stderr|stdout|syslog
716 Send all messages between minSeverity and maxSeverity to the
717 standard output stream, the standard error stream, or to the system
718 log. (The "syslog" value is only supported on Unix.) Recognized
719 severity levels are debug, info, notice, warn, and err. We advise
720 using "notice" in most cases, since anything more verbose may
721 provide sensitive information to an attacker who obtains the logs.
722 If only one severity level is given, all messages of that level or
723 higher will be sent to the listed destination.
724 Some low-level logs may be sent from signal handlers, so their
727 destination logs must be signal-safe. These low-level logs include
728 backtraces, logging function errors, and errors in code called by
729 logging functions. Signal-safe logs are always sent to stderr or
730 stdout. They are also sent to a limited number of log files that
731 are configured to log messages at error severity from the bug or
732 general domains. They are never sent as syslogs, control port log
733 events, or to any API-based log destinations.
734 Log minSeverity[-maxSeverity] file FILENAME
736 As above, but send log messages to the listed filename. The "Log"
737 option may appear more than once in a configuration file. Messages
738 are sent to all the logs that match their severity level.
739 Log [domain,...]minSeverity[-maxSeverity] ... file FILENAME
741 Log [domain,...]minSeverity[-maxSeverity] ... stderr|stdout|syslog
743 As above, but select messages by range of log severity and by a set
744 of "logging domains". Each logging domain corresponds to an area of
745 functionality inside Tor. You can specify any number of severity
746 ranges for a single log statement, each of them prefixed by a
747 comma-separated list of logging domains. You can prefix a domain
748 with ~ to indicate negation, and use * to indicate "all domains".
749 If you specify a severity range without a list of domains, it
750 matches all domains.
751 This is an advanced feature which is most useful for debugging one
754 or two of Tor’s subsystems at a time.
755 The currently recognized domains are: general, crypto, net, config,
758 fs, protocol, mm, http, app, control, circ, rend, bug, dir,
759 dirserv, or, edge, acct, hist, handshake, heartbeat, channel,
760 sched, guard, consdiff, dos, process, pt, btrack, and mesg. Domain
761 names are case-insensitive.
762 For example, "Log [handshake]debug [~net,~mm]info notice stdout"
765 sends to stdout: all handshake messages of any severity, all
766 info-and-higher messages from domains other than networking and
767 memory management, and all messages of severity notice or higher.
768 LogMessageDomains 0|1
770 If 1, Tor includes message domains with each log message. Every log
771 message currently has at least one domain; most currently have
772 exactly one. This doesn’t affect controller log messages. (Default:
773 0)
774 LogTimeGranularity NUM
776 Set the resolution of timestamps in Tor’s logs to NUM milliseconds.
777 NUM must be positive and either a divisor or a multiple of 1
778 second. Note that this option only controls the granularity written
779 by Tor to a file or console log. Tor does not (for example) "batch
780 up" log messages to affect times logged by a controller, times
781 attached to syslog messages, or the mtime fields on log files.
782 (Default: 1 second)
783 MaxAdvertisedBandwidth N
785 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
786 If set, we will not advertise more than this amount of bandwidth
787 for our BandwidthRate. Server operators who want to reduce the
788 number of clients who ask to build circuits through them (since
789 this is proportional to advertised bandwidth rate) can thus reduce
790 the CPU demands on their server without impacting network
791 performance.
792 MaxUnparseableDescSizeToLog N bytes|KBytes|MBytes|GBytes|TBytes
794 Unparseable descriptors (e.g. for votes, consensuses, routers) are
795 logged in separate files by hash, up to the specified size in
796 total. Note that only files logged during the lifetime of this Tor
797 process count toward the total; this is intended to be used to
798 debug problems without opening live servers to resource exhaustion
799 attacks. (Default: 10 MBytes)
800 MetricsPort [address:]port [format]
802 WARNING: Before enabling this, it is important to understand that
803 exposing tor metrics publicly is dangerous to the Tor network
804 users. Please take extra precaution and care when opening this
805 port. Set a very strict access policy with MetricsPortPolicy and
806 consider using your operating systems firewall features for defense
807 in depth.
808 We recommend, for the prometheus format, that the only address that
810 can access this port should be the Prometheus server itself.
811 Remember that the connection is unencrypted (HTTP) hence consider
812 using a tool like stunnel to secure the link from this port to the
813 server.
814 If set, open this port to listen for an HTTP GET request to
816 "/metrics". Upon a request, the collected metrics in the the tor
817 instance are formatted for the given format and then sent back. If
818 this is set, MetricsPortPolicy must be defined else every request
819 will be rejected.
820 Supported format is "prometheus" which is also the default if not
822 set. The Prometheus data model can be found here:
823 https://prometheus.io/docs/concepts/data_model/
824 The tor metrics are constantly collected and they solely consists
826 of counters. Thus, asking for those metrics is very lightweight on
827 the tor process. (Default: None)
828 As an example, here only 5.6.7.8 will be allowed to connect:
830 MetricsPort 1.2.3.4:9035
832 MetricsPortPolicy accept 5.6.7.8
833 MetricsPortPolicy policy,policy,...
835 Set an entrance policy for the MetricsPort, to limit who can access
836 it. The policies have the same form as exit policies below, except
837 that port specifiers are ignored. For multiple entries, this line
838 can be used multiple times. It is a reject all by default policy.
839 (Default: None)
840 Please, keep in mind here that if the server collecting metrics on
842 the MetricsPort is behind a NAT, then everything behind it can
843 access it. This is similar for the case of allowing localhost,
844 every users on the server will be able to access it. Again,
845 strongly consider using a tool like stunnel to secure the link or
846 to strengthen access control.
847 NoExec 0|1
849 If this option is set to 1, then Tor will never launch another
850 executable, regardless of the settings of ClientTransportPlugin or
851 ServerTransportPlugin. Once this option has been set to 1, it
852 cannot be set back to 0 without restarting Tor. (Default: 0)
853 OutboundBindAddress IP
855 Make all outbound connections originate from the IP address
856 specified. This is only useful when you have multiple network
857 interfaces, and you want all of Tor’s outgoing connections to use a
858 single one. This option may be used twice, once with an IPv4
859 address and once with an IPv6 address. IPv6 addresses should be
860 wrapped in square brackets. This setting will be ignored for
861 connections to the loopback addresses (127.0.0.0/8 and ::1), and is
862 not used for DNS requests as well.
863 OutboundBindAddressExit IP
865 Make all outbound exit connections originate from the IP address
866 specified. This option overrides OutboundBindAddress for the same
867 IP version. This option may be used twice, once with an IPv4
868 address and once with an IPv6 address. IPv6 addresses should be
869 wrapped in square brackets. This setting will be ignored for
870 connections to the loopback addresses (127.0.0.0/8 and ::1).
871 OutboundBindAddressOR IP
873 Make all outbound non-exit (relay and other) connections originate
874 from the IP address specified. This option overrides
875 OutboundBindAddress for the same IP version. This option may be
876 used twice, once with an IPv4 address and once with an IPv6
877 address. IPv6 addresses should be wrapped in square brackets. This
878 setting will be ignored for connections to the loopback addresses
879 (127.0.0.0/8 and ::1).
880 __OwningControllerProcess PID
882 Make Tor instance periodically check for presence of a controller
883 process with given PID and terminate itself if this process is no
884 longer alive. Polling interval is 15 seconds.
885 PerConnBWBurst N
887 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
888 If this option is set manually, or via the "perconnbwburst"
889 consensus field, Tor will use it for separate rate limiting for
890 each connection from a non-relay. (Default: 0)
891 PerConnBWRate N
893 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
894 If this option is set manually, or via the "perconnbwrate"
895 consensus field, Tor will use it for separate rate limiting for
896 each connection from a non-relay. (Default: 0)
897 OutboundBindAddressPT IP
899 Request that pluggable transports makes all outbound connections
900 originate from the IP address specified. Because outgoing
901 connections are handled by the pluggable transport itself, it is
902 not possible for Tor to enforce whether the pluggable transport
903 honors this option. This option overrides OutboundBindAddress for
904 the same IP version. This option may be used twice, once with an
905 IPv4 address and once with an IPv6 address. IPv6 addresses should
906 be wrapped in square brackets. This setting will be ignored for
907 connections to the loopback addresses (127.0.0.0/8 and ::1).
908 PidFile FILE
910 On startup, write our PID to FILE. On clean shutdown, remove FILE.
911 Can not be changed while tor is running.
912 ProtocolWarnings 0|1
914 If 1, Tor will log with severity 'warn' various cases of other
915 parties not following the Tor specification. Otherwise, they are
916 logged with severity 'info'. (Default: 0)
917 RelayBandwidthBurst N
919 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
920 If not 0, limit the maximum token bucket size (also known as the
921 burst) for _relayed traffic_ to the given number of bytes in each
922 direction. They do not include directory fetches by the relay (from
923 authority or other relays), because that is considered "client"
924 activity. (Default: 0) RelayBandwidthBurst defaults to the value of
925 RelayBandwidthRate if unset.
926 RelayBandwidthRate N
928 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
929 If not 0, a separate token bucket limits the average incoming
930 bandwidth usage for _relayed traffic_ on this node to the specified
931 number of bytes per second, and the average outgoing bandwidth
932 usage to that same value. Relayed traffic currently is calculated
933 to include answers to directory requests, but that may change in
934 future versions. They do not include directory fetches by the relay
935 (from authority or other relays), because that is considered
936 "client" activity. (Default: 0) RelayBandwidthRate defaults to the
937 value of RelayBandwidthBurst if unset.
938 RephistTrackTime N seconds|minutes|hours|days|weeks
940 Tells an authority, or other node tracking node reliability and
941 history, that fine-grained information about nodes can be discarded
942 when it hasn’t changed for a given amount of time. (Default: 24
943 hours)
944 RunAsDaemon 0|1
946 If 1, Tor forks and daemonizes to the background. This option has
947 no effect on Windows; instead you should use the --service
948 command-line option. Can not be changed while tor is running.
949 (Default: 0)
950 SafeLogging 0|1|relay
952 Tor can scrub potentially sensitive strings from log messages (e.g.
953 addresses) by replacing them with the string [scrubbed]. This way
954 logs can still be useful, but they don’t leave behind personally
955 identifying information about what sites a user might have visited.
956 If this option is set to 0, Tor will not perform any scrubbing, if
959 it is set to 1, all potentially sensitive strings are replaced. If
960 it is set to relay, all log messages generated when acting as a
961 relay are sanitized, but all messages generated when acting as a
962 client are not. Note: Tor may not heed this option when logging at
963 log levels below Notice. (Default: 1)
964 Sandbox 0|1
966 If set to 1, Tor will run securely through the use of a syscall
967 sandbox. Otherwise the sandbox will be disabled. The option only
968 works on Linux-based operating systems, and only when Tor has been
969 built with the libseccomp library. Note that this option may be
970 incompatible with some versions of libc, and some kernel versions.
971 This option can not be changed while tor is running.
972 When the Sandbox is 1, the following options can not be changed
975 when tor is running: Address, ConnLimit, CookieAuthFile,
976 DirPortFrontPage, ExtORPortCookieAuthFile, Logs,
977 ServerDNSResolvConfFile, ClientOnionAuthDir (and any files in it
978 won’t reload on HUP signal).
979 Launching new Onion Services through the control port is not
982 supported with current syscall sandboxing implementation.
983 Tor must remain in client or server mode (some changes to
986 ClientOnly and ORPort are not allowed). Currently, if Sandbox is 1,
987 ControlPort command "GETINFO address" will not work.
988 When using %include in the tor configuration files, reloading the
991 tor configuration is not supported after adding new configuration
992 files or directories.
993 (Default: 0)
996 Schedulers KIST|KISTLite|Vanilla
998 Specify the scheduler type that tor should use. The scheduler is
999 responsible for moving data around within a Tor process. This is an
1000 ordered list by priority which means that the first value will be
1001 tried first and if unavailable, the second one is tried and so on.
1002 It is possible to change these values at runtime. This option
1003 mostly effects relays, and most operators should leave it set to
1004 its default value. (Default: KIST,KISTLite,Vanilla)
1005 The possible scheduler types are:
1008 KIST: Kernel-Informed Socket Transport. Tor will use TCP
1010 information from the kernel to make informed decisions regarding
1011 how much data to send and when to send it. KIST also handles
1012 traffic in batches (see KISTSchedRunInterval) in order to improve
1013 traffic prioritization decisions. As implemented, KIST will only
1014 work on Linux kernel version 2.6.39 or higher.
1015 KISTLite: Same as KIST but without kernel support. Tor will use all
1018 the same mechanics as with KIST, including the batching, but its
1019 decisions regarding how much data to send will not be as good.
1020 KISTLite will work on all kernels and operating systems, and the
1021 majority of the benefits of KIST are still realized with KISTLite.
1022 Vanilla: The scheduler that Tor used before KIST was implemented.
1025 It sends as much data as possible, as soon as possible. Vanilla
1026 will work on all kernels and operating systems.
1027 KISTSchedRunInterval NUM msec
1029 If KIST or KISTLite is used in the Schedulers option, this controls
1030 at which interval the scheduler tick is. If the value is 0 msec,
1031 the value is taken from the consensus if possible else it will
1032 fallback to the default 10 msec. Maximum possible value is 100
1033 msec. (Default: 0 msec)
1034 KISTSockBufSizeFactor NUM
1036 If KIST is used in Schedulers, this is a multiplier of the
1037 per-socket limit calculation of the KIST algorithm. (Default: 1.0)
1038 Socks4Proxy host[:port]
1040 Tor will make all OR connections through the SOCKS 4 proxy at
1041 host:port (or host:1080 if port is not specified).
1042 Socks5Proxy host[:port]
1044 Tor will make all OR connections through the SOCKS 5 proxy at
1045 host:port (or host:1080 if port is not specified).
1046 Socks5ProxyUsername username
1048 Socks5ProxyPassword password
1050 If defined, authenticate to the SOCKS 5 server using username and
1051 password in accordance to RFC 1929. Both username and password must
1052 be between 1 and 255 characters.
1053 SyslogIdentityTag tag
1055 When logging to syslog, adds a tag to the syslog identity such that
1056 log entries are marked with "Tor-tag". Can not be changed while tor
1057 is running. (Default: none)
1058 TCPProxy protocol host:port
1060 Tor will use the given protocol to make all its OR (SSL)
1061 connections through a TCP proxy on host:port, rather than
1062 connecting directly to servers. You may want to set FascistFirewall
1063 to restrict the set of ports you might try to connect to, if your
1064 proxy only allows connecting to certain ports. There is no
1065 equivalent option for directory connections, because all Tor client
1066 versions that support this option download directory documents via
1067 OR connections.
1068 The only protocol supported right now 'haproxy'. This option is only for
1071 clients. (Default: none) +
1072 The HAProxy version 1 proxy protocol is described in detail at
1074 https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt +
1075 Both source IP address and source port will be set to zero.
1077 TruncateLogFile 0|1
1079 If 1, Tor will overwrite logs at startup and in response to a HUP
1080 signal, instead of appending to them. (Default: 0)
1081 UnixSocksGroupWritable 0|1
1083 If this option is set to 0, don’t allow the filesystem group to
1084 read and write unix sockets (e.g. SocksPort unix:). If the option
1085 is set to 1, make the Unix socket readable and writable by the
1086 default GID. (Default: 0)
1087 UseDefaultFallbackDirs 0|1
1089 Use Tor’s default hard-coded FallbackDirs (if any). (When a
1090 FallbackDir line is present, it replaces the hard-coded
1091 FallbackDirs, regardless of the value of UseDefaultFallbackDirs.)
1092 (Default: 1)
1093 User Username
1095 On startup, setuid to this user and setgid to their primary group.
1096 Can not be changed while tor is running.
1097
1099 The following options are useful only for clients (that is, if
1100 SocksPort, HTTPTunnelPort, TransPort, DNSPort, or NATDPort is
1101 non-zero):
1102 AllowNonRFC953Hostnames 0|1
1104 When this option is disabled, Tor blocks hostnames containing
1105 illegal characters (like @ and :) rather than sending them to an
1106 exit node to be resolved. This helps trap accidental attempts to
1107 resolve URLs and so on. (Default: 0)
1108 AutomapHostsOnResolve 0|1
1110 When this option is enabled, and we get a request to resolve an
1111 address that ends with one of the suffixes in AutomapHostsSuffixes,
1112 we map an unused virtual address to that address, and return the
1113 new virtual address. This is handy for making ".onion" addresses
1114 work with applications that resolve an address and then connect to
1115 it. (Default: 0)
1116 AutomapHostsSuffixes SUFFIX,SUFFIX,...
1118 A comma-separated list of suffixes to use with
1119 AutomapHostsOnResolve. The "." suffix is equivalent to "all
1120 addresses." (Default: .exit,.onion).
1121 Bridge [transport] IP:ORPort [fingerprint]
1123 When set along with UseBridges, instructs Tor to use the relay at
1124 "IP:ORPort" as a "bridge" relaying into the Tor network. If
1125 "fingerprint" is provided (using the same format as for
1126 DirAuthority), we will verify that the relay running at that
1127 location has the right fingerprint. We also use fingerprint to look
1128 up the bridge descriptor at the bridge authority, if it’s provided
1129 and if UpdateBridgesFromAuthority is set too.
1130 If "transport" is provided, it must match a ClientTransportPlugin
1133 line. We then use that pluggable transport’s proxy to transfer data
1134 to the bridge, rather than connecting to the bridge directly. Some
1135 transports use a transport-specific method to work out the remote
1136 address to connect to. These transports typically ignore the
1137 "IP:ORPort" specified in the bridge line.
1138 Tor passes any "key=val" settings to the pluggable transport proxy
1141 as per-connection arguments when connecting to the bridge. Consult
1142 the documentation of the pluggable transport for details of what
1143 arguments it supports.
1144 CircuitPadding 0|1
1146 If set to 0, Tor will not pad client circuits with additional cover
1147 traffic. Only clients may set this option. This option should be
1148 offered via the UI to mobile users for use where bandwidth may be
1149 expensive. If set to 1, padding will be negotiated as per the
1150 consensus and relay support (unlike ConnectionPadding,
1151 CircuitPadding cannot be force-enabled). (Default: 1)
1152 ReducedCircuitPadding 0|1
1154 If set to 1, Tor will only use circuit padding algorithms that have
1155 low overhead. Only clients may set this option. This option should
1156 be offered via the UI to mobile users for use where bandwidth may
1157 be expensive. (Default: 0)
1158 ClientBootstrapConsensusAuthorityDownloadInitialDelay N
1160 Initial delay in seconds for when clients should download
1161 consensuses from authorities if they are bootstrapping (that is,
1162 they don’t have a usable, reasonably live consensus). Only used by
1163 clients fetching from a list of fallback directory mirrors. This
1164 schedule is advanced by (potentially concurrent) connection
1165 attempts, unlike other schedules, which are advanced by connection
1166 failures. (Default: 6)
1167 ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay N
1169 Initial delay in seconds for when clients should download
1170 consensuses from authorities if they are bootstrapping (that is,
1171 they don’t have a usable, reasonably live consensus). Only used by
1172 clients which don’t have or won’t fetch from a list of fallback
1173 directory mirrors. This schedule is advanced by (potentially
1174 concurrent) connection attempts, unlike other schedules, which are
1175 advanced by connection failures. (Default: 0)
1176 ClientBootstrapConsensusFallbackDownloadInitialDelay N
1178 Initial delay in seconds for when clients should download
1179 consensuses from fallback directory mirrors if they are
1180 bootstrapping (that is, they don’t have a usable, reasonably live
1181 consensus). Only used by clients fetching from a list of fallback
1182 directory mirrors. This schedule is advanced by (potentially
1183 concurrent) connection attempts, unlike other schedules, which are
1184 advanced by connection failures. (Default: 0)
1185 ClientBootstrapConsensusMaxInProgressTries NUM
1187 Try this many simultaneous connections to download a consensus
1188 before waiting for one to complete, timeout, or error out.
1189 (Default: 3)
1190 ClientDNSRejectInternalAddresses 0|1
1192 If true, Tor does not believe any anonymously retrieved DNS answer
1193 that tells it that an address resolves to an internal address (like
1194 127.0.0.1 or 192.168.0.1). This option prevents certain
1195 browser-based attacks; it is not allowed to be set on the default
1196 network. (Default: 1)
1197 ClientOnionAuthDir path
1199 Path to the directory containing v3 hidden service authorization
1200 files. Each file is for a single onion address, and the files MUST
1201 have the suffix ".auth_private" (i.e. "bob_onion.auth_private").
1202 The content format MUST be:
1203 <onion-address>:descriptor:x25519:<base32-encoded-privkey>
1205 The <onion-address> MUST NOT have the ".onion" suffix. The
1207 <base32-encoded-privkey> is the base32 representation of the raw
1208 key bytes only (32 bytes for x25519). See Appendix G in the
1209 rend-spec-v3.txt file of torspec for more information.
1210 ClientOnly 0|1
1212 If set to 1, Tor will not run as a relay or serve directory
1213 requests, even if the ORPort, ExtORPort, or DirPort options are
1214 set. (This config option is mostly unnecessary: we added it back
1215 when we were considering having Tor clients auto-promote themselves
1216 to being relays if they were stable and fast enough. The current
1217 behavior is simply that Tor is a client unless ORPort, ExtORPort,
1218 or DirPort are configured.) (Default: 0)
1219 ClientPreferIPv6DirPort 0|1|auto
1221 If this option is set to 1, Tor prefers a directory port with an
1222 IPv6 address over one with IPv4, for direct connections, if a given
1223 directory server has both. (Tor also prefers an IPv6 DirPort if
1224 IPv4Client is set to 0.) If this option is set to auto, clients
1225 prefer IPv4. Other things may influence the choice. This option
1226 breaks a tie to the favor of IPv6. (Default: auto) (DEPRECATED:
1227 This option has had no effect for some time.)
1228 ClientPreferIPv6ORPort 0|1|auto
1230 If this option is set to 1, Tor prefers an OR port with an IPv6
1231 address over one with IPv4 if a given entry node has both. (Tor
1232 also prefers an IPv6 ORPort if IPv4Client is set to 0.) If this
1233 option is set to auto, Tor bridge clients prefer the configured
1234 bridge address, and other clients prefer IPv4. Other things may
1235 influence the choice. This option breaks a tie to the favor of
1236 IPv6. (Default: auto)
1237 ClientRejectInternalAddresses 0|1
1239 If true, Tor does not try to fulfill requests to connect to an
1240 internal address (like 127.0.0.1 or 192.168.0.1) unless an exit
1241 node is specifically requested (for example, via a .exit hostname,
1242 or a controller request). If true, multicast DNS hostnames for
1243 machines on the local network (of the form *.local) are also
1244 rejected. (Default: 1)
1245 ClientUseIPv4 0|1
1247 If this option is set to 0, Tor will avoid connecting to directory
1248 servers and entry nodes over IPv4. Note that clients with an IPv4
1249 address in a Bridge, proxy, or pluggable transport line will try
1250 connecting over IPv4 even if ClientUseIPv4 is set to 0. (Default:
1251 1)
1252 ClientUseIPv6 0|1
1254 If this option is set to 1, Tor might connect to directory servers
1255 or entry nodes over IPv6. For IPv6 only hosts, you need to also set
1256 ClientUseIPv4 to 0 to disable IPv4. Note that clients configured
1257 with an IPv6 address in a Bridge, proxy, or pluggable transportline
1258 will try connecting over IPv6 even if ClientUseIPv6 is set to 0.
1259 (Default: 1)
1260 ConnectionPadding 0|1|auto
1262 This option governs Tor’s use of padding to defend against some
1263 forms of traffic analysis. If it is set to auto, Tor will send
1264 padding only if both the client and the relay support it. If it is
1265 set to 0, Tor will not send any padding cells. If it is set to 1,
1266 Tor will still send padding for client connections regardless of
1267 relay support. Only clients may set this option. This option should
1268 be offered via the UI to mobile users for use where bandwidth may
1269 be expensive. (Default: auto)
1270 ReducedConnectionPadding 0|1
1272 If set to 1, Tor will not not hold OR connections open for very
1273 long, and will send less padding on these connections. Only clients
1274 may set this option. This option should be offered via the UI to
1275 mobile users for use where bandwidth may be expensive. (Default: 0)
1276 DNSPort [address:]port|auto [isolation flags]
1278 If non-zero, open this port to listen for UDP DNS requests, and
1279 resolve them anonymously. This port only handles A, AAAA, and PTR
1280 requests---it doesn’t handle arbitrary DNS request types. Set the
1281 port to "auto" to have Tor pick a port for you. This directive can
1282 be specified multiple times to bind to multiple addresses/ports.
1283 See SocksPort for an explanation of isolation flags. (Default: 0)
1284 DownloadExtraInfo 0|1
1286 If true, Tor downloads and caches "extra-info" documents. These
1287 documents contain information about servers other than the
1288 information in their regular server descriptors. Tor does not use
1289 this information for anything itself; to save bandwidth, leave this
1290 option turned off. (Default: 0)
1291 EnforceDistinctSubnets 0|1
1293 If 1, Tor will not put two servers whose IP addresses are "too
1294 close" on the same circuit. Currently, two addresses are "too
1295 close" if they lie in the same /16 range. (Default: 1)
1296 FascistFirewall 0|1
1298 If 1, Tor will only create outgoing connections to ORs running on
1299 ports that your firewall allows (defaults to 80 and 443; see
1300 FirewallPorts). This will allow you to run Tor as a client behind a
1301 firewall with restrictive policies, but will not allow you to run
1302 as a server behind such a firewall. If you prefer more fine-grained
1303 control, use ReachableAddresses instead.
1304 FirewallPorts PORTS
1306 A list of ports that your firewall allows you to connect to. Only
1307 used when FascistFirewall is set. This option is deprecated; use
1308 ReachableAddresses instead. (Default: 80, 443)
1309 HTTPTunnelPort [address:]port|auto [isolation flags]
1311 Open this port to listen for proxy connections using the "HTTP
1312 CONNECT" protocol instead of SOCKS. Set this to 0 if you don’t want
1313 to allow "HTTP CONNECT" connections. Set the port to "auto" to have
1314 Tor pick a port for you. This directive can be specified multiple
1315 times to bind to multiple addresses/ports. If multiple entries of
1316 this option are present in your configuration file, Tor will
1317 perform stream isolation between listeners by default. See
1318 SocksPort for an explanation of isolation flags. (Default: 0)
1319 LongLivedPorts PORTS
1321 A list of ports for services that tend to have long-running
1322 connections (e.g. chat and interactive shells). Circuits for
1323 streams that use these ports will contain only high-uptime nodes,
1324 to reduce the chance that a node will go down before the stream is
1325 finished. Note that the list is also honored for circuits (both
1326 client and service side) involving hidden services whose virtual
1327 port is in this list. (Default: 21, 22, 706, 1863, 5050, 5190,
1328 5222, 5223, 6523, 6667, 6697, 8300)
1329 MapAddress address newaddress
1331 When a request for address arrives to Tor, it will transform to
1332 newaddress before processing it. For example, if you always want
1333 connections to www.example.com to exit via torserver (where
1334 torserver is the fingerprint of the server), use "MapAddress
1335 www.example.com www.example.com.torserver.exit". If the value is
1336 prefixed with a "*.", matches an entire domain. For example, if you
1337 always want connections to example.com and any if its subdomains to
1338 exit via torserver (where torserver is the fingerprint of the
1339 server), use "MapAddress *.example.com
1340 *.example.com.torserver.exit". (Note the leading "*." in each part
1341 of the directive.) You can also redirect all subdomains of a domain
1342 to a single address. For example, "MapAddress *.example.com
1343 www.example.com". If the specified exit is not available, or the
1344 exit can not connect to the site, Tor will fail any connections to
1345 the mapped address.+
1346 NOTES:
1348 1. When evaluating MapAddress expressions Tor stops when it hits
1350 the most recently added expression that matches the requested
1351 address. So if you have the following in your torrc,
1352 www.torproject.org will map to 198.51.100.1:
1353 MapAddress www.torproject.org 192.0.2.1
1355 MapAddress www.torproject.org 198.51.100.1
1356 2. Tor evaluates the MapAddress configuration until it finds no
1358 matches. So if you have the following in your torrc,
1359 www.torproject.org will map to 203.0.113.1:
1360 MapAddress 198.51.100.1 203.0.113.1
1362 MapAddress www.torproject.org 198.51.100.1
1363 3. The following MapAddress expression is invalid (and will be
1365 ignored) because you cannot map from a specific address to a
1366 wildcard address:
1367 MapAddress www.torproject.org *.torproject.org.torserver.exit
1369 4. Using a wildcard to match only part of a string (as in
1371 *ample.com) is also invalid.
1372 5. Tor maps hostnames and IP addresses separately. If you
1374 MapAddress a DNS name, but use an IP address to connect, then
1375 Tor will ignore the DNS name mapping.
1376 6. MapAddress does not apply to redirects in the application
1378 protocol. For example, HTTP redirects and alt-svc headers will
1379 ignore mappings for the original address. You can use a
1380 wildcard mapping to handle redirects within the same site.
1381 MaxCircuitDirtiness NUM
1383 Feel free to reuse a circuit that was first used at most NUM
1384 seconds ago, but never attach a new stream to a circuit that is too
1385 old. For hidden services, this applies to the last time a circuit
1386 was used, not the first. Circuits with streams constructed with
1387 SOCKS authentication via SocksPorts that have
1388 KeepAliveIsolateSOCKSAuth also remain alive for MaxCircuitDirtiness
1389 seconds after carrying the last such stream. (Default: 10 minutes)
1390 MaxClientCircuitsPending NUM
1392 Do not allow more than NUM circuits to be pending at a time for
1393 handling client streams. A circuit is pending if we have begun
1394 constructing it, but it has not yet been completely constructed.
1395 (Default: 32)
1396 NATDPort [address:]port|auto [isolation flags]
1398 Open this port to listen for connections from old versions of ipfw
1399 (as included in old versions of FreeBSD, etc) using the NATD
1400 protocol. Use 0 if you don’t want to allow NATD connections. Set
1401 the port to "auto" to have Tor pick a port for you. This directive
1402 can be specified multiple times to bind to multiple
1403 addresses/ports. If multiple entries of this option are present in
1404 your configuration file, Tor will perform stream isolation between
1405 listeners by default. See SocksPort for an explanation of isolation
1406 flags.
1407 This option is only for people who cannot use TransPort. (Default:
1410 0)
1411 NewCircuitPeriod NUM
1413 Every NUM seconds consider whether to build a new circuit.
1414 (Default: 30 seconds)
1415 PathBiasCircThreshold NUM
1417 PathBiasDropGuards NUM
1419 PathBiasExtremeRate NUM
1421 PathBiasNoticeRate NUM
1423 PathBiasWarnRate NUM
1425 PathBiasScaleThreshold NUM
1427 These options override the default behavior of Tor’s (currently
1428 experimental) path bias detection algorithm. To try to find broken
1429 or misbehaving guard nodes, Tor looks for nodes where more than a
1430 certain fraction of circuits through that guard fail to get built.
1431 The PathBiasCircThreshold option controls how many circuits we need
1434 to build through a guard before we make these checks. The
1435 PathBiasNoticeRate, PathBiasWarnRate and PathBiasExtremeRate
1436 options control what fraction of circuits must succeed through a
1437 guard so we won’t write log messages. If less than
1438 PathBiasExtremeRate circuits succeed and PathBiasDropGuards is set
1439 to 1, we disable use of that guard.
1440 When we have seen more than PathBiasScaleThreshold circuits through
1443 a guard, we scale our observations by 0.5 (governed by the
1444 consensus) so that new observations don’t get swamped by old ones.
1445 By default, or if a negative value is provided for one of these
1448 options, Tor uses reasonable defaults from the networkstatus
1449 consensus document. If no defaults are available there, these
1450 options default to 150, .70, .50, .30, 0, and 300 respectively.
1451 PathBiasUseThreshold NUM
1453 PathBiasNoticeUseRate NUM
1455 PathBiasExtremeUseRate NUM
1457 PathBiasScaleUseThreshold NUM
1459 Similar to the above options, these options override the default
1460 behavior of Tor’s (currently experimental) path use bias detection
1461 algorithm.
1462 Where as the path bias parameters govern thresholds for
1465 successfully building circuits, these four path use bias parameters
1466 govern thresholds only for circuit usage. Circuits which receive no
1467 stream usage are not counted by this detection algorithm. A used
1468 circuit is considered successful if it is capable of carrying
1469 streams or otherwise receiving well-formed responses to RELAY
1470 cells.
1471 By default, or if a negative value is provided for one of these
1474 options, Tor uses reasonable defaults from the networkstatus
1475 consensus document. If no defaults are available there, these
1476 options default to 20, .80, .60, and 100, respectively.
1477 PathsNeededToBuildCircuits NUM
1479 Tor clients don’t build circuits for user traffic until they know
1480 about enough of the network so that they could potentially
1481 construct enough of the possible paths through the network. If this
1482 option is set to a fraction between 0.25 and 0.95, Tor won’t build
1483 circuits until it has enough descriptors or microdescriptors to
1484 construct that fraction of possible paths. Note that setting this
1485 option too low can make your Tor client less anonymous, and setting
1486 it too high can prevent your Tor client from bootstrapping. If this
1487 option is negative, Tor will use a default value chosen by the
1488 directory authorities. If the directory authorities do not choose a
1489 value, Tor will default to 0.6. (Default: -1)
1490 ReachableAddresses IP[/MASK][:PORT]...
1492 A comma-separated list of IP addresses and ports that your firewall
1493 allows you to connect to. The format is as for the addresses in
1494 ExitPolicy, except that "accept" is understood unless "reject" is
1495 explicitly provided. For example, 'ReachableAddresses 99.0.0.0/8,
1496 reject 18.0.0.0/8:80, accept *:80' means that your firewall allows
1497 connections to everything inside net 99, rejects port 80
1498 connections to net 18, and accepts connections to port 80
1499 otherwise. (Default: 'accept *:*'.)
1500 ReachableDirAddresses IP[/MASK][:PORT]...
1502 Like ReachableAddresses, a list of addresses and ports. Tor will
1503 obey these restrictions when fetching directory information, using
1504 standard HTTP GET requests. If not set explicitly then the value of
1505 ReachableAddresses is used. If HTTPProxy is set then these
1506 connections will go through that proxy. (DEPRECATED: This option
1507 has had no effect for some time.)
1508 ReachableORAddresses IP[/MASK][:PORT]...
1510 Like ReachableAddresses, a list of addresses and ports. Tor will
1511 obey these restrictions when connecting to Onion Routers, using
1512 TLS/SSL. If not set explicitly then the value of ReachableAddresses
1513 is used. If HTTPSProxy is set then these connections will go
1514 through that proxy.
1515 The separation between ReachableORAddresses and
1518 ReachableDirAddresses is only interesting when you are connecting
1519 through proxies (see HTTPProxy and HTTPSProxy). Most proxies limit
1520 TLS connections (which Tor uses to connect to Onion Routers) to
1521 port 443, and some limit HTTP GET requests (which Tor uses for
1522 fetching directory information) to port 80.
1523 SafeSocks 0|1
1525 When this option is enabled, Tor will reject application
1526 connections that use unsafe variants of the socks protocol — ones
1527 that only provide an IP address, meaning the application is doing a
1528 DNS resolve first. Specifically, these are socks4 and socks5 when
1529 not doing remote DNS. (Default: 0)
1530 TestSocks 0|1
1532 When this option is enabled, Tor will make a notice-level log entry
1533 for each connection to the Socks port indicating whether the
1534 request used a safe socks protocol or an unsafe one (see
1535 SafeSocks). This helps to determine whether an application using
1536 Tor is possibly leaking DNS requests. (Default: 0)
1537 WarnPlaintextPorts port,port,...
1539 Tells Tor to issue a warnings whenever the user tries to make an
1540 anonymous connection to one of these ports. This option is designed
1541 to alert users to services that risk sending passwords in the
1542 clear. (Default: 23,109,110,143)
1543 RejectPlaintextPorts port,port,...
1545 Like WarnPlaintextPorts, but instead of warning about risky port
1546 uses, Tor will instead refuse to make the connection. (Default:
1547 None)
1548 SocksPolicy policy,policy,...
1550 Set an entrance policy for this server, to limit who can connect to
1551 the SocksPort and DNSPort ports. The policies have the same form as
1552 exit policies below, except that port specifiers are ignored. Any
1553 address not matched by some entry in the policy is accepted.
1554 SocksPort [address:]port|unix:path|auto [flags] [isolation flags]
1556 Open this port to listen for connections from SOCKS-speaking
1557 applications. Set this to 0 if you don’t want to allow application
1558 connections via SOCKS. Set it to "auto" to have Tor pick a port for
1559 you. This directive can be specified multiple times to bind to
1560 multiple addresses/ports. If a unix domain socket is used, you may
1561 quote the path using standard C escape sequences. Most flags are
1562 off by default, except where specified. Flags that are on by
1563 default can be disabled by putting "No" before the flag name.
1564 (Default: 9050)
1565 NOTE: Although this option allows you to specify an IP address
1568 other than localhost, you should do so only with extreme caution.
1569 The SOCKS protocol is unencrypted and (as we use it)
1570 unauthenticated, so exposing it in this way could leak your
1571 information to anybody watching your network, and allow anybody to
1572 use your computer as an open proxy.
1573 If multiple entries of this option are present in your
1576 configuration file, Tor will perform stream isolation between
1577 listeners by default. The isolation flags arguments give Tor rules
1578 for which streams received on this SocksPort are allowed to share
1579 circuits with one another. Recognized isolation flags are:
1580 IsolateClientAddr
1582 Don’t share circuits with streams from a different client
1583 address. (On by default and strongly recommended when
1584 supported; you can disable it with NoIsolateClientAddr.
1585 Unsupported and force-disabled when using Unix domain sockets.)
1586 IsolateSOCKSAuth
1588 Don’t share circuits with streams for which different SOCKS
1589 authentication was provided. (For HTTPTunnelPort connections,
1590 this option looks at the Proxy-Authorization and
1591 X-Tor-Stream-Isolation headers. On by default; you can disable
1592 it with NoIsolateSOCKSAuth.)
1593 IsolateClientProtocol
1595 Don’t share circuits with streams using a different protocol.
1596 (SOCKS 4, SOCKS 5, HTTPTunnelPort connections, TransPort
1597 connections, NATDPort connections, and DNSPort requests are all
1598 considered to be different protocols.)
1599 IsolateDestPort
1601 Don’t share circuits with streams targeting a different
1602 destination port.
1603 IsolateDestAddr
1605 Don’t share circuits with streams targeting a different
1606 destination address.
1607 KeepAliveIsolateSOCKSAuth
1609 If IsolateSOCKSAuth is enabled, keep alive circuits while they
1610 have at least one stream with SOCKS authentication active.
1611 After such a circuit is idle for more than MaxCircuitDirtiness
1612 seconds, it can be closed.
1613 SessionGroup=INT
1615 If no other isolation rules would prevent it, allow streams on
1616 this port to share circuits with streams from every other port
1617 with the same session group. (By default, streams received on
1618 different SocksPorts, TransPorts, etc are always isolated from
1619 one another. This option overrides that behavior.)
1620 Other recognized flags for a SocksPort are:
1622 NoIPv4Traffic
1624 Tell exits to not connect to IPv4 addresses in response to
1625 SOCKS requests on this connection.
1626 IPv6Traffic
1628 Tell exits to allow IPv6 addresses in response to SOCKS
1629 requests on this connection, so long as SOCKS5 is in use.
1630 (SOCKS4 can’t handle IPv6.)
1631 PreferIPv6
1633 Tells exits that, if a host has both an IPv4 and an IPv6
1634 address, we would prefer to connect to it via IPv6. (IPv4 is
1635 the default.)
1636 NoDNSRequest
1638 Do not ask exits to resolve DNS addresses in SOCKS5 requests.
1639 Tor will connect to IPv4 addresses, IPv6 addresses (if
1640 IPv6Traffic is set) and .onion addresses.
1641 NoOnionTraffic
1643 Do not connect to .onion addresses in SOCKS5 requests.
1644 OnionTrafficOnly
1646 Tell the tor client to only connect to .onion addresses in
1647 response to SOCKS5 requests on this connection. This is
1648 equivalent to NoDNSRequest, NoIPv4Traffic, NoIPv6Traffic. The
1649 corresponding NoOnionTrafficOnly flag is not supported.
1650 CacheIPv4DNS
1652 Tells the client to remember IPv4 DNS answers we receive from
1653 exit nodes via this connection.
1654 CacheIPv6DNS
1656 Tells the client to remember IPv6 DNS answers we receive from
1657 exit nodes via this connection.
1658 GroupWritable
1660 Unix domain sockets only: makes the socket get created as
1661 group-writable.
1662 WorldWritable
1664 Unix domain sockets only: makes the socket get created as
1665 world-writable.
1666 CacheDNS
1668 Tells the client to remember all DNS answers we receive from
1669 exit nodes via this connection.
1670 UseIPv4Cache
1672 Tells the client to use any cached IPv4 DNS answers we have
1673 when making requests via this connection. (NOTE: This option,
1674 or UseIPv6Cache or UseDNSCache, can harm your anonymity, and
1675 probably won’t help performance as much as you might expect.
1676 Use with care!)
1677 UseIPv6Cache
1679 Tells the client to use any cached IPv6 DNS answers we have
1680 when making requests via this connection.
1681 UseDNSCache
1683 Tells the client to use any cached DNS answers we have when
1684 making requests via this connection.
1685 NoPreferIPv6Automap
1687 When serving a hostname lookup request on this port that should
1688 get automapped (according to AutomapHostsOnResolve), if we
1689 could return either an IPv4 or an IPv6 answer, prefer an IPv4
1690 answer. (Tor prefers IPv6 by default.)
1691 PreferSOCKSNoAuth
1693 Ordinarily, when an application offers both "username/password
1694 authentication" and "no authentication" to Tor via SOCKS5, Tor
1695 selects username/password authentication so that
1696 IsolateSOCKSAuth can work. This can confuse some applications,
1697 if they offer a username/password combination then get confused
1698 when asked for one. You can disable this behavior, so that Tor
1699 will select "No authentication" when IsolateSOCKSAuth is
1700 disabled, or when this option is set.
1701 ExtendedErrors
1703 Return extended error code in the SOCKS reply. So far, the
1704 possible errors are:
1705 X'F0' Onion Service Descriptor Can Not be Found
1707 The requested onion service descriptor can't be found on the
1709 hashring and thus not reachable by the client. (v3 only)
1710 X'F1' Onion Service Descriptor Is Invalid
1712 The requested onion service descriptor can't be parsed or
1714 signature validation failed. (v3 only)
1715 X'F2' Onion Service Introduction Failed
1717 All introduction attempts failed either due to a combination of
1719 NACK by the intro point or time out. (v3 only)
1720 X'F3' Onion Service Rendezvous Failed
1722 Every rendezvous circuit has timed out and thus the client is
1724 unable to rendezvous with the service. (v3 only)
1725 X'F4' Onion Service Missing Client Authorization
1727 Client was able to download the requested onion service descriptor
1729 but is unable to decrypt its content because it is missing client
1730 authorization information. (v3 only)
1731 X'F5' Onion Service Wrong Client Authorization
1733 Client was able to download the requested onion service descriptor
1735 but is unable to decrypt its content using the client
1736 authorization information it has. This means the client access
1737 were revoked. (v3 only)
1738 X'F6' Onion Service Invalid Address
1740 The given .onion address is invalid. In one of these cases this
1742 error is returned: address checksum doesn't match, ed25519 public
1743 key is invalid or the encoding is invalid. (v3 only)
1744 X'F7' Onion Service Introduction Timed Out
1746 Similar to X'F2' code but in this case, all introduction attempts
1748 have failed due to a time out. (v3 only)
1749 Flags are processed left to right. If flags conflict, the last flag
1751 on the line is used, and all earlier flags are ignored. No error is
1752 issued for conflicting flags.
1753 TokenBucketRefillInterval NUM [msec|second]
1755 Set the refill delay interval of Tor’s token bucket to NUM
1756 milliseconds. NUM must be between 1 and 1000, inclusive. When Tor
1757 is out of bandwidth, on a connection or globally, it will wait up
1758 to this long before it tries to use that connection again. Note
1759 that bandwidth limits are still expressed in bytes per second: this
1760 option only affects the frequency with which Tor checks to see
1761 whether previously exhausted connections may read again. Can not be
1762 changed while tor is running. (Default: 100 msec)
1763 TrackHostExits host,.domain,...
1765 For each value in the comma separated list, Tor will track recent
1766 connections to hosts that match this value and attempt to reuse the
1767 same exit node for each. If the value is prepended with a '.', it
1768 is treated as matching an entire domain. If one of the values is
1769 just a '.', it means match everything. This option is useful if you
1770 frequently connect to sites that will expire all your
1771 authentication cookies (i.e. log you out) if your IP address
1772 changes. Note that this option does have the disadvantage of making
1773 it more clear that a given history is associated with a single
1774 user. However, most people who would wish to observe this will
1775 observe it through cookies or other protocol-specific means anyhow.
1776 TrackHostExitsExpire NUM
1778 Since exit servers go up and down, it is desirable to expire the
1779 association between host and exit server after NUM seconds. The
1780 default is 1800 seconds (30 minutes).
1781 TransPort [address:]port|auto [isolation flags]
1783 Open this port to listen for transparent proxy connections. Set
1784 this to 0 if you don’t want to allow transparent proxy connections.
1785 Set the port to "auto" to have Tor pick a port for you. This
1786 directive can be specified multiple times to bind to multiple
1787 addresses/ports. If multiple entries of this option are present in
1788 your configuration file, Tor will perform stream isolation between
1789 listeners by default. See SocksPort for an explanation of isolation
1790 flags.
1791 TransPort requires OS support for transparent proxies, such as
1794 BSDs' pf or Linux’s IPTables. If you’re planning to use Tor as a
1795 transparent proxy for a network, you’ll want to examine and change
1796 VirtualAddrNetwork from the default setting. (Default: 0)
1797 TransProxyType default|TPROXY|ipfw|pf-divert
1799 TransProxyType may only be enabled when there is transparent proxy
1800 listener enabled.
1801 Set this to "TPROXY" if you wish to be able to use the TPROXY Linux
1804 module to transparently proxy connections that are configured using
1805 the TransPort option. Detailed information on how to configure the
1806 TPROXY feature can be found in the Linux kernel source tree in the
1807 file Documentation/networking/tproxy.txt.
1808 Set this option to "ipfw" to use the FreeBSD ipfw interface.
1811 On *BSD operating systems when using pf, set this to "pf-divert" to
1814 take advantage of divert-to rules, which do not modify the packets
1815 like rdr-to rules do. Detailed information on how to configure pf
1816 to use divert-to rules can be found in the pf.conf(5) manual page.
1817 On OpenBSD, divert-to is available to use on versions greater than
1818 or equal to OpenBSD 4.4.
1819 Set this to "default", or leave it unconfigured, to use regular
1822 IPTables on Linux, or to use pf rdr-to rules on *BSD systems.
1823 (Default: "default")
1826 UpdateBridgesFromAuthority 0|1
1828 When set (along with UseBridges), Tor will try to fetch bridge
1829 descriptors from the configured bridge authorities when feasible.
1830 It will fall back to a direct request if the authority responds
1831 with a 404. (Default: 0)
1832 UseBridges 0|1
1834 When set, Tor will fetch descriptors for each bridge listed in the
1835 "Bridge" config lines, and use these relays as both entry guards
1836 and directory guards. (Default: 0)
1837 UseEntryGuards 0|1
1839 If this option is set to 1, we pick a few long-term entry servers,
1840 and try to stick with them. This is desirable because constantly
1841 changing servers increases the odds that an adversary who owns some
1842 servers will observe a fraction of your paths. Entry Guards can not
1843 be used by Directory Authorities or Single Onion Services. In these
1844 cases, this option is ignored. (Default: 1)
1845 UseGuardFraction 0|1|auto
1847 This option specifies whether clients should use the guardfraction
1848 information found in the consensus during path selection. If it’s
1849 set to auto, clients will do what the UseGuardFraction consensus
1850 parameter tells them to do. (Default: auto)
1851 GuardLifetime N days|weeks|months
1853 If UseEntryGuards is set, minimum time to keep a guard on our guard
1854 list before picking a new one. If less than one day, we use
1855 defaults from the consensus directory. (Default: 0)
1856 NumDirectoryGuards NUM
1858 If UseEntryGuards is set to 1, we try to make sure we have at least
1859 NUM routers to use as directory guards. If this option is set to 0,
1860 use the value from the guard-n-primary-dir-guards-to-use consensus
1861 parameter, and default to 3 if the consensus parameter isn’t set.
1862 (Default: 0)
1863 NumEntryGuards NUM
1865 If UseEntryGuards is set to 1, we will try to pick a total of NUM
1866 routers as long-term entries for our circuits. If NUM is 0, we try
1867 to learn the number from the guard-n-primary-guards-to-use
1868 consensus parameter, and default to 1 if the consensus parameter
1869 isn’t set. (Default: 0)
1870 NumPrimaryGuards NUM
1872 If UseEntryGuards is set to 1, we will try to pick NUM routers for
1873 our primary guard list, which is the set of routers we strongly
1874 prefer when connecting to the Tor network. If NUM is 0, we try to
1875 learn the number from the guard-n-primary-guards consensus
1876 parameter, and default to 3 if the consensus parameter isn’t set.
1877 (Default: 0)
1878 VanguardsLiteEnabled 0|1|auto
1880 This option specifies whether clients should use the vanguards-lite
1881 subsystem to protect against guard discovery attacks. If it’s set
1882 to auto, clients will do what the vanguards-lite-enabled consensus
1883 parameter tells them to do, and will default to enable the
1884 subsystem if the consensus parameter isn’t set. (Default: auto)
1885 UseMicrodescriptors 0|1|auto
1887 Microdescriptors are a smaller version of the information that Tor
1888 needs in order to build its circuits. Using microdescriptors makes
1889 Tor clients download less directory information, thus saving
1890 bandwidth. Directory caches need to fetch regular descriptors and
1891 microdescriptors, so this option doesn’t save any bandwidth for
1892 them. For legacy reasons, auto is accepted, but it has the same
1893 effect as 1. (Default: auto)
1894 VirtualAddrNetworkIPv4 IPv4Address/bits
1896 VirtualAddrNetworkIPv6 [IPv6Address]/bits
1898 When Tor needs to assign a virtual (unused) address because of a
1899 MAPADDRESS command from the controller or the AutomapHostsOnResolve
1900 feature, Tor picks an unassigned address from this range.
1901 (Defaults: 127.192.0.0/10 and [FE80::]/10 respectively.)
1902 When providing proxy server service to a network of computers using
1905 a tool like dns-proxy-tor, change the IPv4 network to
1906 "10.192.0.0/10" or "172.16.0.0/12" and change the IPv6 network to
1907 "[FC00::]/7". The default VirtualAddrNetwork address ranges on a
1908 properly configured machine will route to the loopback or
1909 link-local interface. The maximum number of bits for the network
1910 prefix is set to 104 for IPv6 and 16 for IPv4. However, a larger
1911 network (that is, one with a smaller prefix length) is preferable,
1912 since it reduces the chances for an attacker to guess the used IP.
1913 For local use, no change to the default VirtualAddrNetwork setting
1914 is needed.
1915
1917 The following options are useful for configuring timeouts related to
1918 building Tor circuits and using them:
1919 CircuitsAvailableTimeout NUM
1921 Tor will attempt to keep at least one open, unused circuit
1922 available for this amount of time. This option governs how long
1923 idle circuits are kept open, as well as the amount of time Tor will
1924 keep a circuit open to each of the recently used ports. This way
1925 when the Tor client is entirely idle, it can expire all of its
1926 circuits, and then expire its TLS connections. Note that the actual
1927 timeout value is uniformly randomized from the specified value to
1928 twice that amount. (Default: 30 minutes; Max: 24 hours)
1929 LearnCircuitBuildTimeout 0|1
1931 If 0, CircuitBuildTimeout adaptive learning is disabled. (Default:
1932 1)
1933 CircuitBuildTimeout NUM
1935 Try for at most NUM seconds when building circuits. If the circuit
1936 isn’t open in that time, give up on it. If LearnCircuitBuildTimeout
1937 is 1, this value serves as the initial value to use before a
1938 timeout is learned. If LearnCircuitBuildTimeout is 0, this value is
1939 the only value used. (Default: 60 seconds)
1940 CircuitStreamTimeout NUM
1942 If non-zero, this option overrides our internal timeout schedule
1943 for how many seconds until we detach a stream from a circuit and
1944 try a new circuit. If your network is particularly slow, you might
1945 want to set this to a number like 60. (Default: 0)
1946 SocksTimeout NUM
1948 Let a socks connection wait NUM seconds handshaking, and NUM
1949 seconds unattached waiting for an appropriate circuit, before we
1950 fail it. (Default: 2 minutes)
1951
1953 Tor can enter dormant mode to conserve power and network bandwidth. The
1954 following options control when Tor enters and leaves dormant mode:
1955 DormantCanceledByStartup 0|1
1957 By default, Tor starts in active mode if it was active the last
1958 time it was shut down, and in dormant mode if it was dormant. But
1959 if this option is true, Tor treats every startup event as user
1960 activity, and Tor will never start in Dormant mode, even if it has
1961 been unused for a long time on previous runs. (Default: 0)
1962 Note: Packagers and application developers should change the value
1964 of this option only with great caution: it has the potential to
1965 create spurious traffic on the network. This option should only be
1966 used if Tor is started by an affirmative user activity (like
1967 clicking on an application or running a command), and not if Tor is
1968 launched for some other reason (for example, by a startup process,
1969 or by an application that launches itself on every login.)
1970 DormantClientTimeout N minutes|hours|days|weeks
1972 If Tor spends this much time without any client activity, enter a
1973 dormant state where automatic circuits are not built, and directory
1974 information is not fetched. Does not affect servers or onion
1975 services. Must be at least 10 minutes. (Default: 24 hours)
1976 DormantOnFirstStartup 0|1
1978 If true, then the first time Tor starts up with a fresh
1979 DataDirectory, it starts in dormant mode, and takes no actions
1980 until the user has made a request. (This mode is recommended if
1981 installing a Tor client for a user who might not actually use it.)
1982 If false, Tor bootstraps the first time it is started, whether it
1983 sees a user request or not.
1984 After the first time Tor starts, it begins in dormant mode if it
1986 was dormant before, and not otherwise. (Default: 0)
1987 DormantTimeoutDisabledByIdleStreams 0|1
1989 If true, then any open client stream (even one not reading or
1990 writing) counts as client activity for the purpose of
1991 DormantClientTimeout. If false, then only network activity counts.
1992 (Default: 1)
1993 DormantTimeoutEnabled 0|1
1995 If false, then no amount of time without activity is sufficient to
1996 make Tor go dormant. Setting this option to zero is only
1997 recommended for special-purpose applications that need to use the
1998 Tor binary for something other than sending or receiving Tor
1999 traffic. (Default: 1)
2000
2002 The following options restrict the nodes that a tor client (or onion
2003 service) can use while building a circuit. These options can weaken
2004 your anonymity by making your client behavior different from other Tor
2005 clients:
2006 EntryNodes node,node,...
2008 A list of identity fingerprints and country codes of nodes to use
2009 for the first hop in your normal circuits. Normal circuits include
2010 all circuits except for direct connections to directory servers.
2011 The Bridge option overrides this option; if you have configured
2012 bridges and UseBridges is 1, the Bridges are used as your entry
2013 nodes.
2014 This option can appear multiple times: the values from multiple
2017 lines are spliced together.
2018 The ExcludeNodes option overrides this option: any node listed in
2021 both EntryNodes and ExcludeNodes is treated as excluded. See
2022 ExcludeNodes for more information on how to specify nodes.
2023 ExcludeNodes node,node,...
2025 A list of identity fingerprints, country codes, and address
2026 patterns of nodes to avoid when building a circuit. Country codes
2027 are 2-letter ISO3166 codes, and must be wrapped in braces;
2028 fingerprints may be preceded by a dollar sign. (Example:
2029 ExcludeNodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, {cc},
2030 255.254.0.0/8)
2031 This option can appear multiple times: the values from multiple
2034 lines are spliced together.
2035 By default, this option is treated as a preference that Tor is
2038 allowed to override in order to keep working. For example, if you
2039 try to connect to a hidden service, but you have excluded all of
2040 the hidden service’s introduction points, Tor will connect to one
2041 of them anyway. If you do not want this behavior, set the
2042 StrictNodes option (documented below).
2043 Note also that if you are a relay, this (and the other node
2046 selection options below) only affects your own circuits that Tor
2047 builds for you. Clients can still build circuits through you to any
2048 node. Controllers can tell Tor to build circuits through any node.
2049 Country codes are case-insensitive. The code "{??}" refers to nodes
2052 whose country can’t be identified. No country code, including {??},
2053 works if no GeoIPFile can be loaded. See also the
2054 GeoIPExcludeUnknown option below.
2055 ExcludeExitNodes node,node,...
2057 A list of identity fingerprints, country codes, and address
2058 patterns of nodes to never use when picking an exit node---that is,
2059 a node that delivers traffic for you outside the Tor network. Note
2060 that any node listed in ExcludeNodes is automatically considered to
2061 be part of this list too. See ExcludeNodes for more information on
2062 how to specify nodes. See also the caveats on the ExitNodes option
2063 below.
2064 This option can appear multiple times: the values from multiple
2066 lines are spliced together.
2067 ExitNodes node,node,...
2070 A list of identity fingerprints, country codes, and address
2071 patterns of nodes to use as exit node---that is, a node that
2072 delivers traffic for you outside the Tor network. See ExcludeNodes
2073 for more information on how to specify nodes.
2074 This option can appear multiple times: the values from multiple
2077 lines are spliced together.
2078 Note that if you list too few nodes here, or if you exclude too
2081 many exit nodes with ExcludeExitNodes, you can degrade
2082 functionality. For example, if none of the exits you list allows
2083 traffic on port 80 or 443, you won’t be able to browse the web.
2084 Note also that not every circuit is used to deliver traffic outside
2087 of the Tor network. It is normal to see non-exit circuits (such as
2088 those used to connect to hidden services, those that do directory
2089 fetches, those used for relay reachability self-tests, and so on)
2090 that end at a non-exit node. To keep a node from being used
2091 entirely, see ExcludeNodes and StrictNodes.
2092 The ExcludeNodes option overrides this option: any node listed in
2095 both ExitNodes and ExcludeNodes is treated as excluded.
2096 The .exit address notation, if enabled via MapAddress, overrides
2099 this option.
2100 GeoIPExcludeUnknown 0|1|auto
2102 If this option is set to auto, then whenever any country code is
2103 set in ExcludeNodes or ExcludeExitNodes, all nodes with unknown
2104 country ({??} and possibly {A1}) are treated as excluded as well.
2105 If this option is set to 1, then all unknown countries are treated
2106 as excluded in ExcludeNodes and ExcludeExitNodes. This option has
2107 no effect when a GeoIP file isn’t configured or can’t be found.
2108 (Default: auto)
2109 HSLayer2Nodes node,node,...
2111 A list of identity fingerprints, nicknames, country codes, and
2112 address patterns of nodes that are allowed to be used as the second
2113 hop in all client or service-side Onion Service circuits. This
2114 option mitigates attacks where the adversary runs middle nodes and
2115 induces your client or service to create many circuits, in order to
2116 discover your primary guard node. (Default: Any node in the network
2117 may be used in the second hop.)
2118 (Example: HSLayer2Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234,
2120 {cc}, 255.254.0.0/8)
2121 This option can appear multiple times: the values from multiple
2124 lines are spliced together.
2125 When this is set, the resulting hidden service paths will look
2128 like:
2129 C - G - L2 - M - Rend
2131 C - G - L2 - M - HSDir
2133 C - G - L2 - M - Intro
2135 S - G - L2 - M - Rend
2137 S - G - L2 - M - HSDir
2139 S - G - L2 - M - Intro
2141 where C is this client, S is the service, G is the Guard node, L2
2144 is a node from this option, and M is a random middle node. Rend,
2145 HSDir, and Intro point selection is not affected by this option.
2146 This option may be combined with HSLayer3Nodes to create paths of
2148 the form:
2149 C - G - L2 - L3 - Rend
2151 C - G - L2 - L3 - M - HSDir
2153 C - G - L2 - L3 - M - Intro
2155 S - G - L2 - L3 - M - Rend
2157 S - G - L2 - L3 - HSDir
2159 S - G - L2 - L3 - Intro
2161 ExcludeNodes have higher priority than HSLayer2Nodes, which means
2164 that nodes specified in ExcludeNodes will not be picked.
2165 When either this option or HSLayer3Nodes are set, the /16 subnet
2167 and node family restrictions are removed for hidden service
2168 circuits. Additionally, we allow the guard node to be present as
2169 the Rend, HSDir, and IP node, and as the hop before it. This is
2170 done to prevent the adversary from inferring information about our
2171 guard, layer2, and layer3 node choices at later points in the path.
2172 This option is meant to be managed by a Tor controller such as
2174 https://github.com/mikeperry-tor/vanguards that selects and updates
2175 this set of nodes for you. Hence it does not do load balancing if
2176 fewer than 20 nodes are selected, and if no nodes in HSLayer2Nodes
2177 are currently available for use, Tor will not work. Please use
2178 extreme care if you are setting this option manually.
2179 HSLayer3Nodes node,node,...
2181 A list of identity fingerprints, nicknames, country codes, and
2182 address patterns of nodes that are allowed to be used as the third
2183 hop in all client and service-side Onion Service circuits. This
2184 option mitigates attacks where the adversary runs middle nodes and
2185 induces your client or service to create many circuits, in order to
2186 discover your primary or Layer2 guard nodes. (Default: Any node in
2187 the network may be used in the third hop.)
2188 (Example: HSLayer3Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234,
2190 {cc}, 255.254.0.0/8)
2191 This option can appear multiple times: the values from multiple
2194 lines are spliced together.
2195 When this is set by itself, the resulting hidden service paths will
2198 look like:
2199 C - G - M - L3 - Rend
2201 C - G - M - L3 - M - HSDir
2203 C - G - M - L3 - M - Intro
2205 S - G - M - L3 - M - Rend
2207 S - G - M - L3 - HSDir
2209 S - G - M - L3 - Intro
2211 where C is this client, S is the service, G is the Guard node, L2
2213 is a node from this option, and M is a random middle node. Rend,
2214 HSDir, and Intro point selection is not affected by this option.
2215 While it is possible to use this option by itself, it should be
2217 combined with HSLayer2Nodes to create paths of the form:
2218 C - G - L2 - L3 - Rend
2220 C - G - L2 - L3 - M - HSDir
2222 C - G - L2 - L3 - M - Intro
2224 S - G - L2 - L3 - M - Rend
2226 S - G - L2 - L3 - HSDir
2228 S - G - L2 - L3 - Intro
2230 ExcludeNodes have higher priority than HSLayer3Nodes, which means
2233 that nodes specified in ExcludeNodes will not be picked.
2234 When either this option or HSLayer2Nodes are set, the /16 subnet
2236 and node family restrictions are removed for hidden service
2237 circuits. Additionally, we allow the guard node to be present as
2238 the Rend, HSDir, and IP node, and as the hop before it. This is
2239 done to prevent the adversary from inferring information about our
2240 guard, layer2, and layer3 node choices at later points in the path.
2241 This option is meant to be managed by a Tor controller such as
2243 https://github.com/mikeperry-tor/vanguards that selects and updates
2244 this set of nodes for you. Hence it does not do load balancing if
2245 fewer than 20 nodes are selected, and if no nodes in HSLayer3Nodes
2246 are currently available for use, Tor will not work. Please use
2247 extreme care if you are setting this option manually.
2248 MiddleNodes node,node,...
2250 A list of identity fingerprints and country codes of nodes to use
2251 for "middle" hops in your normal circuits. Normal circuits include
2252 all circuits except for direct connections to directory servers.
2253 Middle hops are all hops other than exit and entry.
2254 This option can appear multiple times: the values from multiple
2256 lines are spliced together.
2257 This is an experimental feature that is meant to be used by
2260 researchers and developers to test new features in the Tor network
2261 safely. Using it without care will strongly influence your
2262 anonymity. Other tor features may not work with MiddleNodes. This
2263 feature might get removed in the future.
2264 The HSLayer2Node and HSLayer3Node options override this option for onion
2266 service circuits, if they are set. The vanguards addon will read this
2267 option, and if set, it will set HSLayer2Nodes and HSLayer3Nodes to nodes
2268 from this set.
2269 The ExcludeNodes option overrides this option: any node listed in both
2271 MiddleNodes and ExcludeNodes is treated as excluded. See
2272 the <<ExcludeNodes,ExcludeNodes>> for more information on how to specify nodes.
2273 NodeFamily node,node,...
2275 The Tor servers, defined by their identity fingerprints, constitute
2276 a "family" of similar or co-administered servers, so never use any
2277 two of them in the same circuit. Defining a NodeFamily is only
2278 needed when a server doesn’t list the family itself (with
2279 MyFamily). This option can be used multiple times; each instance
2280 defines a separate family. In addition to nodes, you can also list
2281 IP address and ranges and country codes in {curly braces}. See
2282 ExcludeNodes for more information on how to specify nodes.
2283 StrictNodes 0|1
2285 If StrictNodes is set to 1, Tor will treat solely the ExcludeNodes
2286 option as a requirement to follow for all the circuits you
2287 generate, even if doing so will break functionality for you
2288 (StrictNodes does not apply to ExcludeExitNodes, ExitNodes,
2289 MiddleNodes, or MapAddress). If StrictNodes is set to 0, Tor will
2290 still try to avoid nodes in the ExcludeNodes list, but it will err
2291 on the side of avoiding unexpected errors. Specifically,
2292 StrictNodes 0 tells Tor that it is okay to use an excluded node
2293 when it is necessary to perform relay reachability self-tests,
2294 connect to a hidden service, provide a hidden service to a client,
2295 fulfill a .exit request, upload directory information, or download
2296 directory information. (Default: 0)
2297
2299 The following options are useful only for servers (that is, if ORPort
2300 is non-zero):
2301 AccountingMax N
2303 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
2304 Limits the max number of bytes sent and received within a set time
2305 period using a given calculation rule (see AccountingStart and
2306 AccountingRule). Useful if you need to stay under a specific
2307 bandwidth. By default, the number used for calculation is the max
2308 of either the bytes sent or received. For example, with
2309 AccountingMax set to 1 TByte, a server could send 900 GBytes and
2310 receive 800 GBytes and continue running. It will only hibernate
2311 once one of the two reaches 1 TByte. This can be changed to use the
2312 sum of the both bytes received and sent by setting the
2313 AccountingRule option to "sum" (total bandwidth in/out). When the
2314 number of bytes remaining gets low, Tor will stop accepting new
2315 connections and circuits. When the number of bytes is exhausted,
2316 Tor will hibernate until some time in the next accounting period.
2317 To prevent all servers from waking at the same time, Tor will also
2318 wait until a random point in each period before waking up. If you
2319 have bandwidth cost issues, enabling hibernation is preferable to
2320 setting a low bandwidth, since it provides users with a collection
2321 of fast servers that are up some of the time, which is more useful
2322 than a set of slow servers that are always "available".
2323 Note that (as also described in the Bandwidth section) Tor uses
2326 powers of two, not powers of ten: 1 GByte is 1024*1024*1024, not
2327 one billion. Be careful: some internet service providers might
2328 count GBytes differently.
2329 AccountingRule sum|max|in|out
2331 How we determine when our AccountingMax has been reached (when we
2332 should hibernate) during a time interval. Set to "max" to calculate
2333 using the higher of either the sent or received bytes (this is the
2334 default functionality). Set to "sum" to calculate using the sent
2335 plus received bytes. Set to "in" to calculate using only the
2336 received bytes. Set to "out" to calculate using only the sent
2337 bytes. (Default: max)
2338 AccountingStart day|week|month [day] HH:MM
2340 Specify how long accounting periods last. If month is given, each
2341 accounting period runs from the time HH:MM on the dayth day of one
2342 month to the same day and time of the next. The relay will go at
2343 full speed, use all the quota you specify, then hibernate for the
2344 rest of the period. (The day must be between 1 and 28.) If week is
2345 given, each accounting period runs from the time HH:MM of the dayth
2346 day of one week to the same day and time of the next week, with
2347 Monday as day 1 and Sunday as day 7. If day is given, each
2348 accounting period runs from the time HH:MM each day to the same
2349 time on the next day. All times are local, and given in 24-hour
2350 time. (Default: "month 1 0:00")
2351 Address address
2353 The address of this server, or a fully qualified domain name of
2354 this server that resolves to an address. You can leave this unset,
2355 and Tor will try to guess your address. If a domain name is
2356 provided, Tor will attempt to resolve it and use the underlying
2357 IPv4/IPv6 address as its publish address (taking precedence over
2358 the ORPort configuration). The publish address is the one used to
2359 tell clients and other servers where to find your Tor server; it
2360 doesn’t affect the address that your server binds to. To bind to a
2361 different address, use the ORPort and OutboundBindAddress options.
2362 AddressDisableIPv6 0|1
2364 By default, Tor will attempt to find the IPv6 of the relay if there
2365 is no IPv4Only ORPort. If set, this option disables IPv6 auto
2366 discovery. This disables IPv6 address resolution, IPv6 ORPorts, and
2367 IPv6 reachability checks. Also, the relay won’t publish an IPv6
2368 ORPort in its descriptor. (Default: 0)
2369 AssumeReachable 0|1
2371 This option is used when bootstrapping a new Tor network. If set to
2372 1, don’t do self-reachability testing; just upload your server
2373 descriptor immediately. (Default: 0)
2374 AssumeReachableIPv6 0|1|auto
2376 Like AssumeReachable, but affects only the relay’s own IPv6 ORPort.
2377 If this value is set to "auto", then Tor will look at
2378 AssumeReachable instead. (Default: auto)
2379 BridgeRelay 0|1
2381 Sets the relay to act as a "bridge" with respect to relaying
2382 connections from bridge users to the Tor network. It mainly causes
2383 Tor to publish a server descriptor to the bridge database, rather
2384 than to the public directory authorities.
2385 Note: make sure that no MyFamily lines are present in your torrc
2388 when relay is configured in bridge mode.
2389 BridgeDistribution string
2391 If set along with BridgeRelay, Tor will include a new line in its
2392 bridge descriptor which indicates to the BridgeDB service how it
2393 would like its bridge address to be given out. Set it to "none" if
2394 you want BridgeDB to avoid distributing your bridge address, or
2395 "any" to let BridgeDB decide. See
2396 https://bridges.torproject.org/info for a more up-to-date list of
2397 options. (Default: any)
2398 ContactInfo email_address
2400 Administrative contact information for this relay or bridge. This
2401 line can be used to contact you if your relay or bridge is
2402 misconfigured or something else goes wrong. Note that we archive
2403 and publish all descriptors containing these lines and that Google
2404 indexes them, so spammers might also collect them. You may want to
2405 obscure the fact that it’s an email address and/or generate a new
2406 address for this purpose.
2407 ContactInfo must be set to a working address if you run more than
2410 one relay or bridge. (Really, everybody running a relay or bridge
2411 should set it.)
2412 DisableOOSCheck 0|1
2414 This option disables the code that closes connections when Tor
2415 notices that it is running low on sockets. Right now, it is on by
2416 default, since the existing out-of-sockets mechanism tends to kill
2417 OR connections more than it should. (Default: 1)
2418 ExitPolicy policy,policy,...
2420 Set an exit policy for this server. Each policy is of the form
2421 "accept[6]|reject[6] ADDR[/MASK][:PORT]". If /MASK is omitted then
2422 this policy just applies to the host given. Instead of giving a
2423 host or network you can also use "*" to denote the universe
2424 (0.0.0.0/0 and ::/0), or *4 to denote all IPv4 addresses, and *6 to
2425 denote all IPv6 addresses. PORT can be a single port number, an
2426 interval of ports "FROM_PORT-TO_PORT", or "*". If PORT is omitted,
2427 that means "*".
2428 For example, "accept 18.7.22.69:*,reject 18.0.0.0/8:*,accept *:*"
2431 would reject any IPv4 traffic destined for MIT except for
2432 web.mit.edu, and accept any other IPv4 or IPv6 traffic.
2433 Tor also allows IPv6 exit policy entries. For instance, "reject6
2436 [FC00::]/7:*" rejects all destinations that share 7 most
2437 significant bit prefix with address FC00::. Respectively, "accept6
2438 [C000::]/3:*" accepts all destinations that share 3 most
2439 significant bit prefix with address C000::.
2440 accept6 and reject6 only produce IPv6 exit policy entries. Using an
2443 IPv4 address with accept6 or reject6 is ignored and generates a
2444 warning. accept/reject allows either IPv4 or IPv6 addresses. Use *4
2445 as an IPv4 wildcard address, and *6 as an IPv6 wildcard address.
2446 accept/reject * expands to matching IPv4 and IPv6 wildcard address
2447 rules.
2448 To specify all IPv4 and IPv6 internal and link-local networks
2451 (including 0.0.0.0/8, 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16,
2452 10.0.0.0/8, 172.16.0.0/12, [::]/8, [FC00::]/7, [FE80::]/10,
2453 [FEC0::]/10, [FF00::]/8, and [::]/127), you can use the "private"
2454 alias instead of an address. ("private" always produces rules for
2455 IPv4 and IPv6 addresses, even when used with accept6/reject6.)
2456 Private addresses are rejected by default (at the beginning of your
2459 exit policy), along with any configured primary public IPv4 and
2460 IPv6 addresses. These private addresses are rejected unless you set
2461 the ExitPolicyRejectPrivate config option to 0. For example, once
2462 you’ve done that, you could allow HTTP to 127.0.0.1 and block all
2463 other connections to internal networks with "accept
2464 127.0.0.1:80,reject private:*", though that may also allow
2465 connections to your own computer that are addressed to its public
2466 (external) IP address. See RFC 1918 and RFC 3330 for more details
2467 about internal and reserved IP address space. See
2468 ExitPolicyRejectLocalInterfaces if you want to block every address
2469 on the relay, even those that aren’t advertised in the descriptor.
2470 This directive can be specified multiple times so you don’t have to
2473 put it all on one line.
2474 Policies are considered first to last, and the first match wins. If
2477 you want to allow the same ports on IPv4 and IPv6, write your rules
2478 using accept/reject *. If you want to allow different ports on IPv4
2479 and IPv6, write your IPv6 rules using accept6/reject6 *6, and your
2480 IPv4 rules using accept/reject *4. If you want to _replace_ the
2481 default exit policy, end your exit policy with either a reject *:*
2482 or an accept *:*. Otherwise, you’re _augmenting_ (prepending to)
2483 the default exit policy.
2484 If you want to use a reduced exit policy rather than the default
2487 exit policy, set "ReducedExitPolicy 1". If you want to replace the
2488 default exit policy with your custom exit policy, end your exit
2489 policy with either a reject : or an accept :. Otherwise, you’re
2490 augmenting (prepending to) the default or reduced exit policy.
2491 The default exit policy is:
2494 reject *:25
2496 reject *:119
2497 reject *:135-139
2498 reject *:445
2499 reject *:563
2500 reject *:1214
2501 reject *:4661-4666
2502 reject *:6346-6429
2503 reject *:6699
2504 reject *:6881-6999
2505 accept *:*
2506 Since the default exit policy uses accept/reject *, it applies to
2508 both IPv4 and IPv6 addresses.
2509 ExitPolicyRejectLocalInterfaces 0|1
2511 Reject all IPv4 and IPv6 addresses that the relay knows about, at
2512 the beginning of your exit policy. This includes any
2513 OutboundBindAddress, the bind addresses of any port options, such
2514 as ControlPort or DNSPort, and any public IPv4 and IPv6 addresses
2515 on any interface on the relay. (If IPv6Exit is not set, all IPv6
2516 addresses will be rejected anyway.) See above entry on ExitPolicy.
2517 This option is off by default, because it lists all public relay IP
2518 addresses in the ExitPolicy, even those relay operators might
2519 prefer not to disclose. (Default: 0)
2520 ExitPolicyRejectPrivate 0|1
2522 Reject all private (local) networks, along with the relay’s
2523 advertised public IPv4 and IPv6 addresses, at the beginning of your
2524 exit policy. See above entry on ExitPolicy. (Default: 1)
2525 ExitRelay 0|1|auto
2527 Tells Tor whether to run as an exit relay. If Tor is running as a
2528 non-bridge server, and ExitRelay is set to 1, then Tor allows
2529 traffic to exit according to the ExitPolicy option, the
2530 ReducedExitPolicy option, or the default ExitPolicy (if no other
2531 exit policy option is specified).
2532 If ExitRelay is set to 0, no traffic is allowed to exit, and the
2535 ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored.
2536 If ExitRelay is set to "auto", then Tor checks the ExitPolicy,
2539 ReducedExitPolicy, and IPv6Exit options. If at least one of these
2540 options is set, Tor behaves as if ExitRelay were set to 1. If none
2541 of these exit policy options are set, Tor behaves as if ExitRelay
2542 were set to 0. (Default: auto)
2543 ExtendAllowPrivateAddresses 0|1
2545 When this option is enabled, Tor will connect to relays on
2546 localhost, RFC1918 addresses, and so on. In particular, Tor will
2547 make direct OR connections, and Tor routers allow EXTEND requests,
2548 to these private addresses. (Tor will always allow connections to
2549 bridges, proxies, and pluggable transports configured on private
2550 addresses.) Enabling this option can create security issues; you
2551 should probably leave it off. (Default: 0)
2552 GeoIPFile filename
2554 A filename containing IPv4 GeoIP data, for use with by-country
2555 statistics.
2556 GeoIPv6File filename
2558 A filename containing IPv6 GeoIP data, for use with by-country
2559 statistics.
2560 HeartbeatPeriod N minutes|hours|days|weeks
2562 Log a heartbeat message every HeartbeatPeriod seconds. This is a
2563 log level notice message, designed to let you know your Tor server
2564 is still alive and doing useful things. Settings this to 0 will
2565 disable the heartbeat. Otherwise, it must be at least 30 minutes.
2566 (Default: 6 hours)
2567 IPv6Exit 0|1
2569 If set, and we are an exit node, allow clients to use us for IPv6
2570 traffic. When this option is set and ExitRelay is auto, we act as
2571 if ExitRelay is 1. (Default: 0)
2572 KeyDirectory DIR
2574 Store secret keys in DIR. Can not be changed while tor is running.
2575 (Default: the "keys" subdirectory of DataDirectory.)
2576 KeyDirectoryGroupReadable 0|1|auto
2578 If this option is set to 0, don’t allow the filesystem group to
2579 read the KeyDirectory. If the option is set to 1, make the
2580 KeyDirectory readable by the default GID. If the option is "auto",
2581 then we use the setting for DataDirectoryGroupReadable when the
2582 KeyDirectory is the same as the DataDirectory, and 0 otherwise.
2583 (Default: auto)
2584 MainloopStats 0|1
2586 Log main loop statistics every HeartbeatPeriod seconds. This is a
2587 log level notice message designed to help developers instrumenting
2588 Tor’s main event loop. (Default: 0)
2589 MaxMemInQueues N bytes|KBytes|MBytes|GBytes
2591 This option configures a threshold above which Tor will assume that
2592 it needs to stop queueing or buffering data because it’s about to
2593 run out of memory. If it hits this threshold, it will begin killing
2594 circuits until it has recovered at least 10% of this memory. Do not
2595 set this option too low, or your relay may be unreliable under
2596 load. This option only affects some queues, so the actual process
2597 size will be larger than this. If this option is set to 0, Tor will
2598 try to pick a reasonable default based on your system’s physical
2599 memory. (Default: 0)
2600 MaxOnionQueueDelay NUM [msec|second]
2602 If we have more onionskins queued for processing than we can
2603 process in this amount of time, reject new ones. (Default: 1750
2604 msec)
2605 MyFamily fingerprint,fingerprint,...
2607 Declare that this Tor relay is controlled or administered by a
2608 group or organization identical or similar to that of the other
2609 relays, defined by their (possibly $-prefixed) identity
2610 fingerprints. This option can be repeated many times, for
2611 convenience in defining large families: all fingerprints in all
2612 MyFamily lines are merged into one list. When two relays both
2613 declare that they are in the same 'family', Tor clients will not
2614 use them in the same circuit. (Each relay only needs to list the
2615 other servers in its family; it doesn’t need to list itself, but it
2616 won’t hurt if it does.) Do not list any bridge relay as it would
2617 compromise its concealment.
2618 If you run more than one relay, the MyFamily option on each relay
2621 must list all other relays, as described above.
2622 Note: do not use MyFamily when configuring your Tor instance as a
2625 bridge.
2626 Nickname name
2628 Set the server’s nickname to 'name'. Nicknames must be between 1
2629 and 19 characters inclusive, and must contain only the characters
2630 [a-zA-Z0-9]. If not set, Unnamed will be used. Relays can always be
2631 uniquely identified by their identity fingerprints.
2632 NumCPUs num
2634 How many processes to use at once for decrypting onionskins and
2635 other parallelizable operations. If this is set to 0, Tor will try
2636 to detect how many CPUs you have, defaulting to 1 if it can’t tell.
2637 (Default: 0)
2638 OfflineMasterKey 0|1
2640 If non-zero, the Tor relay will never generate or load its master
2641 secret key. Instead, you’ll have to use "tor --keygen" to manage
2642 the permanent ed25519 master identity key, as well as the
2643 corresponding temporary signing keys and certificates. (Default: 0)
2644 ORPort [address:]PORT|auto [flags]
2646 Advertise this port to listen for connections from Tor clients and
2647 servers. This option is required to be a Tor server. Set it to
2648 "auto" to have Tor pick a port for you. Set it to 0 to not run an
2649 ORPort at all. This option can occur more than once. (Default: 0)
2650 Tor recognizes these flags on each ORPort:
2653 NoAdvertise
2655 By default, we bind to a port and tell our users about it. If
2656 NoAdvertise is specified, we don’t advertise, but listen
2657 anyway. This can be useful if the port everybody will be
2658 connecting to (for example, one that’s opened on our firewall)
2659 is somewhere else.
2660 NoListen
2662 By default, we bind to a port and tell our users about it. If
2663 NoListen is specified, we don’t bind, but advertise anyway.
2664 This can be useful if something else (for example, a firewall’s
2665 port forwarding configuration) is causing connections to reach
2666 us.
2667 IPv4Only
2669 If the address is absent, or resolves to both an IPv4 and an
2670 IPv6 address, only listen to the IPv4 address.
2671 IPv6Only
2673 If the address is absent, or resolves to both an IPv4 and an
2674 IPv6 address, only listen to the IPv6 address.
2675 For obvious reasons, NoAdvertise and NoListen are mutually
2677 exclusive, and IPv4Only and IPv6Only are mutually exclusive.
2678 PublishServerDescriptor 0|1|v3|bridge,...
2680 This option specifies which descriptors Tor will publish when
2681 acting as a relay. You can choose multiple arguments, separated by
2682 commas.
2683 If this option is set to 0, Tor will not publish its descriptors to
2686 any directories. (This is useful if you’re testing out your server,
2687 or if you’re using a Tor controller that handles directory
2688 publishing for you.) Otherwise, Tor will publish its descriptors of
2689 all type(s) specified. The default is "1", which means "if running
2690 as a relay or bridge, publish descriptors to the appropriate
2691 authorities". Other possibilities are "v3", meaning "publish as if
2692 you’re a relay", and "bridge", meaning "publish as if you’re a
2693 bridge".
2694 ReducedExitPolicy 0|1
2696 If set, use a reduced exit policy rather than the default one.
2697 The reduced exit policy is an alternative to the default exit
2700 policy. It allows as many Internet services as possible while still
2701 blocking the majority of TCP ports. Currently, the policy allows
2702 approximately 65 ports. This reduces the odds that your node will
2703 be used for peer-to-peer applications.
2704 The reduced exit policy is:
2707 accept *:20-21
2709 accept *:22
2710 accept *:23
2711 accept *:43
2712 accept *:53
2713 accept *:79
2714 accept *:80-81
2715 accept *:88
2716 accept *:110
2717 accept *:143
2718 accept *:194
2719 accept *:220
2720 accept *:389
2721 accept *:443
2722 accept *:464
2723 accept *:465
2724 accept *:531
2725 accept *:543-544
2726 accept *:554
2727 accept *:563
2728 accept *:587
2729 accept *:636
2730 accept *:706
2731 accept *:749
2732 accept *:873
2733 accept *:902-904
2734 accept *:981
2735 accept *:989-990
2736 accept *:991
2737 accept *:992
2738 accept *:993
2739 accept *:994
2740 accept *:995
2741 accept *:1194
2742 accept *:1220
2743 accept *:1293
2744 accept *:1500
2745 accept *:1533
2746 accept *:1677
2747 accept *:1723
2748 accept *:1755
2749 accept *:1863
2750 accept *:2082
2751 accept *:2083
2752 accept *:2086-2087
2753 accept *:2095-2096
2754 accept *:2102-2104
2755 accept *:3128
2756 accept *:3389
2757 accept *:3690
2758 accept *:4321
2759 accept *:4643
2760 accept *:5050
2761 accept *:5190
2762 accept *:5222-5223
2763 accept *:5228
2764 accept *:5900
2765 accept *:6660-6669
2766 accept *:6679
2767 accept *:6697
2768 accept *:8000
2769 accept *:8008
2770 accept *:8074
2771 accept *:8080
2772 accept *:8082
2773 accept *:8087-8088
2774 accept *:8232-8233
2775 accept *:8332-8333
2776 accept *:8443
2777 accept *:8888
2778 accept *:9418
2779 accept *:9999
2780 accept *:10000
2781 accept *:11371
2782 accept *:19294
2783 accept *:19638
2784 accept *:50002
2785 accept *:64738
2786 reject *:*
2787 (Default: 0)
2789 RefuseUnknownExits 0|1|auto
2791 Prevent nodes that don’t appear in the consensus from exiting using
2792 this relay. If the option is 1, we always block exit attempts from
2793 such nodes; if it’s 0, we never do, and if the option is "auto",
2794 then we do whatever the authorities suggest in the consensus (and
2795 block if the consensus is quiet on the issue). (Default: auto)
2796 ServerDNSAllowBrokenConfig 0|1
2798 If this option is false, Tor exits immediately if there are
2799 problems parsing the system DNS configuration or connecting to
2800 nameservers. Otherwise, Tor continues to periodically retry the
2801 system nameservers until it eventually succeeds. (Default: 1)
2802 ServerDNSAllowNonRFC953Hostnames 0|1
2804 When this option is disabled, Tor does not try to resolve hostnames
2805 containing illegal characters (like @ and :) rather than sending
2806 them to an exit node to be resolved. This helps trap accidental
2807 attempts to resolve URLs and so on. This option only affects name
2808 lookups that your server does on behalf of clients. (Default: 0)
2809 ServerDNSDetectHijacking 0|1
2811 When this option is set to 1, we will test periodically to
2812 determine whether our local nameservers have been configured to
2813 hijack failing DNS requests (usually to an advertising site). If
2814 they are, we will attempt to correct this. This option only affects
2815 name lookups that your server does on behalf of clients. (Default:
2816 1)
2817 ServerDNSRandomizeCase 0|1
2819 When this option is set, Tor sets the case of each character
2820 randomly in outgoing DNS requests, and makes sure that the case
2821 matches in DNS replies. This so-called "0x20 hack" helps resist
2822 some types of DNS poisoning attack. For more information, see
2823 "Increased DNS Forgery Resistance through 0x20-Bit Encoding". This
2824 option only affects name lookups that your server does on behalf of
2825 clients. (Default: 1)
2826 ServerDNSResolvConfFile filename
2828 Overrides the default DNS configuration with the configuration in
2829 filename. The file format is the same as the standard Unix
2830 "resolv.conf" file (7). This option, like all other ServerDNS
2831 options, only affects name lookups that your server does on behalf
2832 of clients. (Defaults to use the system DNS configuration or a
2833 localhost DNS service in case no nameservers are found in a given
2834 configuration.)
2835 ServerDNSSearchDomains 0|1
2837 If set to 1, then we will search for addresses in the local search
2838 domain. For example, if this system is configured to believe it is
2839 in "example.com", and a client tries to connect to "www", the
2840 client will be connected to "www.example.com". This option only
2841 affects name lookups that your server does on behalf of clients.
2842 (Default: 0)
2843 ServerDNSTestAddresses hostname,hostname,...
2845 When we’re detecting DNS hijacking, make sure that these valid
2846 addresses aren’t getting redirected. If they are, then our DNS is
2847 completely useless, and we’ll reset our exit policy to "reject
2848 *:*". This option only affects name lookups that your server does
2849 on behalf of clients. (Default: "www.google.com, www.mit.edu,
2850 www.yahoo.com, www.slashdot.org")
2851 ServerTransportListenAddr transport IP:PORT
2853 When this option is set, Tor will suggest IP:PORT as the listening
2854 address of any pluggable transport proxy that tries to launch
2855 transport. (IPv4 addresses should written as-is; IPv6 addresses
2856 should be wrapped in square brackets.) (Default: none)
2857 ServerTransportOptions transport k=v k=v ...
2859 When this option is set, Tor will pass the k=v parameters to any
2860 pluggable transport proxy that tries to launch transport.
2861 (Example: ServerTransportOptions obfs45 shared-secret=bridgepasswd
2863 cache=/var/lib/tor/cache) (Default: none)
2864 ServerTransportPlugin transport exec path-to-binary [options]
2866 The Tor relay launches the pluggable transport proxy in
2867 path-to-binary using options as its command-line options, and
2868 expects to receive proxied client traffic from it. (Default: none)
2869 ShutdownWaitLength NUM
2871 When we get a SIGINT and we’re a server, we begin shutting down: we
2872 close listeners and start refusing new circuits. After NUM seconds,
2873 we exit. If we get a second SIGINT, we exit immediately. (Default:
2874 30 seconds)
2875 SigningKeyLifetime N days|weeks|months
2877 For how long should each Ed25519 signing key be valid? Tor uses a
2878 permanent master identity key that can be kept offline, and
2879 periodically generates new "signing" keys that it uses online. This
2880 option configures their lifetime. (Default: 30 days)
2881 SSLKeyLifetime N minutes|hours|days|weeks
2883 When creating a link certificate for our outermost SSL handshake,
2884 set its lifetime to this amount of time. If set to 0, Tor will
2885 choose some reasonable random defaults. (Default: 0)
2886
2888 Relays publish most statistics in a document called the extra-info
2889 document. The following options affect the different types of
2890 statistics that Tor relays collect and publish:
2891 BridgeRecordUsageByCountry 0|1
2893 When this option is enabled and BridgeRelay is also enabled, and we
2894 have GeoIP data, Tor keeps a per-country count of how many client
2895 addresses have contacted it so that it can help the bridge
2896 authority guess which countries have blocked access to it. If
2897 ExtraInfoStatistics is enabled, it will be published as part of the
2898 extra-info document. (Default: 1)
2899 CellStatistics 0|1
2901 Relays only. When this option is enabled, Tor collects statistics
2902 about cell processing (i.e. mean time a cell is spending in a
2903 queue, mean number of cells in a queue and mean number of processed
2904 cells per circuit) and writes them into disk every 24 hours. Onion
2905 router operators may use the statistics for performance monitoring.
2906 If ExtraInfoStatistics is enabled, it will published as part of the
2907 extra-info document. (Default: 0)
2908 ConnDirectionStatistics 0|1
2910 Relays only. When this option is enabled, Tor writes statistics on
2911 the amounts of traffic it passes between itself and other relays to
2912 disk every 24 hours. Enables relay operators to monitor how much
2913 their relay is being used as middle node in the circuit. If
2914 ExtraInfoStatistics is enabled, it will be published as part of the
2915 extra-info document. (Default: 0)
2916 DirReqStatistics 0|1
2918 Relays and bridges only. When this option is enabled, a Tor
2919 directory writes statistics on the number and response time of
2920 network status requests to disk every 24 hours. Enables relay and
2921 bridge operators to monitor how much their server is being used by
2922 clients to learn about Tor network. If ExtraInfoStatistics is
2923 enabled, it will published as part of the extra-info document.
2924 (Default: 1)
2925 EntryStatistics 0|1
2927 Relays only. When this option is enabled, Tor writes statistics on
2928 the number of directly connecting clients to disk every 24 hours.
2929 Enables relay operators to monitor how much inbound traffic that
2930 originates from Tor clients passes through their server to go
2931 further down the Tor network. If ExtraInfoStatistics is enabled, it
2932 will be published as part of the extra-info document. (Default: 0)
2933 ExitPortStatistics 0|1
2935 Exit relays only. When this option is enabled, Tor writes
2936 statistics on the number of relayed bytes and opened stream per
2937 exit port to disk every 24 hours. Enables exit relay operators to
2938 measure and monitor amounts of traffic that leaves Tor network
2939 through their exit node. If ExtraInfoStatistics is enabled, it will
2940 be published as part of the extra-info document. (Default: 0)
2941 ExtraInfoStatistics 0|1
2943 When this option is enabled, Tor includes previously gathered
2944 statistics in its extra-info documents that it uploads to the
2945 directory authorities. Disabling this option also removes bandwidth
2946 usage statistics, and GeoIPFile and GeoIPv6File hashes from the
2947 extra-info file. Bridge ServerTransportPlugin lines are always
2948 included in the extra-info file, because they are required by
2949 BridgeDB. (Default: 1)
2950 HiddenServiceStatistics 0|1
2952 Relays and bridges only. When this option is enabled, a Tor relay
2953 writes obfuscated statistics on its role as hidden-service
2954 directory, introduction point, or rendezvous point to disk every 24
2955 hours. If ExtraInfoStatistics is enabled, it will be published as
2956 part of the extra-info document. (Default: 1)
2957 OverloadStatistics 0|1*
2959 Relays and bridges only. When this option is enabled, a Tor relay
2960 will write an overload general line in the server descriptor if the
2961 relay is considered overloaded. (Default: 1)
2962 A relay is considered overloaded if at least one of these
2964 conditions is met:
2965 • Onionskins are starting to be dropped.
2967 • The OOM was invoked.
2969 • (Exit only) DNS timeout occurs X% of the time over Y seconds
2971 (values controlled by consensus parameters, see
2972 param-spec.txt).
2973 If ExtraInfoStatistics is enabled, it can also put two more
2975 specific overload lines in the extra-info document if at least
2976 one of these conditions is met:
2977 • TCP Port exhaustion.
2979 • Connection rate limits have been reached (read and write side).
2981 PaddingStatistics 0|1
2983 Relays and bridges only. When this option is enabled, Tor collects
2984 statistics for padding cells sent and received by this relay, in
2985 addition to total cell counts. These statistics are rounded, and
2986 omitted if traffic is low. This information is important for load
2987 balancing decisions related to padding. If ExtraInfoStatistics is
2988 enabled, it will be published as a part of the extra-info document.
2989 (Default: 1)
2990
2992 The following options are useful only for directory servers. (Relays
2993 with enough bandwidth automatically become directory servers; see
2994 DirCache for details.)
2995 DirCache 0|1
2997 When this option is set, Tor caches all current directory documents
2998 except extra info documents, and accepts client requests for them.
2999 If DownloadExtraInfo is set, cached extra info documents are also
3000 cached. Setting DirPort is not required for DirCache, because
3001 clients connect via the ORPort by default. Setting either DirPort
3002 or BridgeRelay and setting DirCache to 0 is not supported.
3003 (Default: 1)
3004 DirPolicy policy,policy,...
3006 Set an entrance policy for this server, to limit who can connect to
3007 the directory ports. The policies have the same form as exit
3008 policies above, except that port specifiers are ignored. Any
3009 address not matched by some entry in the policy is accepted.
3010 DirPort [address:]PORT|auto [flags]
3012 If this option is nonzero, advertise the directory service on this
3013 port. Set it to "auto" to have Tor pick a port for you. This option
3014 can occur more than once, but only one advertised DirPort is
3015 supported: all but one DirPort must have the NoAdvertise flag set.
3016 (Default: 0)
3017 The same flags are supported here as are supported by ORPort. This
3020 port can only be IPv4.
3021 As of Tor 0.4.6.1-alpha, non-authoritative relays (see
3023 AuthoritativeDirectory) will not publish the DirPort but will still
3024 listen on it. Clients don’t use the DirPorts on relays, so it is
3025 safe for you to remove the DirPort from your torrc configuration.
3026 DirPortFrontPage FILENAME
3028 When this option is set, it takes an HTML file and publishes it as
3029 "/" on the DirPort. Now relay operators can provide a disclaimer
3030 without needing to set up a separate webserver. There’s a sample
3031 disclaimer in contrib/operator-tools/tor-exit-notice.html.
3032 MaxConsensusAgeForDiffs N minutes|hours|days|weeks
3034 When this option is nonzero, Tor caches will not try to generate
3035 consensus diffs for any consensus older than this amount of time.
3036 If this option is set to zero, Tor will pick a reasonable default
3037 from the current networkstatus document. You should not set this
3038 option unless your cache is severely low on disk space or CPU. If
3039 you need to set it, keeping it above 3 or 4 hours will help clients
3040 much more than setting it to zero. (Default: 0)
3041
3043 Tor has a series of built-in denial of service mitigation options that
3044 can be individually enabled/disabled and fine-tuned, but by default Tor
3045 directory authorities will define reasonable values for the network and
3046 no explicit configuration is required to make use of these protections.
3047 The following is a series of configuration options for relays and then
3049 options for onion services and how they work.
3050 The mitigations take place at relays, and are as follows:
3052 1. If a single client address makes too many concurrent connections
3054 (this is configurable via DoSConnectionMaxConcurrentCount), hang up
3055 on further connections.
3056 2. If a single client IP address (v4 or v6) makes circuits too quickly
3058 (default values are more than 3 per second, with an allowed burst
3059 of 90, see DoSCircuitCreationRate and DoSCircuitCreationBurst)
3060 while also having too many connections open (default is 3, see
3061 DoSCircuitCreationMinConnections), tor will refuse any new circuit
3062 (CREATE cells) for the next while (random value between 1 and 2
3063 hours).
3064 3. If a client asks to establish a rendezvous point to you directly
3066 (ex: Tor2Web client), ignore the request.
3067 These defenses can be manually controlled by torrc options, but relays
3069 will also take guidance from consensus parameters using these same
3070 names, so there’s no need to configure anything manually. In doubt, do
3071 not change those values.
3072 The values set by the consensus, if any, can be found here:
3074 https://consensus-health.torproject.org/#consensusparams
3075 If any of the DoS mitigations are enabled, a heartbeat message will
3077 appear in your log at NOTICE level which looks like:
3078 DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses.
3080 2238 connections closed. 8052 single hop clients refused.
3081 The following options are useful only for a public relay. They control
3083 the Denial of Service mitigation subsystem described above.
3084 DoSCircuitCreationEnabled 0|1|auto
3086 Enable circuit creation DoS mitigation. If set to 1 (enabled), tor
3087 will cache client IPs along with statistics in order to detect
3088 circuit DoS attacks. If an address is positively identified, tor
3089 will activate defenses against the address. See
3090 DoSCircuitCreationDefenseType option for more details. This is a
3091 client to relay detection only. "auto" means use the consensus
3092 parameter. If not defined in the consensus, the value is 0.
3093 (Default: auto)
3094 DoSCircuitCreationBurst NUM
3096 The allowed circuit creation burst per client IP address. If the
3097 circuit rate and the burst are reached, a client is marked as
3098 executing a circuit creation DoS. "0" means use the consensus
3099 parameter. If not defined in the consensus, the value is 90.
3100 (Default: 0)
3101 DoSCircuitCreationDefenseTimePeriod N seconds|minutes|hours
3103 The base time period in seconds that the DoS defense is activated
3104 for. The actual value is selected randomly for each activation from
3105 N+1 to 3/2 * N. "0" means use the consensus parameter. If not
3106 defined in the consensus, the value is 3600 seconds (1 hour).
3107 (Default: 0)
3108 DoSCircuitCreationDefenseType NUM
3110 This is the type of defense applied to a detected client address.
3111 The possible values are:
3112 1: No defense.
3114 2: Refuse circuit creation for the
3116 DoSCircuitCreationDefenseTimePeriod period of time.
3117 "0" means use the consensus parameter. If not defined in the
3119 consensus, the value is 2. (Default: 0)
3120 DoSCircuitCreationMinConnections NUM
3122 Minimum threshold of concurrent connections before a client address
3123 can be flagged as executing a circuit creation DoS. In other words,
3124 once a client address reaches the circuit rate and has a minimum of
3125 NUM concurrent connections, a detection is positive. "0" means use
3126 the consensus parameter. If not defined in the consensus, the value
3127 is 3. (Default: 0)
3128 DoSCircuitCreationRate NUM
3130 The allowed circuit creation rate per second applied per client IP
3131 address. If this option is 0, it obeys a consensus parameter. If
3132 not defined in the consensus, the value is 3. (Default: 0)
3133 DoSConnectionEnabled 0|1|auto
3135 Enable the connection DoS mitigation. If set to 1 (enabled), for
3136 client address only, this allows tor to mitigate against large
3137 number of concurrent connections made by a single IP address.
3138 "auto" means use the consensus parameter. If not defined in the
3139 consensus, the value is 0. (Default: auto)
3140 DoSConnectionDefenseType NUM
3142 This is the type of defense applied to a detected client address
3143 for the connection mitigation. The possible values are:
3144 1: No defense.
3146 2: Immediately close new connections.
3148 "0" means use the consensus parameter. If not defined in the
3150 consensus, the value is 2. (Default: 0)
3151 DoSConnectionMaxConcurrentCount NUM
3153 The maximum threshold of concurrent connection from a client IP
3154 address. Above this limit, a defense selected by
3155 DoSConnectionDefenseType is applied. "0" means use the consensus
3156 parameter. If not defined in the consensus, the value is 100.
3157 (Default: 0)
3158 DoSConnectionConnectRate NUM
3160 The allowed rate of client connection from a single address per
3161 second. Coupled with the burst (see below), if the limit is
3162 reached, the address is marked and a defense is applied
3163 (DoSConnectionDefenseType) for a period of time defined by
3164 DoSConnectionConnectDefenseTimePeriod. If not defined or set to 0,
3165 it is controlled by a consensus parameter. (Default: 0)
3166 DoSConnectionConnectBurst NUM
3168 The allowed burst of client connection from a single address per
3169 second. See the DoSConnectionConnectRate for more details on this
3170 detection. If not defined or set to 0, it is controlled by a
3171 consensus parameter. (Default: 0)
3172 DoSConnectionConnectDefenseTimePeriod N seconds|minutes|hours
3174 The base time period in seconds that the client connection defense
3175 is activated for. The actual value is selected randomly for each
3176 activation from N+1 to 3/2 * N. If not defined or set to 0, it is
3177 controlled by a consensus parameter. (Default: 24 hours)
3178 DoSRefuseSingleHopClientRendezvous 0|1|auto
3180 Refuse establishment of rendezvous points for single hop clients.
3181 In other words, if a client directly connects to the relay and
3182 sends an ESTABLISH_RENDEZVOUS cell, it is silently dropped. "auto"
3183 means use the consensus parameter. If not defined in the consensus,
3184 the value is 0. (Default: auto)
3185 For onion services, mitigations are a work in progress and multiple
3187 options are currently available.
3188 The introduction point defense is a rate limit on the number of
3190 introduction requests that will be forwarded to a service by each of
3191 its honest introduction point routers. This can prevent some types of
3192 overwhelming floods from reaching the service, but it will also prevent
3193 legitimate clients from establishing new connections.
3194 The following options are per onion service:
3196 HiddenServiceEnableIntroDoSDefense 0|1
3198 Enable DoS defense at the intropoint level. When this is enabled,
3199 the rate and burst parameter (see below) will be sent to the intro
3200 point which will then use them to apply rate limiting for
3201 introduction request to this service.
3202 The introduction point honors the consensus parameters except if
3204 this is specifically set by the service operator using this option.
3205 The service never looks at the consensus parameters in order to
3206 enable or disable this defense. (Default: 0)
3207 HiddenServiceEnableIntroDoSBurstPerSec NUM
3209 The allowed client introduction burst per second at the
3210 introduction point. If this option is 0, it is considered infinite
3211 and thus if HiddenServiceEnableIntroDoSDefense is set, it then
3212 effectively disables the defenses. (Default: 200)
3213 HiddenServiceEnableIntroDoSRatePerSec NUM
3215 The allowed client introduction rate per second at the introduction
3216 point. If this option is 0, it is considered infinite and thus if
3217 HiddenServiceEnableIntroDoSDefense is set, it then effectively
3218 disables the defenses. (Default: 25)
3219 The rate is the maximum number of clients a service will ask its
3221 introduction points to allow every seconds. And the burst is a
3222 parameter that allows that many within one second.
3223 For example, the default values of 25 and 200 respectively means that
3225 for every introduction points a service has (default 3 but can be
3226 configured with HiddenServiceNumIntroductionPoints), 25 clients per
3227 seconds will be allowed to reach the service and 200 at most within 1
3228 second as a burst. This means that if 200 clients are seen within 1
3229 second, it will take 8 seconds (200/25) for another client to be able
3230 to be allowed to introduce due to the rate of 25 per second.
3231 This might be too much for your use case or not, fine tuning these
3233 values is hard and are likely different for each service operator.
3234 Why is this not helping reachability of the service? Because the
3236 defenses are at the introduction point, an attacker can easily flood
3237 all introduction point rendering the service unavailable due to no
3238 client being able to pass through. But, the service itself is not
3239 overwhelmed with connetions allowing it to function properly for the
3240 few clients that were able to go through or other any services running
3241 on the same tor instance.
3242 The bottom line is that this protects the network by preventing an
3244 onion service to flood the network with new rendezvous circuits that is
3245 reducing load on the network.
3246 A secondary mitigation is available, based on prioritized dispatch of
3248 rendezvous circuits for new connections. The queue is ordered based on
3249 effort a client chooses to spend at computing a proof-of-work function.
3250 The following options are per onion service:
3252 HiddenServicePoWDefensesEnabled 0|1
3254 Enable proof-of-work based service DoS mitigation. If set to 1
3255 (enabled), tor will include parameters for an optional client
3256 puzzle in the encrypted portion of this hidden service’s
3257 descriptor. Incoming rendezvous requests will be prioritized based
3258 on the amount of effort a client chooses to make when computing a
3259 solution to the puzzle. The service will periodically update a
3260 suggested amount of effort, based on attack load, and disable the
3261 puzzle entirely when the service is not overloaded. (Default: 0)
3262 HiddenServicePoWQueueRate NUM
3264 The sustained rate of rendezvous requests to dispatch per second
3265 from the priority queue. Has no effect when proof-of-work is
3266 disabled. If this is set to 0 there’s no explicit limit and we will
3267 process requests as quickly as possible. (Default: 250)
3268 HiddenServicePoWQueueBurst NUM
3270 The maximum burst size for rendezvous requests handled from the
3271 priority queue at once. (Default: 2500)
3272 These options are applicable to both onion services and their clients:
3274 CompiledProofOfWorkHash 0|1|auto
3276 When proof-of-work DoS mitigation is active, both the services
3277 themselves and the clients which connect will use a dynamically
3278 generated hash function as part of the puzzle computation.
3279 If this option is set to 1, puzzles will only be solved and
3281 verified using the compiled implementation (about 20x faster) and
3282 we choose to fail rather than using a slower fallback. If it’s 0,
3283 the compiler will never be used. By default, the compiler is always
3284 tried if possible but the interpreter is available as a fallback.
3285 (Default: auto)
3286 See also --list-modules, these proof of work options have no effect
3288 unless the "pow" module is enabled at compile time.
3289
3291 The following options enable operation as a directory authority, and
3292 control how Tor behaves as a directory authority. You should not need
3293 to adjust any of them if you’re running a regular relay or exit server
3294 on the public Tor network.
3295 AuthoritativeDirectory 0|1
3297 When this option is set to 1, Tor operates as an authoritative
3298 directory server. Instead of caching the directory, it generates
3299 its own list of good servers, signs it, and sends that to the
3300 clients. Unless the clients already have you listed as a trusted
3301 directory, you probably do not want to set this option.
3302 BridgeAuthoritativeDir 0|1
3304 When this option is set in addition to AuthoritativeDirectory, Tor
3305 accepts and serves server descriptors, but it caches and serves the
3306 main networkstatus documents rather than generating its own.
3307 (Default: 0)
3308 V3AuthoritativeDirectory 0|1
3310 When this option is set in addition to AuthoritativeDirectory, Tor
3311 generates version 3 network statuses and serves descriptors, etc as
3312 described in dir-spec.txt file of torspec (for Tor clients and
3313 servers running at least 0.2.0.x).
3314 AuthDirBadExit AddressPattern...
3316 Authoritative directories only. A set of address patterns for
3317 servers that will be listed as bad exits in any network status
3318 document this authority publishes, if AuthDirListBadExits is set.
3319 (The address pattern syntax here and in the options below is the
3322 same as for exit policies, except that you don’t need to say
3323 "accept" or "reject", and ports are not needed.)
3324 AuthDirMiddleOnly AddressPattern...
3326 Authoritative directories only. A set of address patterns for
3327 servers that will be listed as middle-only in any network status
3328 document this authority publishes, if AuthDirListMiddleOnly is set.
3329 AuthDirFastGuarantee N
3331 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3332 Authoritative directories only. If non-zero, always vote the Fast
3333 flag for any relay advertising this amount of capacity or more.
3334 (Default: 100 KBytes)
3335 AuthDirGuardBWGuarantee N
3337 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3338 Authoritative directories only. If non-zero, this advertised
3339 capacity or more is always sufficient to satisfy the bandwidth
3340 requirement for the Guard flag. (Default: 2 MBytes)
3341 AuthDirHasIPv6Connectivity 0|1
3343 Authoritative directories only. When set to 0, OR ports with an
3344 IPv6 address are not included in the authority’s votes. When set to
3345 1, IPv6 OR ports are tested for reachability like IPv4 OR ports. If
3346 the reachability test succeeds, the authority votes for the IPv6
3347 ORPort, and votes Running for the relay. If the reachability test
3348 fails, the authority does not vote for the IPv6 ORPort, and does
3349 not vote Running (Default: 0)
3350 The content of the consensus depends on the number of voting authorities
3353 that set AuthDirHasIPv6Connectivity:
3354 If no authorities set AuthDirHasIPv6Connectivity 1, there will be no
3356 IPv6 ORPorts in the consensus.
3357 If a minority of authorities set AuthDirHasIPv6Connectivity 1,
3359 unreachable IPv6 ORPorts will be removed from the consensus. But the
3360 majority of IPv4-only authorities will still vote the relay as Running.
3361 Reachable IPv6 ORPort lines will be included in the consensus
3362 If a majority of voting authorities set AuthDirHasIPv6Connectivity 1,
3364 relays with unreachable IPv6 ORPorts will not be listed as Running.
3365 Reachable IPv6 ORPort lines will be included in the consensus
3366 (To ensure that any valid majority will vote relays with unreachable
3367 IPv6 ORPorts not Running, 75% of authorities must set
3368 AuthDirHasIPv6Connectivity 1.)
3369 AuthDirInvalid AddressPattern...
3371 Authoritative directories only. A set of address patterns for
3372 servers that will never be listed as "valid" in any network status
3373 document that this authority publishes.
3374 AuthDirListBadExits 0|1
3376 Authoritative directories only. If set to 1, this directory has
3377 some opinion about which nodes are unsuitable as exit nodes. (Do
3378 not set this to 1 unless you plan to list non-functioning exits as
3379 bad; otherwise, you are effectively voting in favor of every
3380 declared exit as an exit.)
3381 AuthDirListMiddleOnly 0|1
3383 Authoritative directories only. If set to 1, this directory has
3384 some opinion about which nodes should only be used in the middle
3385 position. (Do not set this to 1 unless you plan to list
3386 questionable relays as "middle only"; otherwise, you are
3387 effectively voting against middle-only status for every relay.)
3388 AuthDirMaxServersPerAddr NUM
3390 Authoritative directories only. The maximum number of servers that
3391 we will list as acceptable on a single IP address. Set this to "0"
3392 for "no limit". (Default: 2)
3393 AuthDirPinKeys 0|1
3395 Authoritative directories only. If non-zero, do not allow any relay
3396 to publish a descriptor if any other relay has reserved its
3397 <Ed25519,RSA> identity keypair. In all cases, Tor records every
3398 keypair it accepts in a journal if it is new, or if it differs from
3399 the most recently accepted pinning for one of the keys it contains.
3400 (Default: 1)
3401 AuthDirReject AddressPattern...
3403 Authoritative directories only. A set of address patterns for
3404 servers that will never be listed at all in any network status
3405 document that this authority publishes, or accepted as an OR
3406 address in any descriptor submitted for publication by this
3407 authority.
3408 AuthDirRejectRequestsUnderLoad 0|1
3410 If set, the directory authority will start rejecting directory
3411 requests from non relay connections by sending a 503 error code if
3412 it is under bandwidth pressure (reaching the configured limit if
3413 any). Relays will always tried to be answered even if this is on.
3414 (Default: 1)
3415 AuthDirBadExitCCs CC,...
3417 AuthDirInvalidCCs CC,...
3419 AuthDirMiddleOnlyCCs CC,...
3421 AuthDirRejectCCs CC,...
3423 Authoritative directories only. These options contain a
3424 comma-separated list of country codes such that any server in one
3425 of those country codes will be marked as a bad exit/invalid for
3426 use, or rejected entirely.
3427 AuthDirSharedRandomness 0|1
3429 Authoritative directories only. Switch for the shared random
3430 protocol. If zero, the authority won’t participate in the protocol.
3431 If non-zero (default), the flag "shared-rand-participate" is added
3432 to the authority vote indicating participation in the protocol.
3433 (Default: 1)
3434 AuthDirTestEd25519LinkKeys 0|1
3436 Authoritative directories only. If this option is set to 0, then we
3437 treat relays as "Running" if their RSA key is correct when we probe
3438 them, regardless of their Ed25519 key. We should only ever set this
3439 option to 0 if there is some major bug in Ed25519 link
3440 authentication that causes us to label all the relays as not
3441 Running. (Default: 1)
3442 AuthDirTestReachability 0|1
3444 Authoritative directories only. If set to 1, then we periodically
3445 check every relay we know about to see whether it is running. If
3446 set to 0, we vote Running for every relay, and don’t perform these
3447 tests. (Default: 1)
3448 AuthDirVoteGuard node,node,...
3450 A list of identity fingerprints or country codes or address
3451 patterns of nodes to vote Guard for regardless of their uptime and
3452 bandwidth. See ExcludeNodes for more information on how to specify
3453 nodes.
3454 AuthDirVoteGuardBwThresholdFraction FRACTION
3456 The Guard flag bandwidth performance threshold fraction that is the
3457 fraction representing who gets the Guard flag out of all measured
3458 bandwidth. (Default: 0.75)
3459 AuthDirVoteGuardGuaranteeTimeKnown N seconds|minutes|hours|days|weeks
3461 A relay with at least this much weighted time known can be
3462 considered familiar enough to be a guard. (Default: 8 days)
3463 AuthDirVoteGuardGuaranteeWFU FRACTION
3465 A level of weighted fractional uptime (WFU) is that is sufficient
3466 to be a Guard. (Default: 0.98)
3467 AuthDirVoteStableGuaranteeMinUptime N seconds|minutes|hours|days|weeks
3469 If a relay’s uptime is at least this value, then it is always
3470 considered stable, regardless of the rest of the network. (Default:
3471 30 days)
3472 AuthDirVoteStableGuaranteeMTBF N seconds|minutes|hours|days|weeks
3474 If a relay’s mean time between failures (MTBF) is least this value,
3475 then it will always be considered stable. (Default: 5 days)
3476 BridgePassword Password
3478 If set, contains an HTTP authenticator that tells a bridge
3479 authority to serve all requested bridge information. Used by the
3480 (only partially implemented) "bridge community" design, where a
3481 community of bridge relay operators all use an alternate bridge
3482 directory authority, and their target user audience can
3483 periodically fetch the list of available community bridges to stay
3484 up-to-date. (Default: not set)
3485 ConsensusParams STRING
3487 STRING is a space-separated list of key=value pairs that Tor will
3488 include in the "params" line of its networkstatus vote. This
3489 directive can be specified multiple times so you don’t have to put
3490 it all on one line.
3491 DirAllowPrivateAddresses 0|1
3493 If set to 1, Tor will accept server descriptors with arbitrary
3494 "Address" elements. Otherwise, if the address is not an IP address
3495 or is a private IP address, it will reject the server descriptor.
3496 Additionally, Tor will allow exit policies for private networks to
3497 fulfill Exit flag requirements. (Default: 0)
3498 GuardfractionFile FILENAME
3500 V3 authoritative directories only. Configures the location of the
3501 guardfraction file which contains information about how long relays
3502 have been guards. (Default: unset)
3503 MinMeasuredBWsForAuthToIgnoreAdvertised N
3505 A total value, in abstract bandwidth units, describing how much
3506 measured total bandwidth an authority should have observed on the
3507 network before it will treat advertised bandwidths as wholly
3508 unreliable. (Default: 500)
3509 MinUptimeHidServDirectoryV2 N seconds|minutes|hours|days|weeks
3511 Minimum uptime of a relay to be accepted as a hidden service
3512 directory by directory authorities. (Default: 96 hours)
3513 RecommendedClientVersions STRING
3515 STRING is a comma-separated list of Tor versions currently believed
3516 to be safe for clients to use. This information is included in
3517 version 2 directories. If this is not set then the value of
3518 RecommendedVersions is used. When this is set then
3519 VersioningAuthoritativeDirectory should be set too.
3520 RecommendedServerVersions STRING
3522 STRING is a comma-separated list of Tor versions currently believed
3523 to be safe for servers to use. This information is included in
3524 version 2 directories. If this is not set then the value of
3525 RecommendedVersions is used. When this is set then
3526 VersioningAuthoritativeDirectory should be set too.
3527 RecommendedVersions STRING
3529 STRING is a comma-separated list of Tor versions currently believed
3530 to be safe. The list is included in each directory, and nodes which
3531 pull down the directory learn whether they need to upgrade. This
3532 option can appear multiple times: the values from multiple lines
3533 are spliced together. When this is set then
3534 VersioningAuthoritativeDirectory should be set too.
3535 V3AuthDistDelay N seconds|minutes|hours
3537 V3 authoritative directories only. Configures the server’s
3538 preferred delay between publishing its consensus and signature and
3539 assuming it has all the signatures from all the other authorities.
3540 Note that the actual time used is not the server’s preferred time,
3541 but the consensus of all preferences. (Default: 5 minutes)
3542 V3AuthNIntervalsValid NUM
3544 V3 authoritative directories only. Configures the number of
3545 VotingIntervals for which each consensus should be valid for.
3546 Choosing high numbers increases network partitioning risks;
3547 choosing low numbers increases directory traffic. Note that the
3548 actual number of intervals used is not the server’s preferred
3549 number, but the consensus of all preferences. Must be at least 2.
3550 (Default: 3)
3551 V3AuthUseLegacyKey 0|1
3553 If set, the directory authority will sign consensuses not only with
3554 its own signing key, but also with a "legacy" key and certificate
3555 with a different identity. This feature is used to migrate
3556 directory authority keys in the event of a compromise. (Default: 0)
3557 V3AuthVoteDelay N seconds|minutes|hours
3559 V3 authoritative directories only. Configures the server’s
3560 preferred delay between publishing its vote and assuming it has all
3561 the votes from all the other authorities. Note that the actual time
3562 used is not the server’s preferred time, but the consensus of all
3563 preferences. (Default: 5 minutes)
3564 V3AuthVotingInterval N minutes|hours
3566 V3 authoritative directories only. Configures the server’s
3567 preferred voting interval. Note that voting will actually happen at
3568 an interval chosen by consensus from all the authorities' preferred
3569 intervals. This time SHOULD divide evenly into a day. (Default: 1
3570 hour)
3571 V3BandwidthsFile FILENAME
3573 V3 authoritative directories only. Configures the location of the
3574 bandwidth-authority generated file storing information on relays'
3575 measured bandwidth capacities. To avoid inconsistent reads,
3576 bandwidth data should be written to temporary file, then renamed to
3577 the configured filename. (Default: unset)
3578 VersioningAuthoritativeDirectory 0|1
3580 When this option is set to 1, Tor adds information on which
3581 versions of Tor are still believed safe for use to the published
3582 directory. Each version 1 authority is automatically a versioning
3583 authority; version 2 authorities provide this service optionally.
3584 See RecommendedVersions, RecommendedClientVersions, and
3585 RecommendedServerVersions.
3586
3588 The following options are used to configure a hidden service. Some
3589 options apply per service and some apply for the whole tor instance.
3590 The next section describes the per service options that can only be set
3592 after the HiddenServiceDir directive
3593 PER SERVICE OPTIONS:
3595 HiddenServiceAllowUnknownPorts 0|1
3597 If set to 1, then connections to unrecognized ports do not cause
3598 the current hidden service to close rendezvous circuits. (Setting
3599 this to 0 is not an authorization mechanism; it is instead meant to
3600 be a mild inconvenience to port-scanners.) (Default: 0)
3601 HiddenServiceDir DIRECTORY
3603 Store data files for a hidden service in DIRECTORY. Every hidden
3604 service must have a separate directory. You may use this option
3605 multiple times to specify multiple services. If DIRECTORY does not
3606 exist, Tor will create it. Please note that you cannot add new
3607 Onion Service to already running Tor instance if Sandbox is
3608 enabled. (Note: in current versions of Tor, if DIRECTORY is a
3609 relative path, it will be relative to the current working directory
3610 of Tor instance, not to its DataDirectory. Do not rely on this
3611 behavior; it is not guaranteed to remain the same in future
3612 versions.)
3613 HiddenServiceDirGroupReadable 0|1
3615 If this option is set to 1, allow the filesystem group to read the
3616 hidden service directory and hostname file. If the option is set to
3617 0, only owner is able to read the hidden service directory.
3618 (Default: 0) Has no effect on Windows.
3619 HiddenServiceExportCircuitID protocol
3621 The onion service will use the given protocol to expose the global
3622 circuit identifier of each inbound client circuit. The only
3623 protocol supported right now 'haproxy'. This option is only for v3
3624 services. (Default: none)
3625 The haproxy option works in the following way: when the feature is
3628 enabled, the Tor process will write a header line when a client is
3629 connecting to the onion service. The header will look like this:
3630 "PROXY TCP6 fc00:dead:beef:4dad::ffff:ffff ::1 65535 42\r\n"
3633 We encode the "global circuit identifier" as the last 32-bits of
3636 the first IPv6 address. All other values in the header can safely
3637 be ignored. You can compute the global circuit identifier using the
3638 following formula given the IPv6 address
3639 "fc00:dead:beef:4dad::AABB:CCDD":
3640 global_circuit_id = (0xAA << 24) + (0xBB << 16) + (0xCC << 8) +
3643 0xDD;
3644 In the case above, where the last 32-bits are 0xffffffff, the
3647 global circuit identifier would be 4294967295. You can use this
3648 value together with Tor’s control port to terminate particular
3649 circuits using their global circuit identifiers. For more
3650 information about this see control-spec.txt.
3651 The HAProxy version 1 protocol is described in detail at
3654 https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
3655 HiddenServiceOnionBalanceInstance 0|1
3657 If set to 1, this onion service becomes an OnionBalance instance
3658 and will accept client connections destined to an OnionBalance
3659 frontend. In this case, Tor expects to find a file named
3660 "ob_config" inside the HiddenServiceDir directory with content:
3661 MasterOnionAddress <frontend_onion_address>
3663 where <frontend_onion_address> is the onion address of the
3665 OnionBalance frontend (e.g.
3666 wrxdvcaqpuzakbfww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.onion).
3667 HiddenServiceMaxStreams N
3669 The maximum number of simultaneous streams (connections) per
3670 rendezvous circuit. The maximum value allowed is 65535. (Setting
3671 this to 0 will allow an unlimited number of simultaneous streams.)
3672 (Default: 0)
3673 HiddenServiceMaxStreamsCloseCircuit 0|1
3675 If set to 1, then exceeding HiddenServiceMaxStreams will cause the
3676 offending rendezvous circuit to be torn down, as opposed to stream
3677 creation requests that exceed the limit being silently ignored.
3678 (Default: 0)
3679 HiddenServiceNumIntroductionPoints NUM
3681 Number of introduction points the hidden service will have. You
3682 can’t have more than 20. (Default: 3)
3683 HiddenServicePort VIRTPORT [TARGET]
3685 Configure a virtual port VIRTPORT for a hidden service. You may use
3686 this option multiple times; each time applies to the service using
3687 the most recent HiddenServiceDir. By default, this option maps the
3688 virtual port to the same port on 127.0.0.1 over TCP. You may
3689 override the target port, address, or both by specifying a target
3690 of addr, port, addr:port, or unix:path. (You can specify an IPv6
3691 target as [addr]:port. Unix paths may be quoted, and may use
3692 standard C escapes.) You may also have multiple lines with the same
3693 VIRTPORT: when a user connects to that VIRTPORT, one of the TARGETs
3694 from those lines will be chosen at random. Note that address-port
3695 pairs have to be comma-separated.
3696 HiddenServiceVersion 3
3698 A list of rendezvous service descriptor versions to publish for the
3699 hidden service. Currently, only version 3 is supported. (Default:
3700 3)
3701 PER INSTANCE OPTIONS:
3703 HiddenServiceSingleHopMode 0|1
3705 Experimental - Non Anonymous Hidden Services on a tor instance in
3706 HiddenServiceSingleHopMode make one-hop (direct) circuits between
3707 the onion service server, and the introduction and rendezvous
3708 points. (Onion service descriptors are still posted using 3-hop
3709 paths, to avoid onion service directories blocking the service.)
3710 This option makes every hidden service instance hosted by a tor
3711 instance a Single Onion Service. One-hop circuits make Single Onion
3712 servers easily locatable, but clients remain location-anonymous.
3713 However, the fact that a client is accessing a Single Onion rather
3714 than a Hidden Service may be statistically distinguishable.
3715 WARNING: Once a hidden service directory has been used by a tor
3718 instance in HiddenServiceSingleHopMode, it can NEVER be used again
3719 for a hidden service. It is best practice to create a new hidden
3720 service directory, key, and address for each new Single Onion
3721 Service and Hidden Service. It is not possible to run Single Onion
3722 Services and Hidden Services from the same tor instance: they
3723 should be run on different servers with different IP addresses.
3724 HiddenServiceSingleHopMode requires HiddenServiceNonAnonymousMode
3727 to be set to 1. Since a Single Onion service is non-anonymous, you
3728 can not configure a SOCKSPort on a tor instance that is running in
3729 HiddenServiceSingleHopMode. Can not be changed while tor is
3730 running. (Default: 0)
3731 HiddenServiceNonAnonymousMode 0|1
3733 Makes hidden services non-anonymous on this tor instance. Allows
3734 the non-anonymous HiddenServiceSingleHopMode. Enables direct
3735 connections in the server-side hidden service protocol. If you are
3736 using this option, you need to disable all client-side services on
3737 your Tor instance, including setting SOCKSPort to "0". Can not be
3738 changed while tor is running. (Default: 0)
3739 PublishHidServDescriptors 0|1
3741 If set to 0, Tor will run any hidden services you configure, but it
3742 won’t advertise them to the rendezvous directory. This option is
3743 only useful if you’re using a Tor controller that handles hidserv
3744 publishing for you. (Default: 1)
3745
3747 Service side:
3748 To configure client authorization on the service side, the
3750 "<HiddenServiceDir>/authorized_clients/" directory needs to exist. Each file
3751 in that directory should be suffixed with ".auth" (i.e. "alice.auth"; the
3752 file name is irrelevant) and its content format MUST be:
3753 <auth-type>:<key-type>:<base32-encoded-public-key>
3755 The supported <auth-type> are: "descriptor". The supported <key-type> are:
3757 "x25519". The <base32-encoded-public-key> is the base32 representation of
3758 the raw key bytes only (32 bytes for x25519).
3759 Each file MUST contain one line only. Any malformed file will be
3761 ignored. Client authorization will only be enabled for the service if tor
3762 successfully loads at least one authorization file.
3763 Note that once you've configured client authorization, anyone else with the
3765 address won't be able to access it from this point on. If no authorization is
3766 configured, the service will be accessible to anyone with the onion address.
3767 Revoking a client can be done by removing their ".auth" file, however the
3769 revocation will be in effect only after the tor process gets restarted or if
3770 a SIGHUP takes place.
3771 Client side:
3773 To access a v3 onion service with client authorization as a client, make sure
3775 you have ClientOnionAuthDir set in your torrc. Then, in the
3776 <ClientOnionAuthDir> directory, create an .auth_private file for the onion
3777 service corresponding to this key (i.e. 'bob_onion.auth_private'). The
3778 contents of the <ClientOnionAuthDir>/<user>.auth_private file should look like:
3779 <56-char-onion-addr-without-.onion-part>:descriptor:x25519:<x25519 private key in base32>
3781 For more information, please see
3783 https://2019.www.torproject.org/docs/tor-onion-service.html.en#ClientAuthorization
3784 .
3785
3787 The following options are used for running a testing Tor network.
3788 TestingTorNetwork 0|1
3790 If set to 1, Tor adjusts default values of the configuration
3791 options below, so that it is easier to set up a testing Tor
3792 network. May only be set if non-default set of DirAuthorities is
3793 set. Cannot be unset while Tor is running. (Default: 0)
3794 DirAllowPrivateAddresses 1
3797 EnforceDistinctSubnets 0
3798 AuthDirMaxServersPerAddr 0
3799 ClientBootstrapConsensusAuthorityDownloadInitialDelay 0
3800 ClientBootstrapConsensusFallbackDownloadInitialDelay 0
3801 ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay 0
3802 ClientDNSRejectInternalAddresses 0
3803 ClientRejectInternalAddresses 0
3804 CountPrivateBandwidth 1
3805 ExitPolicyRejectPrivate 0
3806 ExtendAllowPrivateAddresses 1
3807 V3AuthVotingInterval 5 minutes
3808 V3AuthVoteDelay 20 seconds
3809 V3AuthDistDelay 20 seconds
3810 TestingV3AuthInitialVotingInterval 150 seconds
3811 TestingV3AuthInitialVoteDelay 20 seconds
3812 TestingV3AuthInitialDistDelay 20 seconds
3813 TestingAuthDirTimeToLearnReachability 0 minutes
3814 MinUptimeHidServDirectoryV2 0 minutes
3815 TestingServerDownloadInitialDelay 0
3816 TestingClientDownloadInitialDelay 0
3817 TestingServerConsensusDownloadInitialDelay 0
3818 TestingClientConsensusDownloadInitialDelay 0
3819 TestingBridgeDownloadInitialDelay 10
3820 TestingBridgeBootstrapDownloadInitialDelay 0
3821 TestingClientMaxIntervalWithoutRequest 5 seconds
3822 TestingDirConnectionMaxStall 30 seconds
3823 TestingEnableConnBwEvent 1
3824 TestingEnableCellStatsEvent 1
3825 TestingAuthDirTimeToLearnReachability N seconds|minutes|hours
3827 After starting as an authority, do not make claims about whether
3828 routers are Running until this much time has passed. Changing this
3829 requires that TestingTorNetwork is set. (Default: 30 minutes)
3830 TestingAuthKeyLifetime N seconds|minutes|hours|days|weeks|months
3832 Overrides the default lifetime for a signing Ed25519 TLS Link
3833 authentication key. (Default: 2 days)
3834 TestingAuthKeySlop N seconds|minutes|hours
3836 TestingBridgeBootstrapDownloadInitialDelay N
3838 Initial delay in seconds for how long clients should wait before
3839 downloading a bridge descriptor for a new bridge. Changing this
3840 requires that TestingTorNetwork is set. (Default: 0)
3841 TestingBridgeDownloadInitialDelay N
3843 How long to wait (in seconds) once clients have successfully
3844 downloaded a bridge descriptor, before trying another download for
3845 that same bridge. Changing this requires that TestingTorNetwork is
3846 set. (Default: 10800)
3847 TestingClientConsensusDownloadInitialDelay N
3849 Initial delay in seconds for when clients should download
3850 consensuses. Changing this requires that TestingTorNetwork is set.
3851 (Default: 0)
3852 TestingClientDownloadInitialDelay N
3854 Initial delay in seconds for when clients should download things in
3855 general. Changing this requires that TestingTorNetwork is set.
3856 (Default: 0)
3857 TestingClientMaxIntervalWithoutRequest N seconds|minutes
3859 When directory clients have only a few descriptors to request, they
3860 batch them until they have more, or until this amount of time has
3861 passed. Changing this requires that TestingTorNetwork is set.
3862 (Default: 10 minutes)
3863 TestingDirAuthVoteExit node,node,...
3865 A list of identity fingerprints, country codes, and address
3866 patterns of nodes to vote Exit for regardless of their uptime,
3867 bandwidth, or exit policy. See ExcludeNodes for more information on
3868 how to specify nodes.
3869 In order for this option to have any effect, TestingTorNetwork has
3872 to be set. See ExcludeNodes for more information on how to specify
3873 nodes.
3874 TestingDirAuthVoteExitIsStrict 0|1
3876 If True (1), a node will never receive the Exit flag unless it is
3877 specified in the TestingDirAuthVoteExit list, regardless of its
3878 uptime, bandwidth, or exit policy.
3879 In order for this option to have any effect, TestingTorNetwork has
3882 to be set.
3883 TestingDirAuthVoteGuard node,node,...
3885 A list of identity fingerprints and country codes and address
3886 patterns of nodes to vote Guard for regardless of their uptime and
3887 bandwidth. See ExcludeNodes for more information on how to specify
3888 nodes.
3889 In order for this option to have any effect, TestingTorNetwork has
3892 to be set.
3893 TestingDirAuthVoteGuardIsStrict 0|1
3895 If True (1), a node will never receive the Guard flag unless it is
3896 specified in the TestingDirAuthVoteGuard list, regardless of its
3897 uptime and bandwidth.
3898 In order for this option to have any effect, TestingTorNetwork has
3901 to be set.
3902 TestingDirAuthVoteHSDir node,node,...
3904 A list of identity fingerprints and country codes and address
3905 patterns of nodes to vote HSDir for regardless of their uptime and
3906 DirPort. See ExcludeNodes for more information on how to specify
3907 nodes.
3908 In order for this option to have any effect, TestingTorNetwork must
3911 be set.
3912 TestingDirAuthVoteHSDirIsStrict 0|1
3914 If True (1), a node will never receive the HSDir flag unless it is
3915 specified in the TestingDirAuthVoteHSDir list, regardless of its
3916 uptime and DirPort.
3917 In order for this option to have any effect, TestingTorNetwork has
3920 to be set.
3921 TestingDirConnectionMaxStall N seconds|minutes
3923 Let a directory connection stall this long before expiring it.
3924 Changing this requires that TestingTorNetwork is set. (Default: 5
3925 minutes)
3926 TestingEnableCellStatsEvent 0|1
3928 If this option is set, then Tor controllers may register for
3929 CELL_STATS events. Changing this requires that TestingTorNetwork is
3930 set. (Default: 0)
3931 TestingEnableConnBwEvent 0|1
3933 If this option is set, then Tor controllers may register for
3934 CONN_BW events. Changing this requires that TestingTorNetwork is
3935 set. (Default: 0)
3936 TestingLinkCertLifetime N seconds|minutes|hours|days|weeks|months
3938 Overrides the default lifetime for the certificates used to
3939 authenticate our X509 link cert with our ed25519 signing key.
3940 (Default: 2 days)
3941 TestingLinkKeySlop N seconds|minutes|hours
3943 TestingMinExitFlagThreshold N
3945 KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3946 Sets a lower-bound for assigning an exit flag when running as an
3947 authority on a testing network. Overrides the usual default lower
3948 bound of 4 KBytes. (Default: 0)
3949 TestingMinFastFlagThreshold N
3951 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3952 Minimum value for the Fast flag. Overrides the ordinary minimum
3953 taken from the consensus when TestingTorNetwork is set. (Default:
3954 0.)
3955 TestingMinTimeToReportBandwidth N seconds|minutes|hours
3957 Do not report our measurements for our maximum observed bandwidth
3958 for any time period that has lasted for less than this amount of
3959 time. Values over 1 day have no effect. (Default: 1 day)
3960 TestingServerConsensusDownloadInitialDelay N
3962 Initial delay in seconds for when servers should download
3963 consensuses. Changing this requires that TestingTorNetwork is set.
3964 (Default: 0)
3965 TestingServerDownloadInitialDelay N
3967 Initial delay in seconds for when servers should download things in
3968 general. Changing this requires that TestingTorNetwork is set.
3969 (Default: 0)
3970 TestingSigningKeySlop N seconds|minutes|hours
3972 How early before the official expiration of a an Ed25519 signing
3973 key do we replace it and issue a new key? (Default: 3 hours for
3974 link and auth; 1 day for signing.)
3975 TestingV3AuthInitialDistDelay N seconds|minutes|hours
3977 Like V3AuthDistDelay, but for initial voting interval before the
3978 first consensus has been created. Changing this requires that
3979 TestingTorNetwork is set. (Default: 5 minutes)
3980 TestingV3AuthInitialVoteDelay N seconds|minutes|hours
3982 Like V3AuthVoteDelay, but for initial voting interval before the
3983 first consensus has been created. Changing this requires that
3984 TestingTorNetwork is set. (Default: 5 minutes)
3985 TestingV3AuthInitialVotingInterval N seconds|minutes|hours
3987 Like V3AuthVotingInterval, but for initial voting interval before
3988 the first consensus has been created. Changing this requires that
3989 TestingTorNetwork is set. (Default: 30 minutes)
3990 TestingV3AuthVotingStartOffset N seconds|minutes|hours
3992 Directory authorities offset voting start time by this much.
3993 Changing this requires that TestingTorNetwork is set. (Default: 0)
3994
3996 These options are not saved to the torrc file by the "SAVECONF"
3997 controller command. Other options of this type are documented in
3998 control-spec.txt, section 5.4. End-users should mostly ignore them.
3999 __ControlPort, __DirPort, __DNSPort, __ExtORPort, __NATDPort, __ORPort,
4001 __SocksPort, __TransPort
4002 These underscore-prefixed options are variants of the regular Port
4003 options. They behave the same, except they are not saved to the
4004 torrc file by the controller’s SAVECONF command.
4005
4007 Tor catches the following signals:
4008 SIGTERM
4010 Tor will catch this, clean up and sync to disk if necessary, and
4011 exit.
4012 SIGINT
4014 Tor clients behave as with SIGTERM; but Tor servers will do a
4015 controlled slow shutdown, closing listeners and waiting 30 seconds
4016 before exiting. (The delay can be configured with the
4017 ShutdownWaitLength config option.)
4018 SIGHUP
4020 The signal instructs Tor to reload its configuration (including
4021 closing and reopening logs), and kill and restart its helper
4022 processes if applicable.
4023 SIGUSR1
4025 Log statistics about current connections, past connections, and
4026 throughput.
4027 SIGUSR2
4029 Switch all logs to loglevel debug. You can go back to the old
4030 loglevels by sending a SIGHUP.
4031 SIGCHLD
4033 Tor receives this signal when one of its helper processes has
4034 exited, so it can clean up.
4035 SIGPIPE
4037 Tor catches this signal and ignores it.
4038 SIGXFSZ
4040 If this signal exists on your platform, Tor catches and ignores it.
4041
4043 /etc/tor/torrc
4044 Default location of the configuration file.
4045 $HOME/.torrc
4047 Fallback location for torrc, if /etc/tor/torrc is not found.
4048 /var/lib/tor/
4050 The tor process stores keys and other data here.
4051 CacheDirectory/cached-certs
4053 Contains downloaded directory key certificates that are used to
4054 verify authenticity of documents generated by the Tor directory
4055 authorities.
4056 CacheDirectory/cached-consensus and/or cached-microdesc-consensus
4058 The most recent consensus network status document we’ve downloaded.
4059 CacheDirectory/cached-descriptors and cached-descriptors.new
4061 These files contain the downloaded router statuses. Some routers
4062 may appear more than once; if so, the most recently published
4063 descriptor is used. Lines beginning with @-signs are annotations
4064 that contain more information about a given router. The .new file
4065 is an append-only journal; when it gets too large, all entries are
4066 merged into a new cached-descriptors file.
4067 CacheDirectory/cached-extrainfo and cached-extrainfo.new
4069 Similar to cached-descriptors, but holds optionally-downloaded
4070 "extra-info" documents. Relays use these documents to send
4071 inessential information about statistics, bandwidth history, and
4072 network health to the authorities. They aren’t fetched by default.
4073 See DownloadExtraInfo for more information.
4074 CacheDirectory/cached-microdescs and cached-microdescs.new
4076 These files hold downloaded microdescriptors. Lines beginning with
4077 @-signs are annotations that contain more information about a given
4078 router. The .new file is an append-only journal; when it gets too
4079 large, all entries are merged into a new cached-microdescs file.
4080 DataDirectory/state
4082 Contains a set of persistent key-value mappings. These include:
4083 • the current entry guards and their status.
4085 • the current bandwidth accounting values.
4087 • when the file was last written
4089 • what version of Tor generated the state file
4091 • a short history of bandwidth usage, as produced in the server
4093 descriptors.
4094 DataDirectory/sr-state
4096 Authority only. This file is used to record information about the
4097 current status of the shared-random-value voting state.
4098 CacheDirectory/diff-cache
4100 Directory cache only. Holds older consensuses and diffs from oldest
4101 to the most recent consensus of each type compressed in various
4102 ways. Each file contains a set of key-value arguments describing
4103 its contents, followed by a single NUL byte, followed by the main
4104 file contents.
4105 DataDirectory/bw_accounting
4107 This file is obsolete and the data is now stored in the state file
4108 instead. Used to track bandwidth accounting values (when the
4109 current period starts and ends; how much has been read and written
4110 so far this period).
4111 DataDirectory/control_auth_cookie
4113 This file can be used only when cookie authentication is enabled.
4114 Used for cookie authentication with the controller. Location can be
4115 overridden by the CookieAuthFile configuration option. Regenerated
4116 on startup. See control-spec.txt in torspec for details.
4117 DataDirectory/lock
4119 This file is used to prevent two Tor instances from using the same
4120 data directory. If access to this file is locked, data directory is
4121 already in use by Tor.
4122 DataDirectory/key-pinning-journal
4124 Used by authorities. A line-based file that records mappings
4125 between RSA1024 and Ed25519 identity keys. Authorities enforce
4126 these mappings, so that once a relay has picked an Ed25519 key,
4127 stealing or factoring the RSA1024 key will no longer let an
4128 attacker impersonate the relay.
4129 KeyDirectory/authority_identity_key
4131 A v3 directory authority’s master identity key, used to
4132 authenticate its signing key. Tor doesn’t use this while it’s
4133 running. The tor-gencert program uses this. If you’re running an
4134 authority, you should keep this key offline, and not put it in this
4135 file.
4136 KeyDirectory/authority_certificate
4138 Only directory authorities use this file. A v3 directory
4139 authority’s certificate which authenticates the authority’s current
4140 vote- and consensus-signing key using its master identity key.
4141 KeyDirectory/authority_signing_key
4143 Only directory authorities use this file. A v3 directory
4144 authority’s signing key that is used to sign votes and consensuses.
4145 Corresponds to the authority_certificate cert.
4146 KeyDirectory/legacy_certificate
4148 As authority_certificate; used only when V3AuthUseLegacyKey is set.
4149 See documentation for V3AuthUseLegacyKey.
4150 KeyDirectory/legacy_signing_key
4152 As authority_signing_key: used only when V3AuthUseLegacyKey is set.
4153 See documentation for V3AuthUseLegacyKey.
4154 KeyDirectory/secret_id_key
4156 A relay’s RSA1024 permanent identity key, including private and
4157 public components. Used to sign router descriptors, and to sign
4158 other keys.
4159 KeyDirectory/ed25519_master_id_public_key
4161 The public part of a relay’s Ed25519 permanent identity key.
4162 KeyDirectory/ed25519_master_id_secret_key
4164 The private part of a relay’s Ed25519 permanent identity key. This
4165 key is used to sign the medium-term ed25519 signing key. This file
4166 can be kept offline or encrypted. If so, Tor will not be able to
4167 generate new signing keys automatically; you’ll need to use tor
4168 --keygen to do so.
4169 KeyDirectory/ed25519_signing_secret_key
4171 The private and public components of a relay’s medium-term Ed25519
4172 signing key. This key is authenticated by the Ed25519 master key,
4173 which in turn authenticates other keys (and router descriptors).
4174 KeyDirectory/ed25519_signing_cert
4176 The certificate which authenticates "ed25519_signing_secret_key" as
4177 having been signed by the Ed25519 master key.
4178 KeyDirectory/secret_onion_key and secret_onion_key.old
4180 A relay’s RSA1024 short-term onion key. Used to decrypt old-style
4181 ("TAP") circuit extension requests. The .old file holds the
4182 previously generated key, which the relay uses to handle any
4183 requests that were made by clients that didn’t have the new one.
4184 KeyDirectory/secret_onion_key_ntor and secret_onion_key_ntor.old
4186 A relay’s Curve25519 short-term onion key. Used to handle modern
4187 ("ntor") circuit extension requests. The .old file holds the
4188 previously generated key, which the relay uses to handle any
4189 requests that were made by clients that didn’t have the new one.
4190 DataDirectory/fingerprint
4192 Only used by servers. Contains the fingerprint of the server’s RSA
4193 identity key.
4194 DataDirectory/fingerprint-ed25519
4196 Only used by servers. Contains the fingerprint of the server’s
4197 ed25519 identity key.
4198 DataDirectory/hashed-fingerprint
4200 Only used by bridges. Contains the hashed fingerprint of the
4201 bridge’s identity key. (That is, the hash of the hash of the
4202 identity key.)
4203 DataDirectory/approved-routers
4205 Only used by authoritative directory servers. Each line lists a
4206 status and an identity, separated by whitespace. Identities can be
4207 hex-encoded RSA fingerprints, or base-64 encoded ed25519 public
4208 keys. See the fingerprint file in a tor relay’s DataDirectory for
4209 an example fingerprint line. If the status is !reject, then
4210 descriptors from the given identity are rejected by this server. If
4211 it is !invalid then descriptors are accepted, but marked in the
4212 vote as not valid. If it is !badexit, then the authority will vote
4213 for it to receive a BadExit flag, indicating that it shouldn’t be
4214 used for traffic leaving the Tor network. If it is !middleonly,
4215 then the authority will vote for it to only be used in the middle
4216 of circuits. (Neither rejected nor invalid relays are included in
4217 the consensus.)
4218 DataDirectory/v3-status-votes
4220 Only for v3 authoritative directory servers. This file contains
4221 status votes from all the authoritative directory servers.
4222 CacheDirectory/unverified-consensus
4224 Contains a network consensus document that has been downloaded, but
4225 which we didn’t have the right certificates to check yet.
4226 CacheDirectory/unverified-microdesc-consensus
4228 Contains a microdescriptor-flavored network consensus document that
4229 has been downloaded, but which we didn’t have the right
4230 certificates to check yet.
4231 DataDirectory/unparseable-desc
4233 Onion server descriptors that Tor was unable to parse are dumped to
4234 this file. Only used for debugging.
4235 DataDirectory/router-stability
4237 Only used by authoritative directory servers. Tracks measurements
4238 for router mean-time-between-failures so that authorities have a
4239 fair idea of how to set their Stable flags.
4240 DataDirectory/stats/dirreq-stats
4242 Only used by directory caches and authorities. This file is used to
4243 collect directory request statistics.
4244 DataDirectory/stats/entry-stats
4246 Only used by servers. This file is used to collect incoming
4247 connection statistics by Tor entry nodes.
4248 DataDirectory/stats/bridge-stats
4250 Only used by servers. This file is used to collect incoming
4251 connection statistics by Tor bridges.
4252 DataDirectory/stats/exit-stats
4254 Only used by servers. This file is used to collect outgoing
4255 connection statistics by Tor exit routers.
4256 DataDirectory/stats/buffer-stats
4258 Only used by servers. This file is used to collect buffer usage
4259 history.
4260 DataDirectory/stats/conn-stats
4262 Only used by servers. This file is used to collect approximate
4263 connection history (number of active connections over time).
4264 DataDirectory/stats/hidserv-stats
4266 Only used by servers. This file is used to collect approximate
4267 counts of what fraction of the traffic is hidden service rendezvous
4268 traffic, and approximately how many hidden services the relay has
4269 seen.
4270 DataDirectory/networkstatus-bridges`
4272 Only used by authoritative bridge directories. Contains information
4273 about bridges that have self-reported themselves to the bridge
4274 authority.
4275 HiddenServiceDirectory/hostname
4277 The <base32-encoded-fingerprint>.onion domain name for this hidden
4278 service. If the hidden service is restricted to authorized clients
4279 only, this file also contains authorization data for all clients.
4280 Note
4282 The clients will ignore any extra subdomains prepended to a
4283 hidden service hostname. Supposing you have "xyz.onion" as your
4284 hostname, you can ask your clients to connect to
4285 "www.xyz.onion" or "irc.xyz.onion" for virtual-hosting
4286 purposes.
4287 HiddenServiceDirectory/private_key
4289 Contains the private key for this hidden service.
4290 HiddenServiceDirectory/client_keys
4292 Contains authorization data for a hidden service that is only
4293 accessible by authorized clients.
4294 HiddenServiceDirectory/onion_service_non_anonymous
4296 This file is present if a hidden service key was created in
4297 HiddenServiceNonAnonymousMode.
4298
4300 For more information, refer to the Tor Project website at
4301 https://www.torproject.org/ and the Tor specifications at
4302 https://spec.torproject.org. See also torsocks(1) and torify(1).
4303
4305 Because Tor is still under development, there may be plenty of bugs.
4306 Please report them at https://bugs.torproject.org/.
4307Tor 11/09/2023 TOR(1)