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 ConnLimit NUM
345 The minimum number of file descriptors that must be available to
346 the Tor process before it will start. Tor will ask the OS for as
347 many file descriptors as the OS will allow (you can find this by
348 "ulimit -H -n"). If this number is less than ConnLimit, then Tor
349 will refuse to start.
350 Tor relays need thousands of sockets, to connect to every other
353 relay. If you are running a private bridge, you can reduce the
354 number of sockets that Tor uses. For example, to limit Tor to 500
355 sockets, run "ulimit -n 500" in a shell. Then start tor in the same
356 shell, with ConnLimit 500. You may also need to set DisableOOSCheck
357 0.
358 Unless you have severely limited sockets, you probably don’t need
361 to adjust ConnLimit itself. It has no effect on Windows, since that
362 platform lacks getrlimit(). (Default: 1000)
363 ConstrainedSockets 0|1
365 If set, Tor will tell the kernel to attempt to shrink the buffers
366 for all sockets to the size specified in ConstrainedSockSize. This
367 is useful for virtual servers and other environments where system
368 level TCP buffers may be limited. If you’re on a virtual server,
369 and you encounter the "Error creating network socket: No buffer
370 space available" message, you are likely experiencing this problem.
371 The preferred solution is to have the admin increase the buffer
374 pool for the host itself via /proc/sys/net/ipv4/tcp_mem or
375 equivalent facility; this configuration option is a second-resort.
376 The DirPort option should also not be used if TCP buffers are
379 scarce. The cached directory requests consume additional sockets
380 which exacerbates the problem.
381 You should not enable this feature unless you encounter the "no
384 buffer space available" issue. Reducing the TCP buffers affects
385 window size for the TCP stream and will reduce throughput in
386 proportion to round trip time on long paths. (Default: 0)
387 ConstrainedSockSize N bytes|KBytes
389 When ConstrainedSockets is enabled the receive and transmit buffers
390 for all sockets will be set to this limit. Must be a value between
391 2048 and 262144, in 1024 byte increments. Default of 8192 is
392 recommended.
393 ControlPort [address:]port|unix:path|auto [flags]
395 If set, Tor will accept connections on this port and allow those
396 connections to control the Tor process using the Tor Control
397 Protocol (described in control-spec.txt in torspec). Note: unless
398 you also specify one or more of HashedControlPassword or
399 CookieAuthentication, setting this option will cause Tor to allow
400 any process on the local host to control it. (Setting both
401 authentication methods means either method is sufficient to
402 authenticate to Tor.) This option is required for many Tor
403 controllers; most use the value of 9051. If a unix domain socket is
404 used, you may quote the path using standard C escape sequences. You
405 can specify this directive multiple times, to bind to multiple
406 address/port pairs. Set it to "auto" to have Tor pick a port for
407 you. (Default: 0)
408 Recognized flags are:
411 GroupWritable
413 Unix domain sockets only: makes the socket get created as
414 group-writable.
415 WorldWritable
417 Unix domain sockets only: makes the socket get created as
418 world-writable.
419 RelaxDirModeCheck
421 Unix domain sockets only: Do not insist that the directory that
422 holds the socket be read-restricted.
423 ControlPortFileGroupReadable 0|1
425 If this option is set to 0, don’t allow the filesystem group to
426 read the control port file. If the option is set to 1, make the
427 control port file readable by the default GID. (Default: 0)
428 ControlPortWriteToFile Path
430 If set, Tor writes the address and port of any control port it
431 opens to this address. Usable by controllers to learn the actual
432 control port when ControlPort is set to "auto".
433 ControlSocket Path
435 Like ControlPort, but listens on a Unix domain socket, rather than
436 a TCP socket. 0 disables ControlSocket. (Unix and Unix-like
437 systems only.) (Default: 0)
438 ControlSocketsGroupWritable 0|1
440 If this option is set to 0, don’t allow the filesystem group to
441 read and write unix sockets (e.g. ControlSocket). If the option is
442 set to 1, make the control socket readable and writable by the
443 default GID. (Default: 0)
444 CookieAuthentication 0|1
446 If this option is set to 1, allow connections on the control port
447 when the connecting process knows the contents of a file named
448 "control_auth_cookie", which Tor will create in its data directory.
449 This authentication method should only be used on systems with good
450 filesystem security. (Default: 0)
451 CookieAuthFile Path
453 If set, this option overrides the default location and file name
454 for Tor’s cookie file. (See CookieAuthentication.)
455 CookieAuthFileGroupReadable 0|1
457 If this option is set to 0, don’t allow the filesystem group to
458 read the cookie file. If the option is set to 1, make the cookie
459 file readable by the default GID. [Making the file readable by
460 other groups is not yet implemented; let us know if you need this
461 for some reason.] (Default: 0)
462 CountPrivateBandwidth 0|1
464 If this option is set, then Tor’s rate-limiting applies not only to
465 remote connections, but also to connections to private addresses
466 like 127.0.0.1 or 10.0.0.1. This is mostly useful for debugging
467 rate-limiting. (Default: 0)
468 DataDirectory DIR
470 Store working data in DIR. Can not be changed while tor is running.
471 (Default: ~/.tor if your home directory is not /; otherwise,
472 /var/lib/tor. On Windows, the default is your ApplicationData
473 folder.)
474 DataDirectoryGroupReadable 0|1
476 If this option is set to 0, don’t allow the filesystem group to
477 read the DataDirectory. If the option is set to 1, make the
478 DataDirectory readable by the default GID. (Default: 0)
479 DirAuthority [nickname] [flags] ipv4address:dirport fingerprint
481 Use a nonstandard authoritative directory server at the provided
482 address and port, with the specified key fingerprint. This option
483 can be repeated many times, for multiple authoritative directory
484 servers. Flags are separated by spaces, and determine what kind of
485 an authority this directory is. By default, an authority is not
486 authoritative for any directory style or version unless an
487 appropriate flag is given.
488 Tor will use this authority as a bridge authoritative directory if
491 the "bridge" flag is set. If a flag "orport=orport" is given, Tor
492 will use the given port when opening encrypted tunnels to the
493 dirserver. If a flag "weight=num" is given, then the directory
494 server is chosen randomly with probability proportional to that
495 weight (default 1.0). If a flag "v3ident=fp" is given, the
496 dirserver is a v3 directory authority whose v3 long-term signing
497 key has the fingerprint fp. Lastly, if an
498 "ipv6=[ipv6address]:orport" flag is present, then the directory
499 authority is listening for IPv6 connections on the indicated IPv6
500 address and OR Port.
501 Tor will contact the authority at ipv4address to download directory
504 documents. Clients always use the ORPort. Relays usually use the
505 DirPort, but will use the ORPort in some circumstances. If an IPv6
506 ORPort is supplied, clients will also download directory documents
507 at the IPv6 ORPort, if they are configured to use IPv6.
508 If no DirAuthority line is given, Tor will use the default
511 directory authorities. NOTE: this option is intended for setting up
512 a private Tor network with its own directory authorities. If you
513 use it, you will be distinguishable from other users, because you
514 won’t believe the same authorities they do.
515 DirAuthorityFallbackRate NUM
517 When configured to use both directory authorities and fallback
518 directories, the directory authorities also work as fallbacks. They
519 are chosen with their regular weights, multiplied by this number,
520 which should be 1.0 or less. The default is less than 1, to reduce
521 load on authorities. (Default: 0.1)
522 DisableAllSwap 0|1
524 If set to 1, Tor will attempt to lock all current and future memory
525 pages, so that memory cannot be paged out. Windows, OS X and
526 Solaris are currently not supported. We believe that this feature
527 works on modern Gnu/Linux distributions, and that it should work on
528 *BSD systems (untested). This option requires that you start your
529 Tor as root, and you should use the User option to properly reduce
530 Tor’s privileges. Can not be changed while tor is running.
531 (Default: 0)
532 DisableDebuggerAttachment 0|1
534 If set to 1, Tor will attempt to prevent basic debugging attachment
535 attempts by other processes. This may also keep Tor from generating
536 core files if it crashes. It has no impact for users who wish to
537 attach if they have CAP_SYS_PTRACE or if they are root. We believe
538 that this feature works on modern Gnu/Linux distributions, and that
539 it may also work on *BSD systems (untested). Some modern Gnu/Linux
540 systems such as Ubuntu have the kernel.yama.ptrace_scope sysctl and
541 by default enable it as an attempt to limit the PTRACE scope for
542 all user processes by default. This feature will attempt to limit
543 the PTRACE scope for Tor specifically - it will not attempt to
544 alter the system wide ptrace scope as it may not even exist. If you
545 wish to attach to Tor with a debugger such as gdb or strace you
546 will want to set this to 0 for the duration of your debugging.
547 Normal users should leave it on. Disabling this option while Tor is
548 running is prohibited. (Default: 1)
549 DisableNetwork 0|1
551 When this option is set, we don’t listen for or accept any
552 connections other than controller connections, and we close (and
553 don’t reattempt) any outbound connections. Controllers sometimes
554 use this option to avoid using the network until Tor is fully
555 configured. Tor will make still certain network-related calls (like
556 DNS lookups) as a part of its configuration process, even if
557 DisableNetwork is set. (Default: 0)
558 ExtendByEd25519ID 0|1|auto
560 If this option is set to 1, we always try to include a relay’s
561 Ed25519 ID when telling the preceding relay in a circuit to extend
562 to it. If this option is set to 0, we never include Ed25519 IDs
563 when extending circuits. If the option is set to "auto", we obey a
564 parameter in the consensus document. (Default: auto)
565 ExtORPort [address:]port|auto
567 Open this port to listen for Extended ORPort connections from your
568 pluggable transports.
569 (Default: DataDirectory/extended_orport_auth_cookie)
571 ExtORPortCookieAuthFile Path
573 If set, this option overrides the default location and file name
574 for the Extended ORPort’s cookie file — the cookie file is needed
575 for pluggable transports to communicate through the Extended
576 ORPort.
577 ExtORPortCookieAuthFileGroupReadable 0|1
579 If this option is set to 0, don’t allow the filesystem group to
580 read the Extended OR Port cookie file. If the option is set to 1,
581 make the cookie file readable by the default GID. [Making the file
582 readable by other groups is not yet implemented; let us know if you
583 need this for some reason.] (Default: 0)
584 FallbackDir ipv4address:dirport orport=orport id=fingerprint
586 [weight=num] [ipv6=[ipv6address]:orport]
587 When tor is unable to connect to any directory cache for directory
588 info (usually because it doesn’t know about any yet) it tries a
589 hard-coded directory. Relays try one directory authority at a time.
590 Clients try multiple directory authorities and FallbackDirs, to
591 avoid hangs on startup if a hard-coded directory is down. Clients
592 wait for a few seconds between each attempt, and retry FallbackDirs
593 more often than directory authorities, to reduce the load on the
594 directory authorities.
595 FallbackDirs should be stable relays with stable IP addresses,
598 ports, and identity keys. They must have a DirPort.
599 By default, the directory authorities are also FallbackDirs.
602 Specifying a FallbackDir replaces Tor’s default hard-coded
603 FallbackDirs (if any). (See DirAuthority for an explanation of each
604 flag.)
605 FetchDirInfoEarly 0|1
607 If set to 1, Tor will always fetch directory information like other
608 directory caches, even if you don’t meet the normal criteria for
609 fetching early. Normal users should leave it off. (Default: 0)
610 FetchDirInfoExtraEarly 0|1
612 If set to 1, Tor will fetch directory information before other
613 directory caches. It will attempt to download directory information
614 closer to the start of the consensus period. Normal users should
615 leave it off. (Default: 0)
616 FetchHidServDescriptors 0|1
618 If set to 0, Tor will never fetch any hidden service descriptors
619 from the rendezvous directories. This option is only useful if
620 you’re using a Tor controller that handles hidden service fetches
621 for you. (Default: 1)
622 FetchServerDescriptors 0|1
624 If set to 0, Tor will never fetch any network status summaries or
625 server descriptors from the directory servers. This option is only
626 useful if you’re using a Tor controller that handles directory
627 fetches for you. (Default: 1)
628 FetchUselessDescriptors 0|1
630 If set to 1, Tor will fetch every consensus flavor, and all server
631 descriptors and authority certificates referenced by those
632 consensuses, except for extra info descriptors. When this option is
633 1, Tor will also keep fetching descriptors, even when idle. If set
634 to 0, Tor will avoid fetching useless descriptors: flavors that it
635 is not using to build circuits, and authority certificates it does
636 not trust. When Tor hasn’t built any application circuits, it will
637 go idle, and stop fetching descriptors. This option is useful if
638 you’re using a tor client with an external parser that uses a full
639 consensus. This option fetches all documents except extrainfo
640 descriptors, DirCache fetches and serves all documents except
641 extrainfo descriptors, DownloadExtraInfo* fetches extrainfo
642 documents, and serves them if DirCache is on, and
643 UseMicrodescriptors changes the flavor of consensuses and
644 descriptors that is fetched and used for building circuits.
645 (Default: 0)
646 HardwareAccel 0|1
648 If non-zero, try to use built-in (static) crypto hardware
649 acceleration when available. Can not be changed while tor is
650 running. (Default: 0)
651 HashedControlPassword hashed_password
653 Allow connections on the control port if they present the password
654 whose one-way hash is hashed_password. You can compute the hash of
655 a password by running "tor --hash-password password". You can
656 provide several acceptable passwords by using more than one
657 HashedControlPassword line.
658 HTTPProxy host[:port]
660 Tor will make all its directory requests through this host:port (or
661 host:80 if port is not specified), rather than connecting directly
662 to any directory servers. (DEPRECATED: As of 0.3.1.0-alpha you
663 should use HTTPSProxy.)
664 HTTPProxyAuthenticator username:password
666 If defined, Tor will use this username:password for Basic HTTP
667 proxy authentication, as in RFC 2617. This is currently the only
668 form of HTTP proxy authentication that Tor supports; feel free to
669 submit a patch if you want it to support others. (DEPRECATED: As of
670 0.3.1.0-alpha you should use HTTPSProxyAuthenticator.)
671 HTTPSProxy host[:port]
673 Tor will make all its OR (SSL) connections through this host:port
674 (or host:443 if port is not specified), via HTTP CONNECT rather
675 than connecting directly to servers. You may want to set
676 FascistFirewall to restrict the set of ports you might try to
677 connect to, if your HTTPS proxy only allows connecting to certain
678 ports.
679 HTTPSProxyAuthenticator username:password
681 If defined, Tor will use this username:password for Basic HTTPS
682 proxy authentication, as in RFC 2617. This is currently the only
683 form of HTTPS proxy authentication that Tor supports; feel free to
684 submit a patch if you want it to support others.
685 KeepalivePeriod NUM
687 To keep firewalls from expiring connections, send a padding
688 keepalive cell every NUM seconds on open connections that are in
689 use. (Default: 5 minutes)
690 KeepBindCapabilities 0|1|auto
692 On Linux, when we are started as root and we switch our identity
693 using the User option, the KeepBindCapabilities option tells us
694 whether to try to retain our ability to bind to low ports. If this
695 value is 1, we try to keep the capability; if it is 0 we do not;
696 and if it is auto, we keep the capability only if we are configured
697 to listen on a low port. Can not be changed while tor is running.
698 (Default: auto.)
699 Log minSeverity[-maxSeverity] stderr|stdout|syslog
701 Send all messages between minSeverity and maxSeverity to the
702 standard output stream, the standard error stream, or to the system
703 log. (The "syslog" value is only supported on Unix.) Recognized
704 severity levels are debug, info, notice, warn, and err. We advise
705 using "notice" in most cases, since anything more verbose may
706 provide sensitive information to an attacker who obtains the logs.
707 If only one severity level is given, all messages of that level or
708 higher will be sent to the listed destination.
709 Some low-level logs may be sent from signal handlers, so their
712 destination logs must be signal-safe. These low-level logs include
713 backtraces, logging function errors, and errors in code called by
714 logging functions. Signal-safe logs are always sent to stderr or
715 stdout. They are also sent to a limited number of log files that
716 are configured to log messages at error severity from the bug or
717 general domains. They are never sent as syslogs, control port log
718 events, or to any API-based log destinations.
719 Log minSeverity[-maxSeverity] file FILENAME
721 As above, but send log messages to the listed filename. The "Log"
722 option may appear more than once in a configuration file. Messages
723 are sent to all the logs that match their severity level.
724 Log [domain,...]minSeverity[-maxSeverity] ... file FILENAME
726 Log [domain,...]minSeverity[-maxSeverity] ... stderr|stdout|syslog
728 As above, but select messages by range of log severity and by a set
729 of "logging domains". Each logging domain corresponds to an area of
730 functionality inside Tor. You can specify any number of severity
731 ranges for a single log statement, each of them prefixed by a
732 comma-separated list of logging domains. You can prefix a domain
733 with ~ to indicate negation, and use * to indicate "all domains".
734 If you specify a severity range without a list of domains, it
735 matches all domains.
736 This is an advanced feature which is most useful for debugging one
739 or two of Tor’s subsystems at a time.
740 The currently recognized domains are: general, crypto, net, config,
743 fs, protocol, mm, http, app, control, circ, rend, bug, dir,
744 dirserv, or, edge, acct, hist, handshake, heartbeat, channel,
745 sched, guard, consdiff, dos, process, pt, btrack, and mesg. Domain
746 names are case-insensitive.
747 For example, "Log [handshake]debug [~net,~mm]info notice stdout"
750 sends to stdout: all handshake messages of any severity, all
751 info-and-higher messages from domains other than networking and
752 memory management, and all messages of severity notice or higher.
753 LogMessageDomains 0|1
755 If 1, Tor includes message domains with each log message. Every log
756 message currently has at least one domain; most currently have
757 exactly one. This doesn’t affect controller log messages. (Default:
758 0)
759 LogTimeGranularity NUM
761 Set the resolution of timestamps in Tor’s logs to NUM milliseconds.
762 NUM must be positive and either a divisor or a multiple of 1
763 second. Note that this option only controls the granularity written
764 by Tor to a file or console log. Tor does not (for example) "batch
765 up" log messages to affect times logged by a controller, times
766 attached to syslog messages, or the mtime fields on log files.
767 (Default: 1 second)
768 MaxAdvertisedBandwidth N
770 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
771 If set, we will not advertise more than this amount of bandwidth
772 for our BandwidthRate. Server operators who want to reduce the
773 number of clients who ask to build circuits through them (since
774 this is proportional to advertised bandwidth rate) can thus reduce
775 the CPU demands on their server without impacting network
776 performance.
777 MaxUnparseableDescSizeToLog N bytes|KBytes|MBytes|GBytes|TBytes
779 Unparseable descriptors (e.g. for votes, consensuses, routers) are
780 logged in separate files by hash, up to the specified size in
781 total. Note that only files logged during the lifetime of this Tor
782 process count toward the total; this is intended to be used to
783 debug problems without opening live servers to resource exhaustion
784 attacks. (Default: 10 MBytes)
785 MetricsPort [address:]port [format]
787 WARNING: Before enabling this, it is important to understand that
788 exposing tor metrics publicly is dangerous to the Tor network
789 users. Please take extra precaution and care when opening this
790 port. Set a very strict access policy with MetricsPortPolicy and
791 consider using your operating systems firewall features for defense
792 in depth.
793 We recommend, for the prometheus format, that the only address that
795 can access this port should be the Prometheus server itself.
796 Remember that the connection is unencrypted (HTTP) hence consider
797 using a tool like stunnel to secure the link from this port to the
798 server.
799 If set, open this port to listen for an HTTP GET request to
801 "/metrics". Upon a request, the collected metrics in the the tor
802 instance are formatted for the given format and then sent back. If
803 this is set, MetricsPortPolicy must be defined else every request
804 will be rejected.
805 Supported format is "prometheus" which is also the default if not
807 set. The Prometheus data model can be found here:
808 https://prometheus.io/docs/concepts/data_model/
809 The tor metrics are constantly collected and they solely consists
811 of counters. Thus, asking for those metrics is very lightweight on
812 the tor process. (Default: None)
813 As an example, here only 5.6.7.8 will be allowed to connect:
815 MetricsPort 1.2.3.4:9035
817 MetricsPortPolicy accept 5.6.7.8
818 MetricsPortPolicy policy,policy,...
820 Set an entrance policy for the MetricsPort, to limit who can access
821 it. The policies have the same form as exit policies below, except
822 that port specifiers are ignored. For multiple entries, this line
823 can be used multiple times. It is a reject all by default policy.
824 (Default: None)
825 Please, keep in mind here that if the server collecting metrics on
827 the MetricsPort is behind a NAT, then everything behind it can
828 access it. This is similar for the case of allowing localhost,
829 every users on the server will be able to access it. Again,
830 strongly consider using a tool like stunnel to secure the link or
831 to strengthen access control.
832 NoExec 0|1
834 If this option is set to 1, then Tor will never launch another
835 executable, regardless of the settings of ClientTransportPlugin or
836 ServerTransportPlugin. Once this option has been set to 1, it
837 cannot be set back to 0 without restarting Tor. (Default: 0)
838 OutboundBindAddress IP
840 Make all outbound connections originate from the IP address
841 specified. This is only useful when you have multiple network
842 interfaces, and you want all of Tor’s outgoing connections to use a
843 single one. This option may be used twice, once with an IPv4
844 address and once with an IPv6 address. IPv6 addresses should be
845 wrapped in square brackets. This setting will be ignored for
846 connections to the loopback addresses (127.0.0.0/8 and ::1), and is
847 not used for DNS requests as well.
848 OutboundBindAddressExit IP
850 Make all outbound exit connections originate from the IP address
851 specified. This option overrides OutboundBindAddress for the same
852 IP version. This option may be used twice, once with an IPv4
853 address and once with an IPv6 address. IPv6 addresses should be
854 wrapped in square brackets. This setting will be ignored for
855 connections to the loopback addresses (127.0.0.0/8 and ::1).
856 OutboundBindAddressOR IP
858 Make all outbound non-exit (relay and other) connections originate
859 from the IP address specified. This option overrides
860 OutboundBindAddress for the same IP version. This option may be
861 used twice, once with an IPv4 address and once with an IPv6
862 address. IPv6 addresses should be wrapped in square brackets. This
863 setting will be ignored for connections to the loopback addresses
864 (127.0.0.0/8 and ::1).
865 __OwningControllerProcess PID
867 Make Tor instance periodically check for presence of a controller
868 process with given PID and terminate itself if this process is no
869 longer alive. Polling interval is 15 seconds.
870 PerConnBWBurst N
872 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
873 If this option is set manually, or via the "perconnbwburst"
874 consensus field, Tor will use it for separate rate limiting for
875 each connection from a non-relay. (Default: 0)
876 PerConnBWRate N
878 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
879 If this option is set manually, or via the "perconnbwrate"
880 consensus field, Tor will use it for separate rate limiting for
881 each connection from a non-relay. (Default: 0)
882 OutboundBindAddressPT IP
884 Request that pluggable transports makes all outbound connections
885 originate from the IP address specified. Because outgoing
886 connections are handled by the pluggable transport itself, it is
887 not possible for Tor to enforce whether the pluggable transport
888 honors this option. This option overrides OutboundBindAddress for
889 the same IP version. This option may be used twice, once with an
890 IPv4 address and once with an IPv6 address. IPv6 addresses should
891 be wrapped in square brackets. This setting will be ignored for
892 connections to the loopback addresses (127.0.0.0/8 and ::1).
893 PidFile FILE
895 On startup, write our PID to FILE. On clean shutdown, remove FILE.
896 Can not be changed while tor is running.
897 ProtocolWarnings 0|1
899 If 1, Tor will log with severity 'warn' various cases of other
900 parties not following the Tor specification. Otherwise, they are
901 logged with severity 'info'. (Default: 0)
902 RelayBandwidthBurst N
904 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
905 If not 0, limit the maximum token bucket size (also known as the
906 burst) for _relayed traffic_ to the given number of bytes in each
907 direction. They do not include directory fetches by the relay (from
908 authority or other relays), because that is considered "client"
909 activity. (Default: 0)
910 RelayBandwidthRate N
912 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
913 If not 0, a separate token bucket limits the average incoming
914 bandwidth usage for _relayed traffic_ on this node to the specified
915 number of bytes per second, and the average outgoing bandwidth
916 usage to that same value. Relayed traffic currently is calculated
917 to include answers to directory requests, but that may change in
918 future versions. They do not include directory fetches by the relay
919 (from authority or other relays), because that is considered
920 "client" activity. (Default: 0)
921 RephistTrackTime N seconds|minutes|hours|days|weeks
923 Tells an authority, or other node tracking node reliability and
924 history, that fine-grained information about nodes can be discarded
925 when it hasn’t changed for a given amount of time. (Default: 24
926 hours)
927 RunAsDaemon 0|1
929 If 1, Tor forks and daemonizes to the background. This option has
930 no effect on Windows; instead you should use the --service
931 command-line option. Can not be changed while tor is running.
932 (Default: 0)
933 SafeLogging 0|1|relay
935 Tor can scrub potentially sensitive strings from log messages (e.g.
936 addresses) by replacing them with the string [scrubbed]. This way
937 logs can still be useful, but they don’t leave behind personally
938 identifying information about what sites a user might have visited.
939 If this option is set to 0, Tor will not perform any scrubbing, if
942 it is set to 1, all potentially sensitive strings are replaced. If
943 it is set to relay, all log messages generated when acting as a
944 relay are sanitized, but all messages generated when acting as a
945 client are not. Note: Tor may not heed this option when logging at
946 log levels below Notice. (Default: 1)
947 Sandbox 0|1
949 If set to 1, Tor will run securely through the use of a syscall
950 sandbox. Otherwise the sandbox will be disabled. The option only
951 works on Linux-based operating systems, and only when Tor has been
952 built with the libseccomp library. Note that this option may be
953 incompatible with some versions of libc, and some kernel versions.
954 This option can not be changed while tor is running.
955 When the Sandbox is 1, the following options can not be changed
958 when tor is running: Address, ConnLimit, CookieAuthFile,
959 DirPortFrontPage, ExtORPortCookieAuthFile, Logs,
960 ServerDNSResolvConfFile, ClientOnionAuthDir (and any files in it
961 won’t reload on HUP signal).
962 Launching new Onion Services through the control port is not
965 supported with current syscall sandboxing implementation.
966 Tor must remain in client or server mode (some changes to
969 ClientOnly and ORPort are not allowed). Currently, if Sandbox is 1,
970 ControlPort command "GETINFO address" will not work.
971 When using %include in the tor configuration files, reloading the
974 tor configuration is not supported after adding new configuration
975 files or directories.
976 (Default: 0)
979 Schedulers KIST|KISTLite|Vanilla
981 Specify the scheduler type that tor should use. The scheduler is
982 responsible for moving data around within a Tor process. This is an
983 ordered list by priority which means that the first value will be
984 tried first and if unavailable, the second one is tried and so on.
985 It is possible to change these values at runtime. This option
986 mostly effects relays, and most operators should leave it set to
987 its default value. (Default: KIST,KISTLite,Vanilla)
988 The possible scheduler types are:
991 KIST: Kernel-Informed Socket Transport. Tor will use TCP
993 information from the kernel to make informed decisions regarding
994 how much data to send and when to send it. KIST also handles
995 traffic in batches (see KISTSchedRunInterval) in order to improve
996 traffic prioritization decisions. As implemented, KIST will only
997 work on Linux kernel version 2.6.39 or higher.
998 KISTLite: Same as KIST but without kernel support. Tor will use all
1001 the same mechanics as with KIST, including the batching, but its
1002 decisions regarding how much data to send will not be as good.
1003 KISTLite will work on all kernels and operating systems, and the
1004 majority of the benefits of KIST are still realized with KISTLite.
1005 Vanilla: The scheduler that Tor used before KIST was implemented.
1008 It sends as much data as possible, as soon as possible. Vanilla
1009 will work on all kernels and operating systems.
1010 KISTSchedRunInterval NUM msec
1012 If KIST or KISTLite is used in the Schedulers option, this controls
1013 at which interval the scheduler tick is. If the value is 0 msec,
1014 the value is taken from the consensus if possible else it will
1015 fallback to the default 10 msec. Maximum possible value is 100
1016 msec. (Default: 0 msec)
1017 KISTSockBufSizeFactor NUM
1019 If KIST is used in Schedulers, this is a multiplier of the
1020 per-socket limit calculation of the KIST algorithm. (Default: 1.0)
1021 Socks4Proxy host[:port]
1023 Tor will make all OR connections through the SOCKS 4 proxy at
1024 host:port (or host:1080 if port is not specified).
1025 Socks5Proxy host[:port]
1027 Tor will make all OR connections through the SOCKS 5 proxy at
1028 host:port (or host:1080 if port is not specified).
1029 Socks5ProxyUsername username
1031 Socks5ProxyPassword password
1033 If defined, authenticate to the SOCKS 5 server using username and
1034 password in accordance to RFC 1929. Both username and password must
1035 be between 1 and 255 characters.
1036 SyslogIdentityTag tag
1038 When logging to syslog, adds a tag to the syslog identity such that
1039 log entries are marked with "Tor-tag". Can not be changed while tor
1040 is running. (Default: none)
1041 TCPProxy protocol host:port
1043 Tor will use the given protocol to make all its OR (SSL)
1044 connections through a TCP proxy on host:port, rather than
1045 connecting directly to servers. You may want to set FascistFirewall
1046 to restrict the set of ports you might try to connect to, if your
1047 proxy only allows connecting to certain ports. There is no
1048 equivalent option for directory connections, because all Tor client
1049 versions that support this option download directory documents via
1050 OR connections.
1051 The only protocol supported right now 'haproxy'. This option is only for
1054 clients. (Default: none) +
1055 The HAProxy version 1 proxy protocol is described in detail at
1057 https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt +
1058 Both source IP address and source port will be set to zero.
1060 TruncateLogFile 0|1
1062 If 1, Tor will overwrite logs at startup and in response to a HUP
1063 signal, instead of appending to them. (Default: 0)
1064 UnixSocksGroupWritable 0|1
1066 If this option is set to 0, don’t allow the filesystem group to
1067 read and write unix sockets (e.g. SocksPort unix:). If the option
1068 is set to 1, make the Unix socket readable and writable by the
1069 default GID. (Default: 0)
1070 UseDefaultFallbackDirs 0|1
1072 Use Tor’s default hard-coded FallbackDirs (if any). (When a
1073 FallbackDir line is present, it replaces the hard-coded
1074 FallbackDirs, regardless of the value of UseDefaultFallbackDirs.)
1075 (Default: 1)
1076 User Username
1078 On startup, setuid to this user and setgid to their primary group.
1079 Can not be changed while tor is running.
1080
1082 The following options are useful only for clients (that is, if
1083 SocksPort, HTTPTunnelPort, TransPort, DNSPort, or NATDPort is
1084 non-zero):
1085 AllowNonRFC953Hostnames 0|1
1087 When this option is disabled, Tor blocks hostnames containing
1088 illegal characters (like @ and :) rather than sending them to an
1089 exit node to be resolved. This helps trap accidental attempts to
1090 resolve URLs and so on. (Default: 0)
1091 AutomapHostsOnResolve 0|1
1093 When this option is enabled, and we get a request to resolve an
1094 address that ends with one of the suffixes in AutomapHostsSuffixes,
1095 we map an unused virtual address to that address, and return the
1096 new virtual address. This is handy for making ".onion" addresses
1097 work with applications that resolve an address and then connect to
1098 it. (Default: 0)
1099 AutomapHostsSuffixes SUFFIX,SUFFIX,...
1101 A comma-separated list of suffixes to use with
1102 AutomapHostsOnResolve. The "." suffix is equivalent to "all
1103 addresses." (Default: .exit,.onion).
1104 Bridge [transport] IP:ORPort [fingerprint]
1106 When set along with UseBridges, instructs Tor to use the relay at
1107 "IP:ORPort" as a "bridge" relaying into the Tor network. If
1108 "fingerprint" is provided (using the same format as for
1109 DirAuthority), we will verify that the relay running at that
1110 location has the right fingerprint. We also use fingerprint to look
1111 up the bridge descriptor at the bridge authority, if it’s provided
1112 and if UpdateBridgesFromAuthority is set too.
1113 If "transport" is provided, it must match a ClientTransportPlugin
1116 line. We then use that pluggable transport’s proxy to transfer data
1117 to the bridge, rather than connecting to the bridge directly. Some
1118 transports use a transport-specific method to work out the remote
1119 address to connect to. These transports typically ignore the
1120 "IP:ORPort" specified in the bridge line.
1121 Tor passes any "key=val" settings to the pluggable transport proxy
1124 as per-connection arguments when connecting to the bridge. Consult
1125 the documentation of the pluggable transport for details of what
1126 arguments it supports.
1127 CircuitPadding 0|1
1129 If set to 0, Tor will not pad client circuits with additional cover
1130 traffic. Only clients may set this option. This option should be
1131 offered via the UI to mobile users for use where bandwidth may be
1132 expensive. If set to 1, padding will be negotiated as per the
1133 consensus and relay support (unlike ConnectionPadding,
1134 CircuitPadding cannot be force-enabled). (Default: 1)
1135 ReducedCircuitPadding 0|1
1137 If set to 1, Tor will only use circuit padding algorithms that have
1138 low overhead. Only clients may set this option. This option should
1139 be offered via the UI to mobile users for use where bandwidth may
1140 be expensive. (Default: 0)
1141 ClientBootstrapConsensusAuthorityDownloadInitialDelay N
1143 Initial delay in seconds for when clients should download
1144 consensuses from authorities if they are bootstrapping (that is,
1145 they don’t have a usable, reasonably live consensus). Only used by
1146 clients fetching from a list of fallback directory mirrors. This
1147 schedule is advanced by (potentially concurrent) connection
1148 attempts, unlike other schedules, which are advanced by connection
1149 failures. (Default: 6)
1150 ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay N
1152 Initial delay in seconds for when clients should download
1153 consensuses from authorities if they are bootstrapping (that is,
1154 they don’t have a usable, reasonably live consensus). Only used by
1155 clients which don’t have or won’t fetch from a list of fallback
1156 directory mirrors. This schedule is advanced by (potentially
1157 concurrent) connection attempts, unlike other schedules, which are
1158 advanced by connection failures. (Default: 0)
1159 ClientBootstrapConsensusFallbackDownloadInitialDelay N
1161 Initial delay in seconds for when clients should download
1162 consensuses from fallback directory mirrors if they are
1163 bootstrapping (that is, they don’t have a usable, reasonably live
1164 consensus). Only used by clients fetching from a list of fallback
1165 directory mirrors. This schedule is advanced by (potentially
1166 concurrent) connection attempts, unlike other schedules, which are
1167 advanced by connection failures. (Default: 0)
1168 ClientBootstrapConsensusMaxInProgressTries NUM
1170 Try this many simultaneous connections to download a consensus
1171 before waiting for one to complete, timeout, or error out.
1172 (Default: 3)
1173 ClientDNSRejectInternalAddresses 0|1
1175 If true, Tor does not believe any anonymously retrieved DNS answer
1176 that tells it that an address resolves to an internal address (like
1177 127.0.0.1 or 192.168.0.1). This option prevents certain
1178 browser-based attacks; it is not allowed to be set on the default
1179 network. (Default: 1)
1180 ClientOnionAuthDir path
1182 Path to the directory containing v3 hidden service authorization
1183 files. Each file is for a single onion address, and the files MUST
1184 have the suffix ".auth_private" (i.e. "bob_onion.auth_private").
1185 The content format MUST be:
1186 <onion-address>:descriptor:x25519:<base32-encoded-privkey>
1188 The <onion-address> MUST NOT have the ".onion" suffix. The
1190 <base32-encoded-privkey> is the base32 representation of the raw
1191 key bytes only (32 bytes for x25519). See Appendix G in the
1192 rend-spec-v3.txt file of torspec for more information.
1193 ClientOnly 0|1
1195 If set to 1, Tor will not run as a relay or serve directory
1196 requests, even if the ORPort, ExtORPort, or DirPort options are
1197 set. (This config option is mostly unnecessary: we added it back
1198 when we were considering having Tor clients auto-promote themselves
1199 to being relays if they were stable and fast enough. The current
1200 behavior is simply that Tor is a client unless ORPort, ExtORPort,
1201 or DirPort are configured.) (Default: 0)
1202 ClientPreferIPv6DirPort 0|1|auto
1204 If this option is set to 1, Tor prefers a directory port with an
1205 IPv6 address over one with IPv4, for direct connections, if a given
1206 directory server has both. (Tor also prefers an IPv6 DirPort if
1207 IPv4Client is set to 0.) If this option is set to auto, clients
1208 prefer IPv4. Other things may influence the choice. This option
1209 breaks a tie to the favor of IPv6. (Default: auto) (DEPRECATED:
1210 This option has had no effect for some time.)
1211 ClientPreferIPv6ORPort 0|1|auto
1213 If this option is set to 1, Tor prefers an OR port with an IPv6
1214 address over one with IPv4 if a given entry node has both. (Tor
1215 also prefers an IPv6 ORPort if IPv4Client is set to 0.) If this
1216 option is set to auto, Tor bridge clients prefer the configured
1217 bridge address, and other clients prefer IPv4. Other things may
1218 influence the choice. This option breaks a tie to the favor of
1219 IPv6. (Default: auto)
1220 ClientRejectInternalAddresses 0|1
1222 If true, Tor does not try to fulfill requests to connect to an
1223 internal address (like 127.0.0.1 or 192.168.0.1) unless an exit
1224 node is specifically requested (for example, via a .exit hostname,
1225 or a controller request). If true, multicast DNS hostnames for
1226 machines on the local network (of the form *.local) are also
1227 rejected. (Default: 1)
1228 ClientUseIPv4 0|1
1230 If this option is set to 0, Tor will avoid connecting to directory
1231 servers and entry nodes over IPv4. Note that clients with an IPv4
1232 address in a Bridge, proxy, or pluggable transport line will try
1233 connecting over IPv4 even if ClientUseIPv4 is set to 0. (Default:
1234 1)
1235 ClientUseIPv6 0|1
1237 If this option is set to 1, Tor might connect to directory servers
1238 or entry nodes over IPv6. For IPv6 only hosts, you need to also set
1239 ClientUseIPv4 to 0 to disable IPv4. Note that clients configured
1240 with an IPv6 address in a Bridge, proxy, or pluggable transportline
1241 will try connecting over IPv6 even if ClientUseIPv6 is set to 0.
1242 (Default: 0)
1243 ConnectionPadding 0|1|auto
1245 This option governs Tor’s use of padding to defend against some
1246 forms of traffic analysis. If it is set to auto, Tor will send
1247 padding only if both the client and the relay support it. If it is
1248 set to 0, Tor will not send any padding cells. If it is set to 1,
1249 Tor will still send padding for client connections regardless of
1250 relay support. Only clients may set this option. This option should
1251 be offered via the UI to mobile users for use where bandwidth may
1252 be expensive. (Default: auto)
1253 ReducedConnectionPadding 0|1
1255 If set to 1, Tor will not not hold OR connections open for very
1256 long, and will send less padding on these connections. Only clients
1257 may set this option. This option should be offered via the UI to
1258 mobile users for use where bandwidth may be expensive. (Default: 0)
1259 DNSPort [address:]port|auto [isolation flags]
1261 If non-zero, open this port to listen for UDP DNS requests, and
1262 resolve them anonymously. This port only handles A, AAAA, and PTR
1263 requests---it doesn’t handle arbitrary DNS request types. Set the
1264 port to "auto" to have Tor pick a port for you. This directive can
1265 be specified multiple times to bind to multiple addresses/ports.
1266 See SocksPort for an explanation of isolation flags. (Default: 0)
1267 DownloadExtraInfo 0|1
1269 If true, Tor downloads and caches "extra-info" documents. These
1270 documents contain information about servers other than the
1271 information in their regular server descriptors. Tor does not use
1272 this information for anything itself; to save bandwidth, leave this
1273 option turned off. (Default: 0)
1274 EnforceDistinctSubnets 0|1
1276 If 1, Tor will not put two servers whose IP addresses are "too
1277 close" on the same circuit. Currently, two addresses are "too
1278 close" if they lie in the same /16 range. (Default: 1)
1279 FascistFirewall 0|1
1281 If 1, Tor will only create outgoing connections to ORs running on
1282 ports that your firewall allows (defaults to 80 and 443; see
1283 FirewallPorts). This will allow you to run Tor as a client behind a
1284 firewall with restrictive policies, but will not allow you to run
1285 as a server behind such a firewall. If you prefer more fine-grained
1286 control, use ReachableAddresses instead.
1287 FirewallPorts PORTS
1289 A list of ports that your firewall allows you to connect to. Only
1290 used when FascistFirewall is set. This option is deprecated; use
1291 ReachableAddresses instead. (Default: 80, 443)
1292 HTTPTunnelPort [address:]port|auto [isolation flags]
1294 Open this port to listen for proxy connections using the "HTTP
1295 CONNECT" protocol instead of SOCKS. Set this to 0 if you don’t want
1296 to allow "HTTP CONNECT" connections. Set the port to "auto" to have
1297 Tor pick a port for you. This directive can be specified multiple
1298 times to bind to multiple addresses/ports. If multiple entries of
1299 this option are present in your configuration file, Tor will
1300 perform stream isolation between listeners by default. See
1301 SocksPort for an explanation of isolation flags. (Default: 0)
1302 LongLivedPorts PORTS
1304 A list of ports for services that tend to have long-running
1305 connections (e.g. chat and interactive shells). Circuits for
1306 streams that use these ports will contain only high-uptime nodes,
1307 to reduce the chance that a node will go down before the stream is
1308 finished. Note that the list is also honored for circuits (both
1309 client and service side) involving hidden services whose virtual
1310 port is in this list. (Default: 21, 22, 706, 1863, 5050, 5190,
1311 5222, 5223, 6523, 6667, 6697, 8300)
1312 MapAddress address newaddress
1314 When a request for address arrives to Tor, it will transform to
1315 newaddress before processing it. For example, if you always want
1316 connections to www.example.com to exit via torserver (where
1317 torserver is the fingerprint of the server), use "MapAddress
1318 www.example.com www.example.com.torserver.exit". If the value is
1319 prefixed with a "*.", matches an entire domain. For example, if you
1320 always want connections to example.com and any if its subdomains to
1321 exit via torserver (where torserver is the fingerprint of the
1322 server), use "MapAddress *.example.com
1323 *.example.com.torserver.exit". (Note the leading "*." in each part
1324 of the directive.) You can also redirect all subdomains of a domain
1325 to a single address. For example, "MapAddress *.example.com
1326 www.example.com". If the specified exit is not available, or the
1327 exit can not connect to the site, Tor will fail any connections to
1328 the mapped address.+
1329 NOTES:
1331 1. When evaluating MapAddress expressions Tor stops when it hits
1333 the most recently added expression that matches the requested
1334 address. So if you have the following in your torrc,
1335 www.torproject.org will map to 198.51.100.1:
1336 MapAddress www.torproject.org 192.0.2.1
1338 MapAddress www.torproject.org 198.51.100.1
1339 2. Tor evaluates the MapAddress configuration until it finds no
1341 matches. So if you have the following in your torrc,
1342 www.torproject.org will map to 203.0.113.1:
1343 MapAddress 198.51.100.1 203.0.113.1
1345 MapAddress www.torproject.org 198.51.100.1
1346 3. The following MapAddress expression is invalid (and will be
1348 ignored) because you cannot map from a specific address to a
1349 wildcard address:
1350 MapAddress www.torproject.org *.torproject.org.torserver.exit
1352 4. Using a wildcard to match only part of a string (as in
1354 *ample.com) is also invalid.
1355 5. Tor maps hostnames and IP addresses separately. If you
1357 MapAddress a DNS name, but use an IP address to connect, then
1358 Tor will ignore the DNS name mapping.
1359 6. MapAddress does not apply to redirects in the application
1361 protocol. For example, HTTP redirects and alt-svc headers will
1362 ignore mappings for the original address. You can use a
1363 wildcard mapping to handle redirects within the same site.
1364 MaxCircuitDirtiness NUM
1366 Feel free to reuse a circuit that was first used at most NUM
1367 seconds ago, but never attach a new stream to a circuit that is too
1368 old. For hidden services, this applies to the last time a circuit
1369 was used, not the first. Circuits with streams constructed with
1370 SOCKS authentication via SocksPorts that have
1371 KeepAliveIsolateSOCKSAuth also remain alive for MaxCircuitDirtiness
1372 seconds after carrying the last such stream. (Default: 10 minutes)
1373 MaxClientCircuitsPending NUM
1375 Do not allow more than NUM circuits to be pending at a time for
1376 handling client streams. A circuit is pending if we have begun
1377 constructing it, but it has not yet been completely constructed.
1378 (Default: 32)
1379 NATDPort [address:]port|auto [isolation flags]
1381 Open this port to listen for connections from old versions of ipfw
1382 (as included in old versions of FreeBSD, etc) using the NATD
1383 protocol. Use 0 if you don’t want to allow NATD connections. Set
1384 the port to "auto" to have Tor pick a port for you. This directive
1385 can be specified multiple times to bind to multiple
1386 addresses/ports. If multiple entries of this option are present in
1387 your configuration file, Tor will perform stream isolation between
1388 listeners by default. See SocksPort for an explanation of isolation
1389 flags.
1390 This option is only for people who cannot use TransPort. (Default:
1393 0)
1394 NewCircuitPeriod NUM
1396 Every NUM seconds consider whether to build a new circuit.
1397 (Default: 30 seconds)
1398 PathBiasCircThreshold NUM
1400 PathBiasDropGuards NUM
1402 PathBiasExtremeRate NUM
1404 PathBiasNoticeRate NUM
1406 PathBiasWarnRate NUM
1408 PathBiasScaleThreshold NUM
1410 These options override the default behavior of Tor’s (currently
1411 experimental) path bias detection algorithm. To try to find broken
1412 or misbehaving guard nodes, Tor looks for nodes where more than a
1413 certain fraction of circuits through that guard fail to get built.
1414 The PathBiasCircThreshold option controls how many circuits we need
1417 to build through a guard before we make these checks. The
1418 PathBiasNoticeRate, PathBiasWarnRate and PathBiasExtremeRate
1419 options control what fraction of circuits must succeed through a
1420 guard so we won’t write log messages. If less than
1421 PathBiasExtremeRate circuits succeed and PathBiasDropGuards is set
1422 to 1, we disable use of that guard.
1423 When we have seen more than PathBiasScaleThreshold circuits through
1426 a guard, we scale our observations by 0.5 (governed by the
1427 consensus) so that new observations don’t get swamped by old ones.
1428 By default, or if a negative value is provided for one of these
1431 options, Tor uses reasonable defaults from the networkstatus
1432 consensus document. If no defaults are available there, these
1433 options default to 150, .70, .50, .30, 0, and 300 respectively.
1434 PathBiasUseThreshold NUM
1436 PathBiasNoticeUseRate NUM
1438 PathBiasExtremeUseRate NUM
1440 PathBiasScaleUseThreshold NUM
1442 Similar to the above options, these options override the default
1443 behavior of Tor’s (currently experimental) path use bias detection
1444 algorithm.
1445 Where as the path bias parameters govern thresholds for
1448 successfully building circuits, these four path use bias parameters
1449 govern thresholds only for circuit usage. Circuits which receive no
1450 stream usage are not counted by this detection algorithm. A used
1451 circuit is considered successful if it is capable of carrying
1452 streams or otherwise receiving well-formed responses to RELAY
1453 cells.
1454 By default, or if a negative value is provided for one of these
1457 options, Tor uses reasonable defaults from the networkstatus
1458 consensus document. If no defaults are available there, these
1459 options default to 20, .80, .60, and 100, respectively.
1460 PathsNeededToBuildCircuits NUM
1462 Tor clients don’t build circuits for user traffic until they know
1463 about enough of the network so that they could potentially
1464 construct enough of the possible paths through the network. If this
1465 option is set to a fraction between 0.25 and 0.95, Tor won’t build
1466 circuits until it has enough descriptors or microdescriptors to
1467 construct that fraction of possible paths. Note that setting this
1468 option too low can make your Tor client less anonymous, and setting
1469 it too high can prevent your Tor client from bootstrapping. If this
1470 option is negative, Tor will use a default value chosen by the
1471 directory authorities. If the directory authorities do not choose a
1472 value, Tor will default to 0.6. (Default: -1)
1473 ReachableAddresses IP[/MASK][:PORT]...
1475 A comma-separated list of IP addresses and ports that your firewall
1476 allows you to connect to. The format is as for the addresses in
1477 ExitPolicy, except that "accept" is understood unless "reject" is
1478 explicitly provided. For example, 'ReachableAddresses 99.0.0.0/8,
1479 reject 18.0.0.0/8:80, accept *:80' means that your firewall allows
1480 connections to everything inside net 99, rejects port 80
1481 connections to net 18, and accepts connections to port 80
1482 otherwise. (Default: 'accept *:*'.)
1483 ReachableDirAddresses IP[/MASK][:PORT]...
1485 Like ReachableAddresses, a list of addresses and ports. Tor will
1486 obey these restrictions when fetching directory information, using
1487 standard HTTP GET requests. If not set explicitly then the value of
1488 ReachableAddresses is used. If HTTPProxy is set then these
1489 connections will go through that proxy. (DEPRECATED: This option
1490 has had no effect for some time.)
1491 ReachableORAddresses IP[/MASK][:PORT]...
1493 Like ReachableAddresses, a list of addresses and ports. Tor will
1494 obey these restrictions when connecting to Onion Routers, using
1495 TLS/SSL. If not set explicitly then the value of ReachableAddresses
1496 is used. If HTTPSProxy is set then these connections will go
1497 through that proxy.
1498 The separation between ReachableORAddresses and
1501 ReachableDirAddresses is only interesting when you are connecting
1502 through proxies (see HTTPProxy and HTTPSProxy). Most proxies limit
1503 TLS connections (which Tor uses to connect to Onion Routers) to
1504 port 443, and some limit HTTP GET requests (which Tor uses for
1505 fetching directory information) to port 80.
1506 SafeSocks 0|1
1508 When this option is enabled, Tor will reject application
1509 connections that use unsafe variants of the socks protocol — ones
1510 that only provide an IP address, meaning the application is doing a
1511 DNS resolve first. Specifically, these are socks4 and socks5 when
1512 not doing remote DNS. (Default: 0)
1513 TestSocks 0|1
1515 When this option is enabled, Tor will make a notice-level log entry
1516 for each connection to the Socks port indicating whether the
1517 request used a safe socks protocol or an unsafe one (see
1518 SafeSocks). This helps to determine whether an application using
1519 Tor is possibly leaking DNS requests. (Default: 0)
1520 WarnPlaintextPorts port,port,...
1522 Tells Tor to issue a warnings whenever the user tries to make an
1523 anonymous connection to one of these ports. This option is designed
1524 to alert users to services that risk sending passwords in the
1525 clear. (Default: 23,109,110,143)
1526 RejectPlaintextPorts port,port,...
1528 Like WarnPlaintextPorts, but instead of warning about risky port
1529 uses, Tor will instead refuse to make the connection. (Default:
1530 None)
1531 SocksPolicy policy,policy,...
1533 Set an entrance policy for this server, to limit who can connect to
1534 the SocksPort and DNSPort ports. The policies have the same form as
1535 exit policies below, except that port specifiers are ignored. Any
1536 address not matched by some entry in the policy is accepted.
1537 SocksPort [address:]port|unix:path|auto [flags] [isolation flags]
1539 Open this port to listen for connections from SOCKS-speaking
1540 applications. Set this to 0 if you don’t want to allow application
1541 connections via SOCKS. Set it to "auto" to have Tor pick a port for
1542 you. This directive can be specified multiple times to bind to
1543 multiple addresses/ports. If a unix domain socket is used, you may
1544 quote the path using standard C escape sequences. Most flags are
1545 off by default, except where specified. Flags that are on by
1546 default can be disabled by putting "No" before the flag name.
1547 (Default: 9050)
1548 NOTE: Although this option allows you to specify an IP address
1551 other than localhost, you should do so only with extreme caution.
1552 The SOCKS protocol is unencrypted and (as we use it)
1553 unauthenticated, so exposing it in this way could leak your
1554 information to anybody watching your network, and allow anybody to
1555 use your computer as an open proxy.
1556 If multiple entries of this option are present in your
1559 configuration file, Tor will perform stream isolation between
1560 listeners by default. The isolation flags arguments give Tor rules
1561 for which streams received on this SocksPort are allowed to share
1562 circuits with one another. Recognized isolation flags are:
1563 IsolateClientAddr
1565 Don’t share circuits with streams from a different client
1566 address. (On by default and strongly recommended when
1567 supported; you can disable it with NoIsolateClientAddr.
1568 Unsupported and force-disabled when using Unix domain sockets.)
1569 IsolateSOCKSAuth
1571 Don’t share circuits with streams for which different SOCKS
1572 authentication was provided. (For HTTPTunnelPort connections,
1573 this option looks at the Proxy-Authorization and
1574 X-Tor-Stream-Isolation headers. On by default; you can disable
1575 it with NoIsolateSOCKSAuth.)
1576 IsolateClientProtocol
1578 Don’t share circuits with streams using a different protocol.
1579 (SOCKS 4, SOCKS 5, HTTPTunnelPort connections, TransPort
1580 connections, NATDPort connections, and DNSPort requests are all
1581 considered to be different protocols.)
1582 IsolateDestPort
1584 Don’t share circuits with streams targeting a different
1585 destination port.
1586 IsolateDestAddr
1588 Don’t share circuits with streams targeting a different
1589 destination address.
1590 KeepAliveIsolateSOCKSAuth
1592 If IsolateSOCKSAuth is enabled, keep alive circuits while they
1593 have at least one stream with SOCKS authentication active.
1594 After such a circuit is idle for more than MaxCircuitDirtiness
1595 seconds, it can be closed.
1596 SessionGroup=INT
1598 If no other isolation rules would prevent it, allow streams on
1599 this port to share circuits with streams from every other port
1600 with the same session group. (By default, streams received on
1601 different SocksPorts, TransPorts, etc are always isolated from
1602 one another. This option overrides that behavior.)
1603 Other recognized flags for a SocksPort are:
1605 NoIPv4Traffic
1607 Tell exits to not connect to IPv4 addresses in response to
1608 SOCKS requests on this connection.
1609 IPv6Traffic
1611 Tell exits to allow IPv6 addresses in response to SOCKS
1612 requests on this connection, so long as SOCKS5 is in use.
1613 (SOCKS4 can’t handle IPv6.)
1614 PreferIPv6
1616 Tells exits that, if a host has both an IPv4 and an IPv6
1617 address, we would prefer to connect to it via IPv6. (IPv4 is
1618 the default.)
1619 NoDNSRequest
1621 Do not ask exits to resolve DNS addresses in SOCKS5 requests.
1622 Tor will connect to IPv4 addresses, IPv6 addresses (if
1623 IPv6Traffic is set) and .onion addresses.
1624 NoOnionTraffic
1626 Do not connect to .onion addresses in SOCKS5 requests.
1627 OnionTrafficOnly
1629 Tell the tor client to only connect to .onion addresses in
1630 response to SOCKS5 requests on this connection. This is
1631 equivalent to NoDNSRequest, NoIPv4Traffic, NoIPv6Traffic. The
1632 corresponding NoOnionTrafficOnly flag is not supported.
1633 CacheIPv4DNS
1635 Tells the client to remember IPv4 DNS answers we receive from
1636 exit nodes via this connection.
1637 CacheIPv6DNS
1639 Tells the client to remember IPv6 DNS answers we receive from
1640 exit nodes via this connection.
1641 GroupWritable
1643 Unix domain sockets only: makes the socket get created as
1644 group-writable.
1645 WorldWritable
1647 Unix domain sockets only: makes the socket get created as
1648 world-writable.
1649 CacheDNS
1651 Tells the client to remember all DNS answers we receive from
1652 exit nodes via this connection.
1653 UseIPv4Cache
1655 Tells the client to use any cached IPv4 DNS answers we have
1656 when making requests via this connection. (NOTE: This option,
1657 or UseIPv6Cache or UseDNSCache, can harm your anonymity, and
1658 probably won’t help performance as much as you might expect.
1659 Use with care!)
1660 UseIPv6Cache
1662 Tells the client to use any cached IPv6 DNS answers we have
1663 when making requests via this connection.
1664 UseDNSCache
1666 Tells the client to use any cached DNS answers we have when
1667 making requests via this connection.
1668 NoPreferIPv6Automap
1670 When serving a hostname lookup request on this port that should
1671 get automapped (according to AutomapHostsOnResolve), if we
1672 could return either an IPv4 or an IPv6 answer, prefer an IPv4
1673 answer. (Tor prefers IPv6 by default.)
1674 PreferSOCKSNoAuth
1676 Ordinarily, when an application offers both "username/password
1677 authentication" and "no authentication" to Tor via SOCKS5, Tor
1678 selects username/password authentication so that
1679 IsolateSOCKSAuth can work. This can confuse some applications,
1680 if they offer a username/password combination then get confused
1681 when asked for one. You can disable this behavior, so that Tor
1682 will select "No authentication" when IsolateSOCKSAuth is
1683 disabled, or when this option is set.
1684 ExtendedErrors
1686 Return extended error code in the SOCKS reply. So far, the
1687 possible errors are:
1688 X'F0' Onion Service Descriptor Can Not be Found
1690 The requested onion service descriptor can't be found on the
1692 hashring and thus not reachable by the client. (v3 only)
1693 X'F1' Onion Service Descriptor Is Invalid
1695 The requested onion service descriptor can't be parsed or
1697 signature validation failed. (v3 only)
1698 X'F2' Onion Service Introduction Failed
1700 All introduction attempts failed either due to a combination of
1702 NACK by the intro point or time out. (v3 only)
1703 X'F3' Onion Service Rendezvous Failed
1705 Every rendezvous circuit has timed out and thus the client is
1707 unable to rendezvous with the service. (v3 only)
1708 X'F4' Onion Service Missing Client Authorization
1710 Client was able to download the requested onion service descriptor
1712 but is unable to decrypt its content because it is missing client
1713 authorization information. (v3 only)
1714 X'F5' Onion Service Wrong Client Authorization
1716 Client was able to download the requested onion service descriptor
1718 but is unable to decrypt its content using the client
1719 authorization information it has. This means the client access
1720 were revoked. (v3 only)
1721 X'F6' Onion Service Invalid Address
1723 The given .onion address is invalid. In one of these cases this
1725 error is returned: address checksum doesn't match, ed25519 public
1726 key is invalid or the encoding is invalid. (v3 only)
1727 X'F7' Onion Service Introduction Timed Out
1729 Similar to X'F2' code but in this case, all introduction attempts
1731 have failed due to a time out. (v3 only)
1732 Flags are processed left to right. If flags conflict, the last flag
1734 on the line is used, and all earlier flags are ignored. No error is
1735 issued for conflicting flags.
1736 TokenBucketRefillInterval NUM [msec|second]
1738 Set the refill delay interval of Tor’s token bucket to NUM
1739 milliseconds. NUM must be between 1 and 1000, inclusive. When Tor
1740 is out of bandwidth, on a connection or globally, it will wait up
1741 to this long before it tries to use that connection again. Note
1742 that bandwidth limits are still expressed in bytes per second: this
1743 option only affects the frequency with which Tor checks to see
1744 whether previously exhausted connections may read again. Can not be
1745 changed while tor is running. (Default: 100 msec)
1746 TrackHostExits host,.domain,...
1748 For each value in the comma separated list, Tor will track recent
1749 connections to hosts that match this value and attempt to reuse the
1750 same exit node for each. If the value is prepended with a '.', it
1751 is treated as matching an entire domain. If one of the values is
1752 just a '.', it means match everything. This option is useful if you
1753 frequently connect to sites that will expire all your
1754 authentication cookies (i.e. log you out) if your IP address
1755 changes. Note that this option does have the disadvantage of making
1756 it more clear that a given history is associated with a single
1757 user. However, most people who would wish to observe this will
1758 observe it through cookies or other protocol-specific means anyhow.
1759 TrackHostExitsExpire NUM
1761 Since exit servers go up and down, it is desirable to expire the
1762 association between host and exit server after NUM seconds. The
1763 default is 1800 seconds (30 minutes).
1764 TransPort [address:]port|auto [isolation flags]
1766 Open this port to listen for transparent proxy connections. Set
1767 this to 0 if you don’t want to allow transparent proxy connections.
1768 Set the port to "auto" to have Tor pick a port for you. This
1769 directive can be specified multiple times to bind to multiple
1770 addresses/ports. If multiple entries of this option are present in
1771 your configuration file, Tor will perform stream isolation between
1772 listeners by default. See SocksPort for an explanation of isolation
1773 flags.
1774 TransPort requires OS support for transparent proxies, such as
1777 BSDs' pf or Linux’s IPTables. If you’re planning to use Tor as a
1778 transparent proxy for a network, you’ll want to examine and change
1779 VirtualAddrNetwork from the default setting. (Default: 0)
1780 TransProxyType default|TPROXY|ipfw|pf-divert
1782 TransProxyType may only be enabled when there is transparent proxy
1783 listener enabled.
1784 Set this to "TPROXY" if you wish to be able to use the TPROXY Linux
1787 module to transparently proxy connections that are configured using
1788 the TransPort option. Detailed information on how to configure the
1789 TPROXY feature can be found in the Linux kernel source tree in the
1790 file Documentation/networking/tproxy.txt.
1791 Set this option to "ipfw" to use the FreeBSD ipfw interface.
1794 On *BSD operating systems when using pf, set this to "pf-divert" to
1797 take advantage of divert-to rules, which do not modify the packets
1798 like rdr-to rules do. Detailed information on how to configure pf
1799 to use divert-to rules can be found in the pf.conf(5) manual page.
1800 On OpenBSD, divert-to is available to use on versions greater than
1801 or equal to OpenBSD 4.4.
1802 Set this to "default", or leave it unconfigured, to use regular
1805 IPTables on Linux, or to use pf rdr-to rules on *BSD systems.
1806 (Default: "default")
1809 UpdateBridgesFromAuthority 0|1
1811 When set (along with UseBridges), Tor will try to fetch bridge
1812 descriptors from the configured bridge authorities when feasible.
1813 It will fall back to a direct request if the authority responds
1814 with a 404. (Default: 0)
1815 UseBridges 0|1
1817 When set, Tor will fetch descriptors for each bridge listed in the
1818 "Bridge" config lines, and use these relays as both entry guards
1819 and directory guards. (Default: 0)
1820 UseEntryGuards 0|1
1822 If this option is set to 1, we pick a few long-term entry servers,
1823 and try to stick with them. This is desirable because constantly
1824 changing servers increases the odds that an adversary who owns some
1825 servers will observe a fraction of your paths. Entry Guards can not
1826 be used by Directory Authorities or Single Onion Services. In these
1827 cases, this option is ignored. (Default: 1)
1828 UseGuardFraction 0|1|auto
1830 This option specifies whether clients should use the guardfraction
1831 information found in the consensus during path selection. If it’s
1832 set to auto, clients will do what the UseGuardFraction consensus
1833 parameter tells them to do. (Default: auto)
1834 GuardLifetime N days|weeks|months
1836 If UseEntryGuards is set, minimum time to keep a guard on our guard
1837 list before picking a new one. If less than one day, we use
1838 defaults from the consensus directory. (Default: 0)
1839 NumDirectoryGuards NUM
1841 If UseEntryGuards is set to 1, we try to make sure we have at least
1842 NUM routers to use as directory guards. If this option is set to 0,
1843 use the value from the guard-n-primary-dir-guards-to-use consensus
1844 parameter, and default to 3 if the consensus parameter isn’t set.
1845 (Default: 0)
1846 NumEntryGuards NUM
1848 If UseEntryGuards is set to 1, we will try to pick a total of NUM
1849 routers as long-term entries for our circuits. If NUM is 0, we try
1850 to learn the number from the guard-n-primary-guards-to-use
1851 consensus parameter, and default to 1 if the consensus parameter
1852 isn’t set. (Default: 0)
1853 NumPrimaryGuards NUM
1855 If UseEntryGuards is set to 1, we will try to pick NUM routers for
1856 our primary guard list, which is the set of routers we strongly
1857 prefer when connecting to the Tor network. If NUM is 0, we try to
1858 learn the number from the guard-n-primary-guards consensus
1859 parameter, and default to 3 if the consensus parameter isn’t set.
1860 (Default: 0)
1861 VanguardsLiteEnabled 0|1|auto
1863 This option specifies whether clients should use the vanguards-lite
1864 subsystem to protect against guard discovery attacks. If it’s set
1865 to auto, clients will do what the vanguards-lite-enabled consensus
1866 parameter tells them to do, and will default to enable the
1867 subsystem if the consensus parameter isn’t set. (Default: auto)
1868 UseMicrodescriptors 0|1|auto
1870 Microdescriptors are a smaller version of the information that Tor
1871 needs in order to build its circuits. Using microdescriptors makes
1872 Tor clients download less directory information, thus saving
1873 bandwidth. Directory caches need to fetch regular descriptors and
1874 microdescriptors, so this option doesn’t save any bandwidth for
1875 them. For legacy reasons, auto is accepted, but it has the same
1876 effect as 1. (Default: auto)
1877 VirtualAddrNetworkIPv4 IPv4Address/bits
1879 VirtualAddrNetworkIPv6 [IPv6Address]/bits
1881 When Tor needs to assign a virtual (unused) address because of a
1882 MAPADDRESS command from the controller or the AutomapHostsOnResolve
1883 feature, Tor picks an unassigned address from this range.
1884 (Defaults: 127.192.0.0/10 and [FE80::]/10 respectively.)
1885 When providing proxy server service to a network of computers using
1888 a tool like dns-proxy-tor, change the IPv4 network to
1889 "10.192.0.0/10" or "172.16.0.0/12" and change the IPv6 network to
1890 "[FC00::]/7". The default VirtualAddrNetwork address ranges on a
1891 properly configured machine will route to the loopback or
1892 link-local interface. The maximum number of bits for the network
1893 prefix is set to 104 for IPv6 and 16 for IPv4. However, a larger
1894 network (that is, one with a smaller prefix length) is preferable,
1895 since it reduces the chances for an attacker to guess the used IP.
1896 For local use, no change to the default VirtualAddrNetwork setting
1897 is needed.
1898
1900 The following options are useful for configuring timeouts related to
1901 building Tor circuits and using them:
1902 CircuitsAvailableTimeout NUM
1904 Tor will attempt to keep at least one open, unused circuit
1905 available for this amount of time. This option governs how long
1906 idle circuits are kept open, as well as the amount of time Tor will
1907 keep a circuit open to each of the recently used ports. This way
1908 when the Tor client is entirely idle, it can expire all of its
1909 circuits, and then expire its TLS connections. Note that the actual
1910 timeout value is uniformly randomized from the specified value to
1911 twice that amount. (Default: 30 minutes; Max: 24 hours)
1912 LearnCircuitBuildTimeout 0|1
1914 If 0, CircuitBuildTimeout adaptive learning is disabled. (Default:
1915 1)
1916 CircuitBuildTimeout NUM
1918 Try for at most NUM seconds when building circuits. If the circuit
1919 isn’t open in that time, give up on it. If LearnCircuitBuildTimeout
1920 is 1, this value serves as the initial value to use before a
1921 timeout is learned. If LearnCircuitBuildTimeout is 0, this value is
1922 the only value used. (Default: 60 seconds)
1923 CircuitStreamTimeout NUM
1925 If non-zero, this option overrides our internal timeout schedule
1926 for how many seconds until we detach a stream from a circuit and
1927 try a new circuit. If your network is particularly slow, you might
1928 want to set this to a number like 60. (Default: 0)
1929 SocksTimeout NUM
1931 Let a socks connection wait NUM seconds handshaking, and NUM
1932 seconds unattached waiting for an appropriate circuit, before we
1933 fail it. (Default: 2 minutes)
1934
1936 Tor can enter dormant mode to conserve power and network bandwidth. The
1937 following options control when Tor enters and leaves dormant mode:
1938 DormantCanceledByStartup 0|1
1940 By default, Tor starts in active mode if it was active the last
1941 time it was shut down, and in dormant mode if it was dormant. But
1942 if this option is true, Tor treats every startup event as user
1943 activity, and Tor will never start in Dormant mode, even if it has
1944 been unused for a long time on previous runs. (Default: 0)
1945 Note: Packagers and application developers should change the value
1947 of this option only with great caution: it has the potential to
1948 create spurious traffic on the network. This option should only be
1949 used if Tor is started by an affirmative user activity (like
1950 clicking on an application or running a command), and not if Tor is
1951 launched for some other reason (for example, by a startup process,
1952 or by an application that launches itself on every login.)
1953 DormantClientTimeout N minutes|hours|days|weeks
1955 If Tor spends this much time without any client activity, enter a
1956 dormant state where automatic circuits are not built, and directory
1957 information is not fetched. Does not affect servers or onion
1958 services. Must be at least 10 minutes. (Default: 24 hours)
1959 DormantOnFirstStartup 0|1
1961 If true, then the first time Tor starts up with a fresh
1962 DataDirectory, it starts in dormant mode, and takes no actions
1963 until the user has made a request. (This mode is recommended if
1964 installing a Tor client for a user who might not actually use it.)
1965 If false, Tor bootstraps the first time it is started, whether it
1966 sees a user request or not.
1967 After the first time Tor starts, it begins in dormant mode if it
1969 was dormant before, and not otherwise. (Default: 0)
1970 DormantTimeoutDisabledByIdleStreams 0|1
1972 If true, then any open client stream (even one not reading or
1973 writing) counts as client activity for the purpose of
1974 DormantClientTimeout. If false, then only network activity counts.
1975 (Default: 1)
1976 DormantTimeoutEnabled 0|1
1978 If false, then no amount of time without activity is sufficient to
1979 make Tor go dormant. Setting this option to zero is only
1980 recommended for special-purpose applications that need to use the
1981 Tor binary for something other than sending or receiving Tor
1982 traffic. (Default: 1)
1983
1985 The following options restrict the nodes that a tor client (or onion
1986 service) can use while building a circuit. These options can weaken
1987 your anonymity by making your client behavior different from other Tor
1988 clients:
1989 EntryNodes node,node,...
1991 A list of identity fingerprints and country codes of nodes to use
1992 for the first hop in your normal circuits. Normal circuits include
1993 all circuits except for direct connections to directory servers.
1994 The Bridge option overrides this option; if you have configured
1995 bridges and UseBridges is 1, the Bridges are used as your entry
1996 nodes.
1997 This option can appear multiple times: the values from multiple
2000 lines are spliced together.
2001 The ExcludeNodes option overrides this option: any node listed in
2004 both EntryNodes and ExcludeNodes is treated as excluded. See
2005 ExcludeNodes for more information on how to specify nodes.
2006 ExcludeNodes node,node,...
2008 A list of identity fingerprints, country codes, and address
2009 patterns of nodes to avoid when building a circuit. Country codes
2010 are 2-letter ISO3166 codes, and must be wrapped in braces;
2011 fingerprints may be preceded by a dollar sign. (Example:
2012 ExcludeNodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, {cc},
2013 255.254.0.0/8)
2014 This option can appear multiple times: the values from multiple
2017 lines are spliced together.
2018 By default, this option is treated as a preference that Tor is
2021 allowed to override in order to keep working. For example, if you
2022 try to connect to a hidden service, but you have excluded all of
2023 the hidden service’s introduction points, Tor will connect to one
2024 of them anyway. If you do not want this behavior, set the
2025 StrictNodes option (documented below).
2026 Note also that if you are a relay, this (and the other node
2029 selection options below) only affects your own circuits that Tor
2030 builds for you. Clients can still build circuits through you to any
2031 node. Controllers can tell Tor to build circuits through any node.
2032 Country codes are case-insensitive. The code "{??}" refers to nodes
2035 whose country can’t be identified. No country code, including {??},
2036 works if no GeoIPFile can be loaded. See also the
2037 GeoIPExcludeUnknown option below.
2038 ExcludeExitNodes node,node,...
2040 A list of identity fingerprints, country codes, and address
2041 patterns of nodes to never use when picking an exit node---that is,
2042 a node that delivers traffic for you outside the Tor network. Note
2043 that any node listed in ExcludeNodes is automatically considered to
2044 be part of this list too. See ExcludeNodes for more information on
2045 how to specify nodes. See also the caveats on the ExitNodes option
2046 below.
2047 This option can appear multiple times: the values from multiple
2049 lines are spliced together.
2050 ExitNodes node,node,...
2053 A list of identity fingerprints, country codes, and address
2054 patterns of nodes to use as exit node---that is, a node that
2055 delivers traffic for you outside the Tor network. See ExcludeNodes
2056 for more information on how to specify nodes.
2057 This option can appear multiple times: the values from multiple
2060 lines are spliced together.
2061 Note that if you list too few nodes here, or if you exclude too
2064 many exit nodes with ExcludeExitNodes, you can degrade
2065 functionality. For example, if none of the exits you list allows
2066 traffic on port 80 or 443, you won’t be able to browse the web.
2067 Note also that not every circuit is used to deliver traffic outside
2070 of the Tor network. It is normal to see non-exit circuits (such as
2071 those used to connect to hidden services, those that do directory
2072 fetches, those used for relay reachability self-tests, and so on)
2073 that end at a non-exit node. To keep a node from being used
2074 entirely, see ExcludeNodes and StrictNodes.
2075 The ExcludeNodes option overrides this option: any node listed in
2078 both ExitNodes and ExcludeNodes is treated as excluded.
2079 The .exit address notation, if enabled via MapAddress, overrides
2082 this option.
2083 GeoIPExcludeUnknown 0|1|auto
2085 If this option is set to auto, then whenever any country code is
2086 set in ExcludeNodes or ExcludeExitNodes, all nodes with unknown
2087 country ({??} and possibly {A1}) are treated as excluded as well.
2088 If this option is set to 1, then all unknown countries are treated
2089 as excluded in ExcludeNodes and ExcludeExitNodes. This option has
2090 no effect when a GeoIP file isn’t configured or can’t be found.
2091 (Default: auto)
2092 HSLayer2Nodes node,node,...
2094 A list of identity fingerprints, nicknames, country codes, and
2095 address patterns of nodes that are allowed to be used as the second
2096 hop in all client or service-side Onion Service circuits. This
2097 option mitigates attacks where the adversary runs middle nodes and
2098 induces your client or service to create many circuits, in order to
2099 discover your primary guard node. (Default: Any node in the network
2100 may be used in the second hop.)
2101 (Example: HSLayer2Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234,
2103 {cc}, 255.254.0.0/8)
2104 This option can appear multiple times: the values from multiple
2107 lines are spliced together.
2108 When this is set, the resulting hidden service paths will look
2111 like:
2112 C - G - L2 - M - Rend
2114 C - G - L2 - M - HSDir
2116 C - G - L2 - M - Intro
2118 S - G - L2 - M - Rend
2120 S - G - L2 - M - HSDir
2122 S - G - L2 - M - Intro
2124 where C is this client, S is the service, G is the Guard node, L2
2127 is a node from this option, and M is a random middle node. Rend,
2128 HSDir, and Intro point selection is not affected by this option.
2129 This option may be combined with HSLayer3Nodes to create paths of
2131 the form:
2132 C - G - L2 - L3 - Rend
2134 C - G - L2 - L3 - M - HSDir
2136 C - G - L2 - L3 - M - Intro
2138 S - G - L2 - L3 - M - Rend
2140 S - G - L2 - L3 - HSDir
2142 S - G - L2 - L3 - Intro
2144 ExcludeNodes have higher priority than HSLayer2Nodes, which means
2147 that nodes specified in ExcludeNodes will not be picked.
2148 When either this option or HSLayer3Nodes are set, the /16 subnet
2150 and node family restrictions are removed for hidden service
2151 circuits. Additionally, we allow the guard node to be present as
2152 the Rend, HSDir, and IP node, and as the hop before it. This is
2153 done to prevent the adversary from inferring information about our
2154 guard, layer2, and layer3 node choices at later points in the path.
2155 This option is meant to be managed by a Tor controller such as
2157 https://github.com/mikeperry-tor/vanguards that selects and updates
2158 this set of nodes for you. Hence it does not do load balancing if
2159 fewer than 20 nodes are selected, and if no nodes in HSLayer2Nodes
2160 are currently available for use, Tor will not work. Please use
2161 extreme care if you are setting this option manually.
2162 HSLayer3Nodes node,node,...
2164 A list of identity fingerprints, nicknames, country codes, and
2165 address patterns of nodes that are allowed to be used as the third
2166 hop in all client and service-side Onion Service circuits. This
2167 option mitigates attacks where the adversary runs middle nodes and
2168 induces your client or service to create many circuits, in order to
2169 discover your primary or Layer2 guard nodes. (Default: Any node in
2170 the network may be used in the third hop.)
2171 (Example: HSLayer3Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234,
2173 {cc}, 255.254.0.0/8)
2174 This option can appear multiple times: the values from multiple
2177 lines are spliced together.
2178 When this is set by itself, the resulting hidden service paths will
2181 look like:
2182 C - G - M - L3 - Rend
2184 C - G - M - L3 - M - HSDir
2186 C - G - M - L3 - M - Intro
2188 S - G - M - L3 - M - Rend
2190 S - G - M - L3 - HSDir
2192 S - G - M - L3 - Intro
2194 where C is this client, S is the service, G is the Guard node, L2
2196 is a node from this option, and M is a random middle node. Rend,
2197 HSDir, and Intro point selection is not affected by this option.
2198 While it is possible to use this option by itself, it should be
2200 combined with HSLayer2Nodes to create paths of the form:
2201 C - G - L2 - L3 - Rend
2203 C - G - L2 - L3 - M - HSDir
2205 C - G - L2 - L3 - M - Intro
2207 S - G - L2 - L3 - M - Rend
2209 S - G - L2 - L3 - HSDir
2211 S - G - L2 - L3 - Intro
2213 ExcludeNodes have higher priority than HSLayer3Nodes, which means
2216 that nodes specified in ExcludeNodes will not be picked.
2217 When either this option or HSLayer2Nodes are set, the /16 subnet
2219 and node family restrictions are removed for hidden service
2220 circuits. Additionally, we allow the guard node to be present as
2221 the Rend, HSDir, and IP node, and as the hop before it. This is
2222 done to prevent the adversary from inferring information about our
2223 guard, layer2, and layer3 node choices at later points in the path.
2224 This option is meant to be managed by a Tor controller such as
2226 https://github.com/mikeperry-tor/vanguards that selects and updates
2227 this set of nodes for you. Hence it does not do load balancing if
2228 fewer than 20 nodes are selected, and if no nodes in HSLayer3Nodes
2229 are currently available for use, Tor will not work. Please use
2230 extreme care if you are setting this option manually.
2231 MiddleNodes node,node,...
2233 A list of identity fingerprints and country codes of nodes to use
2234 for "middle" hops in your normal circuits. Normal circuits include
2235 all circuits except for direct connections to directory servers.
2236 Middle hops are all hops other than exit and entry.
2237 This option can appear multiple times: the values from multiple
2239 lines are spliced together.
2240 This is an experimental feature that is meant to be used by
2243 researchers and developers to test new features in the Tor network
2244 safely. Using it without care will strongly influence your
2245 anonymity. Other tor features may not work with MiddleNodes. This
2246 feature might get removed in the future.
2247 The HSLayer2Node and HSLayer3Node options override this option for onion
2249 service circuits, if they are set. The vanguards addon will read this
2250 option, and if set, it will set HSLayer2Nodes and HSLayer3Nodes to nodes
2251 from this set.
2252 The ExcludeNodes option overrides this option: any node listed in both
2254 MiddleNodes and ExcludeNodes is treated as excluded. See
2255 the <<ExcludeNodes,ExcludeNodes>> for more information on how to specify nodes.
2256 NodeFamily node,node,...
2258 The Tor servers, defined by their identity fingerprints, constitute
2259 a "family" of similar or co-administered servers, so never use any
2260 two of them in the same circuit. Defining a NodeFamily is only
2261 needed when a server doesn’t list the family itself (with
2262 MyFamily). This option can be used multiple times; each instance
2263 defines a separate family. In addition to nodes, you can also list
2264 IP address and ranges and country codes in {curly braces}. See
2265 ExcludeNodes for more information on how to specify nodes.
2266 StrictNodes 0|1
2268 If StrictNodes is set to 1, Tor will treat solely the ExcludeNodes
2269 option as a requirement to follow for all the circuits you
2270 generate, even if doing so will break functionality for you
2271 (StrictNodes does not apply to ExcludeExitNodes, ExitNodes,
2272 MiddleNodes, or MapAddress). If StrictNodes is set to 0, Tor will
2273 still try to avoid nodes in the ExcludeNodes list, but it will err
2274 on the side of avoiding unexpected errors. Specifically,
2275 StrictNodes 0 tells Tor that it is okay to use an excluded node
2276 when it is necessary to perform relay reachability self-tests,
2277 connect to a hidden service, provide a hidden service to a client,
2278 fulfill a .exit request, upload directory information, or download
2279 directory information. (Default: 0)
2280
2282 The following options are useful only for servers (that is, if ORPort
2283 is non-zero):
2284 AccountingMax N
2286 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
2287 Limits the max number of bytes sent and received within a set time
2288 period using a given calculation rule (see AccountingStart and
2289 AccountingRule). Useful if you need to stay under a specific
2290 bandwidth. By default, the number used for calculation is the max
2291 of either the bytes sent or received. For example, with
2292 AccountingMax set to 1 TByte, a server could send 900 GBytes and
2293 receive 800 GBytes and continue running. It will only hibernate
2294 once one of the two reaches 1 TByte. This can be changed to use the
2295 sum of the both bytes received and sent by setting the
2296 AccountingRule option to "sum" (total bandwidth in/out). When the
2297 number of bytes remaining gets low, Tor will stop accepting new
2298 connections and circuits. When the number of bytes is exhausted,
2299 Tor will hibernate until some time in the next accounting period.
2300 To prevent all servers from waking at the same time, Tor will also
2301 wait until a random point in each period before waking up. If you
2302 have bandwidth cost issues, enabling hibernation is preferable to
2303 setting a low bandwidth, since it provides users with a collection
2304 of fast servers that are up some of the time, which is more useful
2305 than a set of slow servers that are always "available".
2306 Note that (as also described in the Bandwidth section) Tor uses
2309 powers of two, not powers of ten: 1 GByte is 1024*1024*1024, not
2310 one billion. Be careful: some internet service providers might
2311 count GBytes differently.
2312 AccountingRule sum|max|in|out
2314 How we determine when our AccountingMax has been reached (when we
2315 should hibernate) during a time interval. Set to "max" to calculate
2316 using the higher of either the sent or received bytes (this is the
2317 default functionality). Set to "sum" to calculate using the sent
2318 plus received bytes. Set to "in" to calculate using only the
2319 received bytes. Set to "out" to calculate using only the sent
2320 bytes. (Default: max)
2321 AccountingStart day|week|month [day] HH:MM
2323 Specify how long accounting periods last. If month is given, each
2324 accounting period runs from the time HH:MM on the dayth day of one
2325 month to the same day and time of the next. The relay will go at
2326 full speed, use all the quota you specify, then hibernate for the
2327 rest of the period. (The day must be between 1 and 28.) If week is
2328 given, each accounting period runs from the time HH:MM of the dayth
2329 day of one week to the same day and time of the next week, with
2330 Monday as day 1 and Sunday as day 7. If day is given, each
2331 accounting period runs from the time HH:MM each day to the same
2332 time on the next day. All times are local, and given in 24-hour
2333 time. (Default: "month 1 0:00")
2334 Address address
2336 The address of this server, or a fully qualified domain name of
2337 this server that resolves to an address. You can leave this unset,
2338 and Tor will try to guess your address. If a domain name is
2339 provided, Tor will attempt to resolve it and use the underlying
2340 IPv4/IPv6 address as its publish address (taking precedence over
2341 the ORPort configuration). The publish address is the one used to
2342 tell clients and other servers where to find your Tor server; it
2343 doesn’t affect the address that your server binds to. To bind to a
2344 different address, use the ORPort and OutboundBindAddress options.
2345 AddressDisableIPv6 0|1
2347 By default, Tor will attempt to find the IPv6 of the relay if there
2348 is no IPv4Only ORPort. If set, this option disables IPv6 auto
2349 discovery. This disables IPv6 address resolution, IPv6 ORPorts, and
2350 IPv6 reachability checks. Also, the relay won’t publish an IPv6
2351 ORPort in its descriptor. (Default: 0)
2352 AssumeReachable 0|1
2354 This option is used when bootstrapping a new Tor network. If set to
2355 1, don’t do self-reachability testing; just upload your server
2356 descriptor immediately. (Default: 0)
2357 AssumeReachableIPv6 0|1|auto
2359 Like AssumeReachable, but affects only the relay’s own IPv6 ORPort.
2360 If this value is set to "auto", then Tor will look at
2361 AssumeReachable instead. (Default: auto)
2362 BridgeRelay 0|1
2364 Sets the relay to act as a "bridge" with respect to relaying
2365 connections from bridge users to the Tor network. It mainly causes
2366 Tor to publish a server descriptor to the bridge database, rather
2367 than to the public directory authorities.
2368 Note: make sure that no MyFamily lines are present in your torrc
2371 when relay is configured in bridge mode.
2372 BridgeDistribution string
2374 If set along with BridgeRelay, Tor will include a new line in its
2375 bridge descriptor which indicates to the BridgeDB service how it
2376 would like its bridge address to be given out. Set it to "none" if
2377 you want BridgeDB to avoid distributing your bridge address, or
2378 "any" to let BridgeDB decide. See
2379 https://bridges.torproject.org/info for a more up-to-date list of
2380 options. (Default: any)
2381 ContactInfo email_address
2383 Administrative contact information for this relay or bridge. This
2384 line can be used to contact you if your relay or bridge is
2385 misconfigured or something else goes wrong. Note that we archive
2386 and publish all descriptors containing these lines and that Google
2387 indexes them, so spammers might also collect them. You may want to
2388 obscure the fact that it’s an email address and/or generate a new
2389 address for this purpose.
2390 ContactInfo must be set to a working address if you run more than
2393 one relay or bridge. (Really, everybody running a relay or bridge
2394 should set it.)
2395 DisableOOSCheck 0|1
2397 This option disables the code that closes connections when Tor
2398 notices that it is running low on sockets. Right now, it is on by
2399 default, since the existing out-of-sockets mechanism tends to kill
2400 OR connections more than it should. (Default: 1)
2401 ExitPolicy policy,policy,...
2403 Set an exit policy for this server. Each policy is of the form
2404 "accept[6]|reject[6] ADDR[/MASK][:PORT]". If /MASK is omitted then
2405 this policy just applies to the host given. Instead of giving a
2406 host or network you can also use "*" to denote the universe
2407 (0.0.0.0/0 and ::/0), or *4 to denote all IPv4 addresses, and *6 to
2408 denote all IPv6 addresses. PORT can be a single port number, an
2409 interval of ports "FROM_PORT-TO_PORT", or "*". If PORT is omitted,
2410 that means "*".
2411 For example, "accept 18.7.22.69:*,reject 18.0.0.0/8:*,accept *:*"
2414 would reject any IPv4 traffic destined for MIT except for
2415 web.mit.edu, and accept any other IPv4 or IPv6 traffic.
2416 Tor also allows IPv6 exit policy entries. For instance, "reject6
2419 [FC00::]/7:*" rejects all destinations that share 7 most
2420 significant bit prefix with address FC00::. Respectively, "accept6
2421 [C000::]/3:*" accepts all destinations that share 3 most
2422 significant bit prefix with address C000::.
2423 accept6 and reject6 only produce IPv6 exit policy entries. Using an
2426 IPv4 address with accept6 or reject6 is ignored and generates a
2427 warning. accept/reject allows either IPv4 or IPv6 addresses. Use *4
2428 as an IPv4 wildcard address, and *6 as an IPv6 wildcard address.
2429 accept/reject * expands to matching IPv4 and IPv6 wildcard address
2430 rules.
2431 To specify all IPv4 and IPv6 internal and link-local networks
2434 (including 0.0.0.0/8, 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16,
2435 10.0.0.0/8, 172.16.0.0/12, [::]/8, [FC00::]/7, [FE80::]/10,
2436 [FEC0::]/10, [FF00::]/8, and [::]/127), you can use the "private"
2437 alias instead of an address. ("private" always produces rules for
2438 IPv4 and IPv6 addresses, even when used with accept6/reject6.)
2439 Private addresses are rejected by default (at the beginning of your
2442 exit policy), along with any configured primary public IPv4 and
2443 IPv6 addresses. These private addresses are rejected unless you set
2444 the ExitPolicyRejectPrivate config option to 0. For example, once
2445 you’ve done that, you could allow HTTP to 127.0.0.1 and block all
2446 other connections to internal networks with "accept
2447 127.0.0.1:80,reject private:*", though that may also allow
2448 connections to your own computer that are addressed to its public
2449 (external) IP address. See RFC 1918 and RFC 3330 for more details
2450 about internal and reserved IP address space. See
2451 ExitPolicyRejectLocalInterfaces if you want to block every address
2452 on the relay, even those that aren’t advertised in the descriptor.
2453 This directive can be specified multiple times so you don’t have to
2456 put it all on one line.
2457 Policies are considered first to last, and the first match wins. If
2460 you want to allow the same ports on IPv4 and IPv6, write your rules
2461 using accept/reject *. If you want to allow different ports on IPv4
2462 and IPv6, write your IPv6 rules using accept6/reject6 *6, and your
2463 IPv4 rules using accept/reject *4. If you want to _replace_ the
2464 default exit policy, end your exit policy with either a reject *:*
2465 or an accept *:*. Otherwise, you’re _augmenting_ (prepending to)
2466 the default exit policy.
2467 If you want to use a reduced exit policy rather than the default
2470 exit policy, set "ReducedExitPolicy 1". If you want to replace the
2471 default exit policy with your custom exit policy, end your exit
2472 policy with either a reject : or an accept :. Otherwise, you’re
2473 augmenting (prepending to) the default or reduced exit policy.
2474 The default exit policy is:
2477 reject *:25
2479 reject *:119
2480 reject *:135-139
2481 reject *:445
2482 reject *:563
2483 reject *:1214
2484 reject *:4661-4666
2485 reject *:6346-6429
2486 reject *:6699
2487 reject *:6881-6999
2488 accept *:*
2489 Since the default exit policy uses accept/reject *, it applies to
2491 both IPv4 and IPv6 addresses.
2492 ExitPolicyRejectLocalInterfaces 0|1
2494 Reject all IPv4 and IPv6 addresses that the relay knows about, at
2495 the beginning of your exit policy. This includes any
2496 OutboundBindAddress, the bind addresses of any port options, such
2497 as ControlPort or DNSPort, and any public IPv4 and IPv6 addresses
2498 on any interface on the relay. (If IPv6Exit is not set, all IPv6
2499 addresses will be rejected anyway.) See above entry on ExitPolicy.
2500 This option is off by default, because it lists all public relay IP
2501 addresses in the ExitPolicy, even those relay operators might
2502 prefer not to disclose. (Default: 0)
2503 ExitPolicyRejectPrivate 0|1
2505 Reject all private (local) networks, along with the relay’s
2506 advertised public IPv4 and IPv6 addresses, at the beginning of your
2507 exit policy. See above entry on ExitPolicy. (Default: 1)
2508 ExitRelay 0|1|auto
2510 Tells Tor whether to run as an exit relay. If Tor is running as a
2511 non-bridge server, and ExitRelay is set to 1, then Tor allows
2512 traffic to exit according to the ExitPolicy option, the
2513 ReducedExitPolicy option, or the default ExitPolicy (if no other
2514 exit policy option is specified).
2515 If ExitRelay is set to 0, no traffic is allowed to exit, and the
2518 ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored.
2519 If ExitRelay is set to "auto", then Tor checks the ExitPolicy,
2522 ReducedExitPolicy, and IPv6Exit options. If at least one of these
2523 options is set, Tor behaves as if ExitRelay were set to 1. If none
2524 of these exit policy options are set, Tor behaves as if ExitRelay
2525 were set to 0. (Default: auto)
2526 ExtendAllowPrivateAddresses 0|1
2528 When this option is enabled, Tor will connect to relays on
2529 localhost, RFC1918 addresses, and so on. In particular, Tor will
2530 make direct OR connections, and Tor routers allow EXTEND requests,
2531 to these private addresses. (Tor will always allow connections to
2532 bridges, proxies, and pluggable transports configured on private
2533 addresses.) Enabling this option can create security issues; you
2534 should probably leave it off. (Default: 0)
2535 GeoIPFile filename
2537 A filename containing IPv4 GeoIP data, for use with by-country
2538 statistics.
2539 GeoIPv6File filename
2541 A filename containing IPv6 GeoIP data, for use with by-country
2542 statistics.
2543 HeartbeatPeriod N minutes|hours|days|weeks
2545 Log a heartbeat message every HeartbeatPeriod seconds. This is a
2546 log level notice message, designed to let you know your Tor server
2547 is still alive and doing useful things. Settings this to 0 will
2548 disable the heartbeat. Otherwise, it must be at least 30 minutes.
2549 (Default: 6 hours)
2550 IPv6Exit 0|1
2552 If set, and we are an exit node, allow clients to use us for IPv6
2553 traffic. When this option is set and ExitRelay is auto, we act as
2554 if ExitRelay is 1. (Default: 0)
2555 KeyDirectory DIR
2557 Store secret keys in DIR. Can not be changed while tor is running.
2558 (Default: the "keys" subdirectory of DataDirectory.)
2559 KeyDirectoryGroupReadable 0|1|auto
2561 If this option is set to 0, don’t allow the filesystem group to
2562 read the KeyDirectory. If the option is set to 1, make the
2563 KeyDirectory readable by the default GID. If the option is "auto",
2564 then we use the setting for DataDirectoryGroupReadable when the
2565 KeyDirectory is the same as the DataDirectory, and 0 otherwise.
2566 (Default: auto)
2567 MainloopStats 0|1
2569 Log main loop statistics every HeartbeatPeriod seconds. This is a
2570 log level notice message designed to help developers instrumenting
2571 Tor’s main event loop. (Default: 0)
2572 MaxMemInQueues N bytes|KBytes|MBytes|GBytes
2574 This option configures a threshold above which Tor will assume that
2575 it needs to stop queueing or buffering data because it’s about to
2576 run out of memory. If it hits this threshold, it will begin killing
2577 circuits until it has recovered at least 10% of this memory. Do not
2578 set this option too low, or your relay may be unreliable under
2579 load. This option only affects some queues, so the actual process
2580 size will be larger than this. If this option is set to 0, Tor will
2581 try to pick a reasonable default based on your system’s physical
2582 memory. (Default: 0)
2583 MaxOnionQueueDelay NUM [msec|second]
2585 If we have more onionskins queued for processing than we can
2586 process in this amount of time, reject new ones. (Default: 1750
2587 msec)
2588 MyFamily fingerprint,fingerprint,...
2590 Declare that this Tor relay is controlled or administered by a
2591 group or organization identical or similar to that of the other
2592 relays, defined by their (possibly $-prefixed) identity
2593 fingerprints. This option can be repeated many times, for
2594 convenience in defining large families: all fingerprints in all
2595 MyFamily lines are merged into one list. When two relays both
2596 declare that they are in the same 'family', Tor clients will not
2597 use them in the same circuit. (Each relay only needs to list the
2598 other servers in its family; it doesn’t need to list itself, but it
2599 won’t hurt if it does.) Do not list any bridge relay as it would
2600 compromise its concealment.
2601 If you run more than one relay, the MyFamily option on each relay
2604 must list all other relays, as described above.
2605 Note: do not use MyFamily when configuring your Tor instance as a
2608 bridge.
2609 Nickname name
2611 Set the server’s nickname to 'name'. Nicknames must be between 1
2612 and 19 characters inclusive, and must contain only the characters
2613 [a-zA-Z0-9]. If not set, Unnamed will be used. Relays can always be
2614 uniquely identified by their identity fingerprints.
2615 NumCPUs num
2617 How many processes to use at once for decrypting onionskins and
2618 other parallelizable operations. If this is set to 0, Tor will try
2619 to detect how many CPUs you have, defaulting to 1 if it can’t tell.
2620 (Default: 0)
2621 OfflineMasterKey 0|1
2623 If non-zero, the Tor relay will never generate or load its master
2624 secret key. Instead, you’ll have to use "tor --keygen" to manage
2625 the permanent ed25519 master identity key, as well as the
2626 corresponding temporary signing keys and certificates. (Default: 0)
2627 ORPort [address:]PORT|auto [flags]
2629 Advertise this port to listen for connections from Tor clients and
2630 servers. This option is required to be a Tor server. Set it to
2631 "auto" to have Tor pick a port for you. Set it to 0 to not run an
2632 ORPort at all. This option can occur more than once. (Default: 0)
2633 Tor recognizes these flags on each ORPort:
2636 NoAdvertise
2638 By default, we bind to a port and tell our users about it. If
2639 NoAdvertise is specified, we don’t advertise, but listen
2640 anyway. This can be useful if the port everybody will be
2641 connecting to (for example, one that’s opened on our firewall)
2642 is somewhere else.
2643 NoListen
2645 By default, we bind to a port and tell our users about it. If
2646 NoListen is specified, we don’t bind, but advertise anyway.
2647 This can be useful if something else (for example, a firewall’s
2648 port forwarding configuration) is causing connections to reach
2649 us.
2650 IPv4Only
2652 If the address is absent, or resolves to both an IPv4 and an
2653 IPv6 address, only listen to the IPv4 address.
2654 IPv6Only
2656 If the address is absent, or resolves to both an IPv4 and an
2657 IPv6 address, only listen to the IPv6 address.
2658 For obvious reasons, NoAdvertise and NoListen are mutually
2660 exclusive, and IPv4Only and IPv6Only are mutually exclusive.
2661 PublishServerDescriptor 0|1|v3|bridge,...
2663 This option specifies which descriptors Tor will publish when
2664 acting as a relay. You can choose multiple arguments, separated by
2665 commas.
2666 If this option is set to 0, Tor will not publish its descriptors to
2669 any directories. (This is useful if you’re testing out your server,
2670 or if you’re using a Tor controller that handles directory
2671 publishing for you.) Otherwise, Tor will publish its descriptors of
2672 all type(s) specified. The default is "1", which means "if running
2673 as a relay or bridge, publish descriptors to the appropriate
2674 authorities". Other possibilities are "v3", meaning "publish as if
2675 you’re a relay", and "bridge", meaning "publish as if you’re a
2676 bridge".
2677 ReducedExitPolicy 0|1
2679 If set, use a reduced exit policy rather than the default one.
2680 The reduced exit policy is an alternative to the default exit
2683 policy. It allows as many Internet services as possible while still
2684 blocking the majority of TCP ports. Currently, the policy allows
2685 approximately 65 ports. This reduces the odds that your node will
2686 be used for peer-to-peer applications.
2687 The reduced exit policy is:
2690 accept *:20-21
2692 accept *:22
2693 accept *:23
2694 accept *:43
2695 accept *:53
2696 accept *:79
2697 accept *:80-81
2698 accept *:88
2699 accept *:110
2700 accept *:143
2701 accept *:194
2702 accept *:220
2703 accept *:389
2704 accept *:443
2705 accept *:464
2706 accept *:465
2707 accept *:531
2708 accept *:543-544
2709 accept *:554
2710 accept *:563
2711 accept *:587
2712 accept *:636
2713 accept *:706
2714 accept *:749
2715 accept *:873
2716 accept *:902-904
2717 accept *:981
2718 accept *:989-990
2719 accept *:991
2720 accept *:992
2721 accept *:993
2722 accept *:994
2723 accept *:995
2724 accept *:1194
2725 accept *:1220
2726 accept *:1293
2727 accept *:1500
2728 accept *:1533
2729 accept *:1677
2730 accept *:1723
2731 accept *:1755
2732 accept *:1863
2733 accept *:2082
2734 accept *:2083
2735 accept *:2086-2087
2736 accept *:2095-2096
2737 accept *:2102-2104
2738 accept *:3128
2739 accept *:3389
2740 accept *:3690
2741 accept *:4321
2742 accept *:4643
2743 accept *:5050
2744 accept *:5190
2745 accept *:5222-5223
2746 accept *:5228
2747 accept *:5900
2748 accept *:6660-6669
2749 accept *:6679
2750 accept *:6697
2751 accept *:8000
2752 accept *:8008
2753 accept *:8074
2754 accept *:8080
2755 accept *:8082
2756 accept *:8087-8088
2757 accept *:8232-8233
2758 accept *:8332-8333
2759 accept *:8443
2760 accept *:8888
2761 accept *:9418
2762 accept *:9999
2763 accept *:10000
2764 accept *:11371
2765 accept *:19294
2766 accept *:19638
2767 accept *:50002
2768 accept *:64738
2769 reject *:*
2770 (Default: 0)
2772 RefuseUnknownExits 0|1|auto
2774 Prevent nodes that don’t appear in the consensus from exiting using
2775 this relay. If the option is 1, we always block exit attempts from
2776 such nodes; if it’s 0, we never do, and if the option is "auto",
2777 then we do whatever the authorities suggest in the consensus (and
2778 block if the consensus is quiet on the issue). (Default: auto)
2779 ServerDNSAllowBrokenConfig 0|1
2781 If this option is false, Tor exits immediately if there are
2782 problems parsing the system DNS configuration or connecting to
2783 nameservers. Otherwise, Tor continues to periodically retry the
2784 system nameservers until it eventually succeeds. (Default: 1)
2785 ServerDNSAllowNonRFC953Hostnames 0|1
2787 When this option is disabled, Tor does not try to resolve hostnames
2788 containing illegal characters (like @ and :) rather than sending
2789 them to an exit node to be resolved. This helps trap accidental
2790 attempts to resolve URLs and so on. This option only affects name
2791 lookups that your server does on behalf of clients. (Default: 0)
2792 ServerDNSDetectHijacking 0|1
2794 When this option is set to 1, we will test periodically to
2795 determine whether our local nameservers have been configured to
2796 hijack failing DNS requests (usually to an advertising site). If
2797 they are, we will attempt to correct this. This option only affects
2798 name lookups that your server does on behalf of clients. (Default:
2799 1)
2800 ServerDNSRandomizeCase 0|1
2802 When this option is set, Tor sets the case of each character
2803 randomly in outgoing DNS requests, and makes sure that the case
2804 matches in DNS replies. This so-called "0x20 hack" helps resist
2805 some types of DNS poisoning attack. For more information, see
2806 "Increased DNS Forgery Resistance through 0x20-Bit Encoding". This
2807 option only affects name lookups that your server does on behalf of
2808 clients. (Default: 1)
2809 ServerDNSResolvConfFile filename
2811 Overrides the default DNS configuration with the configuration in
2812 filename. The file format is the same as the standard Unix
2813 "resolv.conf" file (7). This option, like all other ServerDNS
2814 options, only affects name lookups that your server does on behalf
2815 of clients. (Defaults to use the system DNS configuration or a
2816 localhost DNS service in case no nameservers are found in a given
2817 configuration.)
2818 ServerDNSSearchDomains 0|1
2820 If set to 1, then we will search for addresses in the local search
2821 domain. For example, if this system is configured to believe it is
2822 in "example.com", and a client tries to connect to "www", the
2823 client will be connected to "www.example.com". This option only
2824 affects name lookups that your server does on behalf of clients.
2825 (Default: 0)
2826 ServerDNSTestAddresses hostname,hostname,...
2828 When we’re detecting DNS hijacking, make sure that these valid
2829 addresses aren’t getting redirected. If they are, then our DNS is
2830 completely useless, and we’ll reset our exit policy to "reject
2831 *:*". This option only affects name lookups that your server does
2832 on behalf of clients. (Default: "www.google.com, www.mit.edu,
2833 www.yahoo.com, www.slashdot.org")
2834 ServerTransportListenAddr transport IP:PORT
2836 When this option is set, Tor will suggest IP:PORT as the listening
2837 address of any pluggable transport proxy that tries to launch
2838 transport. (IPv4 addresses should written as-is; IPv6 addresses
2839 should be wrapped in square brackets.) (Default: none)
2840 ServerTransportOptions transport k=v k=v ...
2842 When this option is set, Tor will pass the k=v parameters to any
2843 pluggable transport proxy that tries to launch transport.
2844 (Example: ServerTransportOptions obfs45 shared-secret=bridgepasswd
2846 cache=/var/lib/tor/cache) (Default: none)
2847 ServerTransportPlugin transport exec path-to-binary [options]
2849 The Tor relay launches the pluggable transport proxy in
2850 path-to-binary using options as its command-line options, and
2851 expects to receive proxied client traffic from it. (Default: none)
2852 ShutdownWaitLength NUM
2854 When we get a SIGINT and we’re a server, we begin shutting down: we
2855 close listeners and start refusing new circuits. After NUM seconds,
2856 we exit. If we get a second SIGINT, we exit immediately. (Default:
2857 30 seconds)
2858 SigningKeyLifetime N days|weeks|months
2860 For how long should each Ed25519 signing key be valid? Tor uses a
2861 permanent master identity key that can be kept offline, and
2862 periodically generates new "signing" keys that it uses online. This
2863 option configures their lifetime. (Default: 30 days)
2864 SSLKeyLifetime N minutes|hours|days|weeks
2866 When creating a link certificate for our outermost SSL handshake,
2867 set its lifetime to this amount of time. If set to 0, Tor will
2868 choose some reasonable random defaults. (Default: 0)
2869
2871 Relays publish most statistics in a document called the extra-info
2872 document. The following options affect the different types of
2873 statistics that Tor relays collect and publish:
2874 BridgeRecordUsageByCountry 0|1
2876 When this option is enabled and BridgeRelay is also enabled, and we
2877 have GeoIP data, Tor keeps a per-country count of how many client
2878 addresses have contacted it so that it can help the bridge
2879 authority guess which countries have blocked access to it. If
2880 ExtraInfoStatistics is enabled, it will be published as part of the
2881 extra-info document. (Default: 1)
2882 CellStatistics 0|1
2884 Relays only. When this option is enabled, Tor collects statistics
2885 about cell processing (i.e. mean time a cell is spending in a
2886 queue, mean number of cells in a queue and mean number of processed
2887 cells per circuit) and writes them into disk every 24 hours. Onion
2888 router operators may use the statistics for performance monitoring.
2889 If ExtraInfoStatistics is enabled, it will published as part of the
2890 extra-info document. (Default: 0)
2891 ConnDirectionStatistics 0|1
2893 Relays only. When this option is enabled, Tor writes statistics on
2894 the amounts of traffic it passes between itself and other relays to
2895 disk every 24 hours. Enables relay operators to monitor how much
2896 their relay is being used as middle node in the circuit. If
2897 ExtraInfoStatistics is enabled, it will be published as part of the
2898 extra-info document. (Default: 0)
2899 DirReqStatistics 0|1
2901 Relays and bridges only. When this option is enabled, a Tor
2902 directory writes statistics on the number and response time of
2903 network status requests to disk every 24 hours. Enables relay and
2904 bridge operators to monitor how much their server is being used by
2905 clients to learn about Tor network. If ExtraInfoStatistics is
2906 enabled, it will published as part of the extra-info document.
2907 (Default: 1)
2908 EntryStatistics 0|1
2910 Relays only. When this option is enabled, Tor writes statistics on
2911 the number of directly connecting clients to disk every 24 hours.
2912 Enables relay operators to monitor how much inbound traffic that
2913 originates from Tor clients passes through their server to go
2914 further down the Tor network. If ExtraInfoStatistics is enabled, it
2915 will be published as part of the extra-info document. (Default: 0)
2916 ExitPortStatistics 0|1
2918 Exit relays only. When this option is enabled, Tor writes
2919 statistics on the number of relayed bytes and opened stream per
2920 exit port to disk every 24 hours. Enables exit relay operators to
2921 measure and monitor amounts of traffic that leaves Tor network
2922 through their exit node. If ExtraInfoStatistics is enabled, it will
2923 be published as part of the extra-info document. (Default: 0)
2924 ExtraInfoStatistics 0|1
2926 When this option is enabled, Tor includes previously gathered
2927 statistics in its extra-info documents that it uploads to the
2928 directory authorities. Disabling this option also removes bandwidth
2929 usage statistics, and GeoIPFile and GeoIPv6File hashes from the
2930 extra-info file. Bridge ServerTransportPlugin lines are always
2931 included in the extra-info file, because they are required by
2932 BridgeDB. (Default: 1)
2933 HiddenServiceStatistics 0|1
2935 Relays and bridges only. When this option is enabled, a Tor relay
2936 writes obfuscated statistics on its role as hidden-service
2937 directory, introduction point, or rendezvous point to disk every 24
2938 hours. If ExtraInfoStatistics is enabled, it will be published as
2939 part of the extra-info document. (Default: 1)
2940 OverloadStatistics 0|1*
2942 Relays and bridges only. When this option is enabled, a Tor relay
2943 will write an overload general line in the server descriptor if the
2944 relay is considered overloaded. (Default: 1)
2945 A relay is considered overloaded if at least one of these
2947 conditions is met:
2948 • Onionskins are starting to be dropped.
2950 • The OOM was invoked.
2952 • (Exit only) DNS timeout occurs X% of the time over Y seconds
2954 (values controlled by consensus parameters, see
2955 param-spec.txt).
2956 If ExtraInfoStatistics is enabled, it can also put two more
2958 specific overload lines in the extra-info document if at least
2959 one of these conditions is met:
2960 • TCP Port exhaustion.
2962 • Connection rate limits have been reached (read and write side).
2964 PaddingStatistics 0|1
2966 Relays and bridges only. When this option is enabled, Tor collects
2967 statistics for padding cells sent and received by this relay, in
2968 addition to total cell counts. These statistics are rounded, and
2969 omitted if traffic is low. This information is important for load
2970 balancing decisions related to padding. If ExtraInfoStatistics is
2971 enabled, it will be published as a part of the extra-info document.
2972 (Default: 1)
2973
2975 The following options are useful only for directory servers. (Relays
2976 with enough bandwidth automatically become directory servers; see
2977 DirCache for details.)
2978 DirCache 0|1
2980 When this option is set, Tor caches all current directory documents
2981 except extra info documents, and accepts client requests for them.
2982 If DownloadExtraInfo is set, cached extra info documents are also
2983 cached. Setting DirPort is not required for DirCache, because
2984 clients connect via the ORPort by default. Setting either DirPort
2985 or BridgeRelay and setting DirCache to 0 is not supported.
2986 (Default: 1)
2987 DirPolicy policy,policy,...
2989 Set an entrance policy for this server, to limit who can connect to
2990 the directory ports. The policies have the same form as exit
2991 policies above, except that port specifiers are ignored. Any
2992 address not matched by some entry in the policy is accepted.
2993 DirPort [address:]PORT|auto [flags]
2995 If this option is nonzero, advertise the directory service on this
2996 port. Set it to "auto" to have Tor pick a port for you. This option
2997 can occur more than once, but only one advertised DirPort is
2998 supported: all but one DirPort must have the NoAdvertise flag set.
2999 (Default: 0)
3000 The same flags are supported here as are supported by ORPort. This
3003 port can only be IPv4.
3004 As of Tor 0.4.6.1-alpha, non-authoritative relays (see
3006 AuthoritativeDirectory) will not publish the DirPort but will still
3007 listen on it. Clients don’t use the DirPorts on relays, so it is
3008 safe for you to remove the DirPort from your torrc configuration.
3009 DirPortFrontPage FILENAME
3011 When this option is set, it takes an HTML file and publishes it as
3012 "/" on the DirPort. Now relay operators can provide a disclaimer
3013 without needing to set up a separate webserver. There’s a sample
3014 disclaimer in contrib/operator-tools/tor-exit-notice.html.
3015 MaxConsensusAgeForDiffs N minutes|hours|days|weeks
3017 When this option is nonzero, Tor caches will not try to generate
3018 consensus diffs for any consensus older than this amount of time.
3019 If this option is set to zero, Tor will pick a reasonable default
3020 from the current networkstatus document. You should not set this
3021 option unless your cache is severely low on disk space or CPU. If
3022 you need to set it, keeping it above 3 or 4 hours will help clients
3023 much more than setting it to zero. (Default: 0)
3024
3026 Tor has a series of built-in denial of service mitigation options that
3027 can be individually enabled/disabled and fine-tuned, but by default Tor
3028 directory authorities will define reasonable values for the network and
3029 no explicit configuration is required to make use of these protections.
3030 The following is a series of configuration options for relays and then
3032 options for onion services and how they work.
3033 The mitigations take place at relays, and are as follows:
3035 1. If a single client address makes too many concurrent connections
3037 (this is configurable via DoSConnectionMaxConcurrentCount), hang up
3038 on further connections.
3039 2. If a single client IP address (v4 or v6) makes circuits too quickly
3041 (default values are more than 3 per second, with an allowed burst
3042 of 90, see DoSCircuitCreationRate and DoSCircuitCreationBurst)
3043 while also having too many connections open (default is 3, see
3044 DoSCircuitCreationMinConnections), tor will refuse any new circuit
3045 (CREATE cells) for the next while (random value between 1 and 2
3046 hours).
3047 3. If a client asks to establish a rendezvous point to you directly
3049 (ex: Tor2Web client), ignore the request.
3050 These defenses can be manually controlled by torrc options, but relays
3052 will also take guidance from consensus parameters using these same
3053 names, so there’s no need to configure anything manually. In doubt, do
3054 not change those values.
3055 The values set by the consensus, if any, can be found here:
3057 https://consensus-health.torproject.org/#consensusparams
3058 If any of the DoS mitigations are enabled, a heartbeat message will
3060 appear in your log at NOTICE level which looks like:
3061 DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses.
3063 2238 connections closed. 8052 single hop clients refused.
3064 The following options are useful only for a public relay. They control
3066 the Denial of Service mitigation subsystem described above.
3067 DoSCircuitCreationEnabled 0|1|auto
3069 Enable circuit creation DoS mitigation. If set to 1 (enabled), tor
3070 will cache client IPs along with statistics in order to detect
3071 circuit DoS attacks. If an address is positively identified, tor
3072 will activate defenses against the address. See
3073 DoSCircuitCreationDefenseType option for more details. This is a
3074 client to relay detection only. "auto" means use the consensus
3075 parameter. If not defined in the consensus, the value is 0.
3076 (Default: auto)
3077 DoSCircuitCreationBurst NUM
3079 The allowed circuit creation burst per client IP address. If the
3080 circuit rate and the burst are reached, a client is marked as
3081 executing a circuit creation DoS. "0" means use the consensus
3082 parameter. If not defined in the consensus, the value is 90.
3083 (Default: 0)
3084 DoSCircuitCreationDefenseTimePeriod N seconds|minutes|hours
3086 The base time period in seconds that the DoS defense is activated
3087 for. The actual value is selected randomly for each activation from
3088 N+1 to 3/2 * N. "0" means use the consensus parameter. If not
3089 defined in the consensus, the value is 3600 seconds (1 hour).
3090 (Default: 0)
3091 DoSCircuitCreationDefenseType NUM
3093 This is the type of defense applied to a detected client address.
3094 The possible values are:
3095 1: No defense.
3097 2: Refuse circuit creation for the
3099 DoSCircuitCreationDefenseTimePeriod period of time.
3100 "0" means use the consensus parameter. If not defined in the
3102 consensus, the value is 2. (Default: 0)
3103 DoSCircuitCreationMinConnections NUM
3105 Minimum threshold of concurrent connections before a client address
3106 can be flagged as executing a circuit creation DoS. In other words,
3107 once a client address reaches the circuit rate and has a minimum of
3108 NUM concurrent connections, a detection is positive. "0" means use
3109 the consensus parameter. If not defined in the consensus, the value
3110 is 3. (Default: 0)
3111 DoSCircuitCreationRate NUM
3113 The allowed circuit creation rate per second applied per client IP
3114 address. If this option is 0, it obeys a consensus parameter. If
3115 not defined in the consensus, the value is 3. (Default: 0)
3116 DoSConnectionEnabled 0|1|auto
3118 Enable the connection DoS mitigation. If set to 1 (enabled), for
3119 client address only, this allows tor to mitigate against large
3120 number of concurrent connections made by a single IP address.
3121 "auto" means use the consensus parameter. If not defined in the
3122 consensus, the value is 0. (Default: auto)
3123 DoSConnectionDefenseType NUM
3125 This is the type of defense applied to a detected client address
3126 for the connection mitigation. The possible values are:
3127 1: No defense.
3129 2: Immediately close new connections.
3131 "0" means use the consensus parameter. If not defined in the
3133 consensus, the value is 2. (Default: 0)
3134 DoSConnectionMaxConcurrentCount NUM
3136 The maximum threshold of concurrent connection from a client IP
3137 address. Above this limit, a defense selected by
3138 DoSConnectionDefenseType is applied. "0" means use the consensus
3139 parameter. If not defined in the consensus, the value is 100.
3140 (Default: 0)
3141 DoSConnectionConnectRate NUM
3143 The allowed rate of client connection from a single address per
3144 second. Coupled with the burst (see below), if the limit is
3145 reached, the address is marked and a defense is applied
3146 (DoSConnectionDefenseType) for a period of time defined by
3147 DoSConnectionConnectDefenseTimePeriod. If not defined or set to 0,
3148 it is controlled by a consensus parameter. (Default: 0)
3149 DoSConnectionConnectBurst NUM
3151 The allowed burst of client connection from a single address per
3152 second. See the DoSConnectionConnectRate for more details on this
3153 detection. If not defined or set to 0, it is controlled by a
3154 consensus parameter. (Default: 0)
3155 DoSConnectionConnectDefenseTimePeriod N seconds|minutes|hours
3157 The base time period in seconds that the client connection defense
3158 is activated for. The actual value is selected randomly for each
3159 activation from N+1 to 3/2 * N. If not defined or set to 0, it is
3160 controlled by a consensus parameter. (Default: 24 hours)
3161 DoSRefuseSingleHopClientRendezvous 0|1|auto
3163 Refuse establishment of rendezvous points for single hop clients.
3164 In other words, if a client directly connects to the relay and
3165 sends an ESTABLISH_RENDEZVOUS cell, it is silently dropped. "auto"
3166 means use the consensus parameter. If not defined in the consensus,
3167 the value is 0. (Default: auto)
3168 As for onion services, only one possible mitigation exists. It was
3170 intended to protect the network first and thus do not help the service
3171 availability or reachability.
3172 The mitigation we put in place is a rate limit of the amount of
3174 introduction that happens at the introduction point for a service. In
3175 other words, it rates limit the number of clients that are attempting
3176 to reach the service at the introduction point instead of at the
3177 service itself.
3178 The following options are per onion service:
3180 HiddenServiceEnableIntroDoSDefense 0|1
3182 Enable DoS defense at the intropoint level. When this is enabled,
3183 the rate and burst parameter (see below) will be sent to the intro
3184 point which will then use them to apply rate limiting for
3185 introduction request to this service.
3186 The introduction point honors the consensus parameters except if
3188 this is specifically set by the service operator using this option.
3189 The service never looks at the consensus parameters in order to
3190 enable or disable this defense. (Default: 0)
3191 HiddenServiceEnableIntroDoSBurstPerSec NUM
3193 The allowed client introduction burst per second at the
3194 introduction point. If this option is 0, it is considered infinite
3195 and thus if HiddenServiceEnableIntroDoSDefense is set, it then
3196 effectively disables the defenses. (Default: 200)
3197 HiddenServiceEnableIntroDoSRatePerSec NUM
3199 The allowed client introduction rate per second at the introduction
3200 point. If this option is 0, it is considered infinite and thus if
3201 HiddenServiceEnableIntroDoSDefense is set, it then effectively
3202 disables the defenses. (Default: 25)
3203 The rate is the maximum number of clients a service will ask its
3205 introduction points to allow every seconds. And the burst is a
3206 parameter that allows that many within one second.
3207 For example, the default values of 25 and 200 respectively means that
3209 for every introduction points a service has (default 3 but can be
3210 configured with HiddenServiceNumIntroductionPoints), 25 clients per
3211 seconds will be allowed to reach the service and 200 at most within 1
3212 second as a burst. This means that if 200 clients are seen within 1
3213 second, it will take 8 seconds (200/25) for another client to be able
3214 to be allowed to introduce due to the rate of 25 per second.
3215 This might be too much for your use case or not, fine tuning these
3217 values is hard and are likely different for each service operator.
3218 Why is this not helping reachability of the service? Because the
3220 defenses are at the introduction point, an attacker can easily flood
3221 all introduction point rendering the service unavailable due to no
3222 client being able to pass through. But, the service itself is not
3223 overwhelmed with connetions allowing it to function properly for the
3224 few clients that were able to go through or other any services running
3225 on the same tor instance.
3226 The bottom line is that this protects the network by preventing an
3228 onion service to flood the network with new rendezvous circuits that is
3229 reducing load on the network.
3230
3232 The following options enable operation as a directory authority, and
3233 control how Tor behaves as a directory authority. You should not need
3234 to adjust any of them if you’re running a regular relay or exit server
3235 on the public Tor network.
3236 AuthoritativeDirectory 0|1
3238 When this option is set to 1, Tor operates as an authoritative
3239 directory server. Instead of caching the directory, it generates
3240 its own list of good servers, signs it, and sends that to the
3241 clients. Unless the clients already have you listed as a trusted
3242 directory, you probably do not want to set this option.
3243 BridgeAuthoritativeDir 0|1
3245 When this option is set in addition to AuthoritativeDirectory, Tor
3246 accepts and serves server descriptors, but it caches and serves the
3247 main networkstatus documents rather than generating its own.
3248 (Default: 0)
3249 V3AuthoritativeDirectory 0|1
3251 When this option is set in addition to AuthoritativeDirectory, Tor
3252 generates version 3 network statuses and serves descriptors, etc as
3253 described in dir-spec.txt file of torspec (for Tor clients and
3254 servers running at least 0.2.0.x).
3255 AuthDirBadExit AddressPattern...
3257 Authoritative directories only. A set of address patterns for
3258 servers that will be listed as bad exits in any network status
3259 document this authority publishes, if AuthDirListBadExits is set.
3260 (The address pattern syntax here and in the options below is the
3263 same as for exit policies, except that you don’t need to say
3264 "accept" or "reject", and ports are not needed.)
3265 AuthDirMiddleOnly AddressPattern...
3267 Authoritative directories only. A set of address patterns for
3268 servers that will be listed as middle-only in any network status
3269 document this authority publishes, if AuthDirListMiddleOnly is set.
3270 AuthDirFastGuarantee N
3272 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3273 Authoritative directories only. If non-zero, always vote the Fast
3274 flag for any relay advertising this amount of capacity or more.
3275 (Default: 100 KBytes)
3276 AuthDirGuardBWGuarantee N
3278 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3279 Authoritative directories only. If non-zero, this advertised
3280 capacity or more is always sufficient to satisfy the bandwidth
3281 requirement for the Guard flag. (Default: 2 MBytes)
3282 AuthDirHasIPv6Connectivity 0|1
3284 Authoritative directories only. When set to 0, OR ports with an
3285 IPv6 address are not included in the authority’s votes. When set to
3286 1, IPv6 OR ports are tested for reachability like IPv4 OR ports. If
3287 the reachability test succeeds, the authority votes for the IPv6
3288 ORPort, and votes Running for the relay. If the reachability test
3289 fails, the authority does not vote for the IPv6 ORPort, and does
3290 not vote Running (Default: 0)
3291 The content of the consensus depends on the number of voting authorities
3294 that set AuthDirHasIPv6Connectivity:
3295 If no authorities set AuthDirHasIPv6Connectivity 1, there will be no
3297 IPv6 ORPorts in the consensus.
3298 If a minority of authorities set AuthDirHasIPv6Connectivity 1,
3300 unreachable IPv6 ORPorts will be removed from the consensus. But the
3301 majority of IPv4-only authorities will still vote the relay as Running.
3302 Reachable IPv6 ORPort lines will be included in the consensus
3303 If a majority of voting authorities set AuthDirHasIPv6Connectivity 1,
3305 relays with unreachable IPv6 ORPorts will not be listed as Running.
3306 Reachable IPv6 ORPort lines will be included in the consensus
3307 (To ensure that any valid majority will vote relays with unreachable
3308 IPv6 ORPorts not Running, 75% of authorities must set
3309 AuthDirHasIPv6Connectivity 1.)
3310 AuthDirInvalid AddressPattern...
3312 Authoritative directories only. A set of address patterns for
3313 servers that will never be listed as "valid" in any network status
3314 document that this authority publishes.
3315 AuthDirListBadExits 0|1
3317 Authoritative directories only. If set to 1, this directory has
3318 some opinion about which nodes are unsuitable as exit nodes. (Do
3319 not set this to 1 unless you plan to list non-functioning exits as
3320 bad; otherwise, you are effectively voting in favor of every
3321 declared exit as an exit.)
3322 AuthDirListMiddleOnly 0|1
3324 Authoritative directories only. If set to 1, this directory has
3325 some opinion about which nodes should only be used in the middle
3326 position. (Do not set this to 1 unless you plan to list
3327 questionable relays as "middle only"; otherwise, you are
3328 effectively voting against middle-only status for every relay.)
3329 AuthDirMaxServersPerAddr NUM
3331 Authoritative directories only. The maximum number of servers that
3332 we will list as acceptable on a single IP address. Set this to "0"
3333 for "no limit". (Default: 2)
3334 AuthDirPinKeys 0|1
3336 Authoritative directories only. If non-zero, do not allow any relay
3337 to publish a descriptor if any other relay has reserved its
3338 <Ed25519,RSA> identity keypair. In all cases, Tor records every
3339 keypair it accepts in a journal if it is new, or if it differs from
3340 the most recently accepted pinning for one of the keys it contains.
3341 (Default: 1)
3342 AuthDirReject AddressPattern...
3344 Authoritative directories only. A set of address patterns for
3345 servers that will never be listed at all in any network status
3346 document that this authority publishes, or accepted as an OR
3347 address in any descriptor submitted for publication by this
3348 authority.
3349 AuthDirRejectRequestsUnderLoad 0|1
3351 If set, the directory authority will start rejecting directory
3352 requests from non relay connections by sending a 503 error code if
3353 it is under bandwidth pressure (reaching the configured limit if
3354 any). Relays will always tried to be answered even if this is on.
3355 (Default: 1)
3356 AuthDirBadExitCCs CC,...
3358 AuthDirInvalidCCs CC,...
3360 AuthDirMiddleOnlyCCs CC,...
3362 AuthDirRejectCCs CC,...
3364 Authoritative directories only. These options contain a
3365 comma-separated list of country codes such that any server in one
3366 of those country codes will be marked as a bad exit/invalid for
3367 use, or rejected entirely.
3368 AuthDirSharedRandomness 0|1
3370 Authoritative directories only. Switch for the shared random
3371 protocol. If zero, the authority won’t participate in the protocol.
3372 If non-zero (default), the flag "shared-rand-participate" is added
3373 to the authority vote indicating participation in the protocol.
3374 (Default: 1)
3375 AuthDirTestEd25519LinkKeys 0|1
3377 Authoritative directories only. If this option is set to 0, then we
3378 treat relays as "Running" if their RSA key is correct when we probe
3379 them, regardless of their Ed25519 key. We should only ever set this
3380 option to 0 if there is some major bug in Ed25519 link
3381 authentication that causes us to label all the relays as not
3382 Running. (Default: 1)
3383 AuthDirTestReachability 0|1
3385 Authoritative directories only. If set to 1, then we periodically
3386 check every relay we know about to see whether it is running. If
3387 set to 0, we vote Running for every relay, and don’t perform these
3388 tests. (Default: 1)
3389 AuthDirVoteGuard node,node,...
3391 A list of identity fingerprints or country codes or address
3392 patterns of nodes to vote Guard for regardless of their uptime and
3393 bandwidth. See ExcludeNodes for more information on how to specify
3394 nodes.
3395 AuthDirVoteGuardBwThresholdFraction FRACTION
3397 The Guard flag bandwidth performance threshold fraction that is the
3398 fraction representing who gets the Guard flag out of all measured
3399 bandwidth. (Default: 0.75)
3400 AuthDirVoteGuardGuaranteeTimeKnown N seconds|minutes|hours|days|weeks
3402 A relay with at least this much weighted time known can be
3403 considered familiar enough to be a guard. (Default: 8 days)
3404 AuthDirVoteGuardGuaranteeWFU FRACTION
3406 A level of weighted fractional uptime (WFU) is that is sufficient
3407 to be a Guard. (Default: 0.98)
3408 AuthDirVoteStableGuaranteeMinUptime N seconds|minutes|hours|days|weeks
3410 If a relay’s uptime is at least this value, then it is always
3411 considered stable, regardless of the rest of the network. (Default:
3412 30 days)
3413 AuthDirVoteStableGuaranteeMTBF N seconds|minutes|hours|days|weeks
3415 If a relay’s mean time between failures (MTBF) is least this value,
3416 then it will always be considered stable. (Default: 5 days)
3417 BridgePassword Password
3419 If set, contains an HTTP authenticator that tells a bridge
3420 authority to serve all requested bridge information. Used by the
3421 (only partially implemented) "bridge community" design, where a
3422 community of bridge relay operators all use an alternate bridge
3423 directory authority, and their target user audience can
3424 periodically fetch the list of available community bridges to stay
3425 up-to-date. (Default: not set)
3426 ConsensusParams STRING
3428 STRING is a space-separated list of key=value pairs that Tor will
3429 include in the "params" line of its networkstatus vote. This
3430 directive can be specified multiple times so you don’t have to put
3431 it all on one line.
3432 DirAllowPrivateAddresses 0|1
3434 If set to 1, Tor will accept server descriptors with arbitrary
3435 "Address" elements. Otherwise, if the address is not an IP address
3436 or is a private IP address, it will reject the server descriptor.
3437 Additionally, Tor will allow exit policies for private networks to
3438 fulfill Exit flag requirements. (Default: 0)
3439 GuardfractionFile FILENAME
3441 V3 authoritative directories only. Configures the location of the
3442 guardfraction file which contains information about how long relays
3443 have been guards. (Default: unset)
3444 MinMeasuredBWsForAuthToIgnoreAdvertised N
3446 A total value, in abstract bandwidth units, describing how much
3447 measured total bandwidth an authority should have observed on the
3448 network before it will treat advertised bandwidths as wholly
3449 unreliable. (Default: 500)
3450 MinUptimeHidServDirectoryV2 N seconds|minutes|hours|days|weeks
3452 Minimum uptime of a relay to be accepted as a hidden service
3453 directory by directory authorities. (Default: 96 hours)
3454 RecommendedClientVersions STRING
3456 STRING is a comma-separated list of Tor versions currently believed
3457 to be safe for clients to use. This information is included in
3458 version 2 directories. If this is not set then the value of
3459 RecommendedVersions is used. When this is set then
3460 VersioningAuthoritativeDirectory should be set too.
3461 RecommendedServerVersions STRING
3463 STRING is a comma-separated list of Tor versions currently believed
3464 to be safe for servers to use. This information is included in
3465 version 2 directories. If this is not set then the value of
3466 RecommendedVersions is used. When this is set then
3467 VersioningAuthoritativeDirectory should be set too.
3468 RecommendedVersions STRING
3470 STRING is a comma-separated list of Tor versions currently believed
3471 to be safe. The list is included in each directory, and nodes which
3472 pull down the directory learn whether they need to upgrade. This
3473 option can appear multiple times: the values from multiple lines
3474 are spliced together. When this is set then
3475 VersioningAuthoritativeDirectory should be set too.
3476 V3AuthDistDelay N seconds|minutes|hours
3478 V3 authoritative directories only. Configures the server’s
3479 preferred delay between publishing its consensus and signature and
3480 assuming it has all the signatures from all the other authorities.
3481 Note that the actual time used is not the server’s preferred time,
3482 but the consensus of all preferences. (Default: 5 minutes)
3483 V3AuthNIntervalsValid NUM
3485 V3 authoritative directories only. Configures the number of
3486 VotingIntervals for which each consensus should be valid for.
3487 Choosing high numbers increases network partitioning risks;
3488 choosing low numbers increases directory traffic. Note that the
3489 actual number of intervals used is not the server’s preferred
3490 number, but the consensus of all preferences. Must be at least 2.
3491 (Default: 3)
3492 V3AuthUseLegacyKey 0|1
3494 If set, the directory authority will sign consensuses not only with
3495 its own signing key, but also with a "legacy" key and certificate
3496 with a different identity. This feature is used to migrate
3497 directory authority keys in the event of a compromise. (Default: 0)
3498 V3AuthVoteDelay N seconds|minutes|hours
3500 V3 authoritative directories only. Configures the server’s
3501 preferred delay between publishing its vote and assuming it has all
3502 the votes from all the other authorities. Note that the actual time
3503 used is not the server’s preferred time, but the consensus of all
3504 preferences. (Default: 5 minutes)
3505 V3AuthVotingInterval N minutes|hours
3507 V3 authoritative directories only. Configures the server’s
3508 preferred voting interval. Note that voting will actually happen at
3509 an interval chosen by consensus from all the authorities' preferred
3510 intervals. This time SHOULD divide evenly into a day. (Default: 1
3511 hour)
3512 V3BandwidthsFile FILENAME
3514 V3 authoritative directories only. Configures the location of the
3515 bandwidth-authority generated file storing information on relays'
3516 measured bandwidth capacities. To avoid inconsistent reads,
3517 bandwidth data should be written to temporary file, then renamed to
3518 the configured filename. (Default: unset)
3519 VersioningAuthoritativeDirectory 0|1
3521 When this option is set to 1, Tor adds information on which
3522 versions of Tor are still believed safe for use to the published
3523 directory. Each version 1 authority is automatically a versioning
3524 authority; version 2 authorities provide this service optionally.
3525 See RecommendedVersions, RecommendedClientVersions, and
3526 RecommendedServerVersions.
3527
3529 The following options are used to configure a hidden service. Some
3530 options apply per service and some apply for the whole tor instance.
3531 The next section describes the per service options that can only be set
3533 after the HiddenServiceDir directive
3534 PER SERVICE OPTIONS:
3536 HiddenServiceAllowUnknownPorts 0|1
3538 If set to 1, then connections to unrecognized ports do not cause
3539 the current hidden service to close rendezvous circuits. (Setting
3540 this to 0 is not an authorization mechanism; it is instead meant to
3541 be a mild inconvenience to port-scanners.) (Default: 0)
3542 HiddenServiceDir DIRECTORY
3544 Store data files for a hidden service in DIRECTORY. Every hidden
3545 service must have a separate directory. You may use this option
3546 multiple times to specify multiple services. If DIRECTORY does not
3547 exist, Tor will create it. Please note that you cannot add new
3548 Onion Service to already running Tor instance if Sandbox is
3549 enabled. (Note: in current versions of Tor, if DIRECTORY is a
3550 relative path, it will be relative to the current working directory
3551 of Tor instance, not to its DataDirectory. Do not rely on this
3552 behavior; it is not guaranteed to remain the same in future
3553 versions.)
3554 HiddenServiceDirGroupReadable 0|1
3556 If this option is set to 1, allow the filesystem group to read the
3557 hidden service directory and hostname file. If the option is set to
3558 0, only owner is able to read the hidden service directory.
3559 (Default: 0) Has no effect on Windows.
3560 HiddenServiceExportCircuitID protocol
3562 The onion service will use the given protocol to expose the global
3563 circuit identifier of each inbound client circuit. The only
3564 protocol supported right now 'haproxy'. This option is only for v3
3565 services. (Default: none)
3566 The haproxy option works in the following way: when the feature is
3569 enabled, the Tor process will write a header line when a client is
3570 connecting to the onion service. The header will look like this:
3571 "PROXY TCP6 fc00:dead:beef:4dad::ffff:ffff ::1 65535 42\r\n"
3574 We encode the "global circuit identifier" as the last 32-bits of
3577 the first IPv6 address. All other values in the header can safely
3578 be ignored. You can compute the global circuit identifier using the
3579 following formula given the IPv6 address
3580 "fc00:dead:beef:4dad::AABB:CCDD":
3581 global_circuit_id = (0xAA << 24) + (0xBB << 16) + (0xCC << 8) +
3584 0xDD;
3585 In the case above, where the last 32-bits are 0xffffffff, the
3588 global circuit identifier would be 4294967295. You can use this
3589 value together with Tor’s control port to terminate particular
3590 circuits using their global circuit identifiers. For more
3591 information about this see control-spec.txt.
3592 The HAProxy version 1 protocol is described in detail at
3595 https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
3596 HiddenServiceOnionBalanceInstance 0|1
3598 If set to 1, this onion service becomes an OnionBalance instance
3599 and will accept client connections destined to an OnionBalance
3600 frontend. In this case, Tor expects to find a file named
3601 "ob_config" inside the HiddenServiceDir directory with content:
3602 MasterOnionAddress <frontend_onion_address>
3604 where <frontend_onion_address> is the onion address of the
3606 OnionBalance frontend (e.g.
3607 wrxdvcaqpuzakbfww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.onion).
3608 HiddenServiceMaxStreams N
3610 The maximum number of simultaneous streams (connections) per
3611 rendezvous circuit. The maximum value allowed is 65535. (Setting
3612 this to 0 will allow an unlimited number of simultaneous streams.)
3613 (Default: 0)
3614 HiddenServiceMaxStreamsCloseCircuit 0|1
3616 If set to 1, then exceeding HiddenServiceMaxStreams will cause the
3617 offending rendezvous circuit to be torn down, as opposed to stream
3618 creation requests that exceed the limit being silently ignored.
3619 (Default: 0)
3620 HiddenServiceNumIntroductionPoints NUM
3622 Number of introduction points the hidden service will have. You
3623 can’t have more than 20. (Default: 3)
3624 HiddenServicePort VIRTPORT [TARGET]
3626 Configure a virtual port VIRTPORT for a hidden service. You may use
3627 this option multiple times; each time applies to the service using
3628 the most recent HiddenServiceDir. By default, this option maps the
3629 virtual port to the same port on 127.0.0.1 over TCP. You may
3630 override the target port, address, or both by specifying a target
3631 of addr, port, addr:port, or unix:path. (You can specify an IPv6
3632 target as [addr]:port. Unix paths may be quoted, and may use
3633 standard C escapes.) You may also have multiple lines with the same
3634 VIRTPORT: when a user connects to that VIRTPORT, one of the TARGETs
3635 from those lines will be chosen at random. Note that address-port
3636 pairs have to be comma-separated.
3637 HiddenServiceVersion 3
3639 A list of rendezvous service descriptor versions to publish for the
3640 hidden service. Currently, only version 3 is supported. (Default:
3641 3)
3642 PER INSTANCE OPTIONS:
3644 HiddenServiceSingleHopMode 0|1
3646 Experimental - Non Anonymous Hidden Services on a tor instance in
3647 HiddenServiceSingleHopMode make one-hop (direct) circuits between
3648 the onion service server, and the introduction and rendezvous
3649 points. (Onion service descriptors are still posted using 3-hop
3650 paths, to avoid onion service directories blocking the service.)
3651 This option makes every hidden service instance hosted by a tor
3652 instance a Single Onion Service. One-hop circuits make Single Onion
3653 servers easily locatable, but clients remain location-anonymous.
3654 However, the fact that a client is accessing a Single Onion rather
3655 than a Hidden Service may be statistically distinguishable.
3656 WARNING: Once a hidden service directory has been used by a tor
3659 instance in HiddenServiceSingleHopMode, it can NEVER be used again
3660 for a hidden service. It is best practice to create a new hidden
3661 service directory, key, and address for each new Single Onion
3662 Service and Hidden Service. It is not possible to run Single Onion
3663 Services and Hidden Services from the same tor instance: they
3664 should be run on different servers with different IP addresses.
3665 HiddenServiceSingleHopMode requires HiddenServiceNonAnonymousMode
3668 to be set to 1. Since a Single Onion service is non-anonymous, you
3669 can not configure a SOCKSPort on a tor instance that is running in
3670 HiddenServiceSingleHopMode. Can not be changed while tor is
3671 running. (Default: 0)
3672 HiddenServiceNonAnonymousMode 0|1
3674 Makes hidden services non-anonymous on this tor instance. Allows
3675 the non-anonymous HiddenServiceSingleHopMode. Enables direct
3676 connections in the server-side hidden service protocol. If you are
3677 using this option, you need to disable all client-side services on
3678 your Tor instance, including setting SOCKSPort to "0". Can not be
3679 changed while tor is running. (Default: 0)
3680 PublishHidServDescriptors 0|1
3682 If set to 0, Tor will run any hidden services you configure, but it
3683 won’t advertise them to the rendezvous directory. This option is
3684 only useful if you’re using a Tor controller that handles hidserv
3685 publishing for you. (Default: 1)
3686
3688 Service side:
3689 To configure client authorization on the service side, the
3691 "<HiddenServiceDir>/authorized_clients/" directory needs to exist. Each file
3692 in that directory should be suffixed with ".auth" (i.e. "alice.auth"; the
3693 file name is irrelevant) and its content format MUST be:
3694 <auth-type>:<key-type>:<base32-encoded-public-key>
3696 The supported <auth-type> are: "descriptor". The supported <key-type> are:
3698 "x25519". The <base32-encoded-public-key> is the base32 representation of
3699 the raw key bytes only (32 bytes for x25519).
3700 Each file MUST contain one line only. Any malformed file will be
3702 ignored. Client authorization will only be enabled for the service if tor
3703 successfully loads at least one authorization file.
3704 Note that once you've configured client authorization, anyone else with the
3706 address won't be able to access it from this point on. If no authorization is
3707 configured, the service will be accessible to anyone with the onion address.
3708 Revoking a client can be done by removing their ".auth" file, however the
3710 revocation will be in effect only after the tor process gets restarted even if
3711 a SIGHUP takes place.
3712 Client side:
3714 To access a v3 onion service with client authorization as a client, make sure
3716 you have ClientOnionAuthDir set in your torrc. Then, in the
3717 <ClientOnionAuthDir> directory, create an .auth_private file for the onion
3718 service corresponding to this key (i.e. 'bob_onion.auth_private'). The
3719 contents of the <ClientOnionAuthDir>/<user>.auth_private file should look like:
3720 <56-char-onion-addr-without-.onion-part>:descriptor:x25519:<x25519 private key in base32>
3722 For more information, please see
3724 https://2019.www.torproject.org/docs/tor-onion-service.html.en#ClientAuthorization
3725 .
3726
3728 The following options are used for running a testing Tor network.
3729 TestingTorNetwork 0|1
3731 If set to 1, Tor adjusts default values of the configuration
3732 options below, so that it is easier to set up a testing Tor
3733 network. May only be set if non-default set of DirAuthorities is
3734 set. Cannot be unset while Tor is running. (Default: 0)
3735 DirAllowPrivateAddresses 1
3738 EnforceDistinctSubnets 0
3739 AuthDirMaxServersPerAddr 0
3740 ClientBootstrapConsensusAuthorityDownloadInitialDelay 0
3741 ClientBootstrapConsensusFallbackDownloadInitialDelay 0
3742 ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay 0
3743 ClientDNSRejectInternalAddresses 0
3744 ClientRejectInternalAddresses 0
3745 CountPrivateBandwidth 1
3746 ExitPolicyRejectPrivate 0
3747 ExtendAllowPrivateAddresses 1
3748 V3AuthVotingInterval 5 minutes
3749 V3AuthVoteDelay 20 seconds
3750 V3AuthDistDelay 20 seconds
3751 TestingV3AuthInitialVotingInterval 150 seconds
3752 TestingV3AuthInitialVoteDelay 20 seconds
3753 TestingV3AuthInitialDistDelay 20 seconds
3754 TestingAuthDirTimeToLearnReachability 0 minutes
3755 MinUptimeHidServDirectoryV2 0 minutes
3756 TestingServerDownloadInitialDelay 0
3757 TestingClientDownloadInitialDelay 0
3758 TestingServerConsensusDownloadInitialDelay 0
3759 TestingClientConsensusDownloadInitialDelay 0
3760 TestingBridgeDownloadInitialDelay 10
3761 TestingBridgeBootstrapDownloadInitialDelay 0
3762 TestingClientMaxIntervalWithoutRequest 5 seconds
3763 TestingDirConnectionMaxStall 30 seconds
3764 TestingEnableConnBwEvent 1
3765 TestingEnableCellStatsEvent 1
3766 RendPostPeriod 2 minutes
3767 TestingAuthDirTimeToLearnReachability N seconds|minutes|hours
3769 After starting as an authority, do not make claims about whether
3770 routers are Running until this much time has passed. Changing this
3771 requires that TestingTorNetwork is set. (Default: 30 minutes)
3772 TestingAuthKeyLifetime N seconds|minutes|hours|days|weeks|months
3774 Overrides the default lifetime for a signing Ed25519 TLS Link
3775 authentication key. (Default: 2 days)
3776 TestingAuthKeySlop N seconds|minutes|hours
3778 TestingBridgeBootstrapDownloadInitialDelay N
3780 Initial delay in seconds for how long clients should wait before
3781 downloading a bridge descriptor for a new bridge. Changing this
3782 requires that TestingTorNetwork is set. (Default: 0)
3783 TestingBridgeDownloadInitialDelay N
3785 How long to wait (in seconds) once clients have successfully
3786 downloaded a bridge descriptor, before trying another download for
3787 that same bridge. Changing this requires that TestingTorNetwork is
3788 set. (Default: 10800)
3789 TestingClientConsensusDownloadInitialDelay N
3791 Initial delay in seconds for when clients should download
3792 consensuses. Changing this requires that TestingTorNetwork is set.
3793 (Default: 0)
3794 TestingClientDownloadInitialDelay N
3796 Initial delay in seconds for when clients should download things in
3797 general. Changing this requires that TestingTorNetwork is set.
3798 (Default: 0)
3799 TestingClientMaxIntervalWithoutRequest N seconds|minutes
3801 When directory clients have only a few descriptors to request, they
3802 batch them until they have more, or until this amount of time has
3803 passed. Changing this requires that TestingTorNetwork is set.
3804 (Default: 10 minutes)
3805 TestingDirAuthVoteExit node,node,...
3807 A list of identity fingerprints, country codes, and address
3808 patterns of nodes to vote Exit for regardless of their uptime,
3809 bandwidth, or exit policy. See ExcludeNodes for more information on
3810 how to specify nodes.
3811 In order for this option to have any effect, TestingTorNetwork has
3814 to be set. See ExcludeNodes for more information on how to specify
3815 nodes.
3816 TestingDirAuthVoteExitIsStrict 0|1
3818 If True (1), a node will never receive the Exit flag unless it is
3819 specified in the TestingDirAuthVoteExit list, regardless of its
3820 uptime, bandwidth, or exit policy.
3821 In order for this option to have any effect, TestingTorNetwork has
3824 to be set.
3825 TestingDirAuthVoteGuard node,node,...
3827 A list of identity fingerprints and country codes and address
3828 patterns of nodes to vote Guard for regardless of their uptime and
3829 bandwidth. See ExcludeNodes for more information on how to specify
3830 nodes.
3831 In order for this option to have any effect, TestingTorNetwork has
3834 to be set.
3835 TestingDirAuthVoteGuardIsStrict 0|1
3837 If True (1), a node will never receive the Guard flag unless it is
3838 specified in the TestingDirAuthVoteGuard list, regardless of its
3839 uptime and bandwidth.
3840 In order for this option to have any effect, TestingTorNetwork has
3843 to be set.
3844 TestingDirAuthVoteHSDir node,node,...
3846 A list of identity fingerprints and country codes and address
3847 patterns of nodes to vote HSDir for regardless of their uptime and
3848 DirPort. See ExcludeNodes for more information on how to specify
3849 nodes.
3850 In order for this option to have any effect, TestingTorNetwork must
3853 be set.
3854 TestingDirAuthVoteHSDirIsStrict 0|1
3856 If True (1), a node will never receive the HSDir flag unless it is
3857 specified in the TestingDirAuthVoteHSDir list, regardless of its
3858 uptime and DirPort.
3859 In order for this option to have any effect, TestingTorNetwork has
3862 to be set.
3863 TestingDirConnectionMaxStall N seconds|minutes
3865 Let a directory connection stall this long before expiring it.
3866 Changing this requires that TestingTorNetwork is set. (Default: 5
3867 minutes)
3868 TestingEnableCellStatsEvent 0|1
3870 If this option is set, then Tor controllers may register for
3871 CELL_STATS events. Changing this requires that TestingTorNetwork is
3872 set. (Default: 0)
3873 TestingEnableConnBwEvent 0|1
3875 If this option is set, then Tor controllers may register for
3876 CONN_BW events. Changing this requires that TestingTorNetwork is
3877 set. (Default: 0)
3878 TestingLinkCertLifetime N seconds|minutes|hours|days|weeks|months
3880 Overrides the default lifetime for the certificates used to
3881 authenticate our X509 link cert with our ed25519 signing key.
3882 (Default: 2 days)
3883 TestingLinkKeySlop N seconds|minutes|hours
3885 TestingMinExitFlagThreshold N
3887 KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3888 Sets a lower-bound for assigning an exit flag when running as an
3889 authority on a testing network. Overrides the usual default lower
3890 bound of 4 KBytes. (Default: 0)
3891 TestingMinFastFlagThreshold N
3893 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3894 Minimum value for the Fast flag. Overrides the ordinary minimum
3895 taken from the consensus when TestingTorNetwork is set. (Default:
3896 0.)
3897 TestingMinTimeToReportBandwidth N seconds|minutes|hours
3899 Do not report our measurements for our maximum observed bandwidth
3900 for any time period that has lasted for less than this amount of
3901 time. Values over 1 day have no effect. (Default: 1 day)
3902 TestingServerConsensusDownloadInitialDelay N
3904 Initial delay in seconds for when servers should download
3905 consensuses. Changing this requires that TestingTorNetwork is set.
3906 (Default: 0)
3907 TestingServerDownloadInitialDelay N
3909 Initial delay in seconds for when servers should download things in
3910 general. Changing this requires that TestingTorNetwork is set.
3911 (Default: 0)
3912 TestingSigningKeySlop N seconds|minutes|hours
3914 How early before the official expiration of a an Ed25519 signing
3915 key do we replace it and issue a new key? (Default: 3 hours for
3916 link and auth; 1 day for signing.)
3917 TestingV3AuthInitialDistDelay N seconds|minutes|hours
3919 Like V3AuthDistDelay, but for initial voting interval before the
3920 first consensus has been created. Changing this requires that
3921 TestingTorNetwork is set. (Default: 5 minutes)
3922 TestingV3AuthInitialVoteDelay N seconds|minutes|hours
3924 Like V3AuthVoteDelay, but for initial voting interval before the
3925 first consensus has been created. Changing this requires that
3926 TestingTorNetwork is set. (Default: 5 minutes)
3927 TestingV3AuthInitialVotingInterval N seconds|minutes|hours
3929 Like V3AuthVotingInterval, but for initial voting interval before
3930 the first consensus has been created. Changing this requires that
3931 TestingTorNetwork is set. (Default: 30 minutes)
3932 TestingV3AuthVotingStartOffset N seconds|minutes|hours
3934 Directory authorities offset voting start time by this much.
3935 Changing this requires that TestingTorNetwork is set. (Default: 0)
3936
3938 These options are not saved to the torrc file by the "SAVECONF"
3939 controller command. Other options of this type are documented in
3940 control-spec.txt, section 5.4. End-users should mostly ignore them.
3941 __ControlPort, __DirPort, __DNSPort, __ExtORPort, __NATDPort, __ORPort,
3943 __SocksPort, __TransPort
3944 These underscore-prefixed options are variants of the regular Port
3945 options. They behave the same, except they are not saved to the
3946 torrc file by the controller’s SAVECONF command.
3947
3949 Tor catches the following signals:
3950 SIGTERM
3952 Tor will catch this, clean up and sync to disk if necessary, and
3953 exit.
3954 SIGINT
3956 Tor clients behave as with SIGTERM; but Tor servers will do a
3957 controlled slow shutdown, closing listeners and waiting 30 seconds
3958 before exiting. (The delay can be configured with the
3959 ShutdownWaitLength config option.)
3960 SIGHUP
3962 The signal instructs Tor to reload its configuration (including
3963 closing and reopening logs), and kill and restart its helper
3964 processes if applicable.
3965 SIGUSR1
3967 Log statistics about current connections, past connections, and
3968 throughput.
3969 SIGUSR2
3971 Switch all logs to loglevel debug. You can go back to the old
3972 loglevels by sending a SIGHUP.
3973 SIGCHLD
3975 Tor receives this signal when one of its helper processes has
3976 exited, so it can clean up.
3977 SIGPIPE
3979 Tor catches this signal and ignores it.
3980 SIGXFSZ
3982 If this signal exists on your platform, Tor catches and ignores it.
3983
3985 /etc/tor/torrc
3986 Default location of the configuration file.
3987 $HOME/.torrc
3989 Fallback location for torrc, if /etc/tor/torrc is not found.
3990 /var/lib/tor/
3992 The tor process stores keys and other data here.
3993 CacheDirectory/cached-certs
3995 Contains downloaded directory key certificates that are used to
3996 verify authenticity of documents generated by the Tor directory
3997 authorities.
3998 CacheDirectory/cached-consensus and/or cached-microdesc-consensus
4000 The most recent consensus network status document we’ve downloaded.
4001 CacheDirectory/cached-descriptors and cached-descriptors.new
4003 These files contain the downloaded router statuses. Some routers
4004 may appear more than once; if so, the most recently published
4005 descriptor is used. Lines beginning with @-signs are annotations
4006 that contain more information about a given router. The .new file
4007 is an append-only journal; when it gets too large, all entries are
4008 merged into a new cached-descriptors file.
4009 CacheDirectory/cached-extrainfo and cached-extrainfo.new
4011 Similar to cached-descriptors, but holds optionally-downloaded
4012 "extra-info" documents. Relays use these documents to send
4013 inessential information about statistics, bandwidth history, and
4014 network health to the authorities. They aren’t fetched by default.
4015 See DownloadExtraInfo for more information.
4016 CacheDirectory/cached-microdescs and cached-microdescs.new
4018 These files hold downloaded microdescriptors. Lines beginning with
4019 @-signs are annotations that contain more information about a given
4020 router. The .new file is an append-only journal; when it gets too
4021 large, all entries are merged into a new cached-microdescs file.
4022 DataDirectory/state
4024 Contains a set of persistent key-value mappings. These include:
4025 • the current entry guards and their status.
4027 • the current bandwidth accounting values.
4029 • when the file was last written
4031 • what version of Tor generated the state file
4033 • a short history of bandwidth usage, as produced in the server
4035 descriptors.
4036 DataDirectory/sr-state
4038 Authority only. This file is used to record information about the
4039 current status of the shared-random-value voting state.
4040 CacheDirectory/diff-cache
4042 Directory cache only. Holds older consensuses and diffs from oldest
4043 to the most recent consensus of each type compressed in various
4044 ways. Each file contains a set of key-value arguments describing
4045 its contents, followed by a single NUL byte, followed by the main
4046 file contents.
4047 DataDirectory/bw_accounting
4049 This file is obsolete and the data is now stored in the state file
4050 instead. Used to track bandwidth accounting values (when the
4051 current period starts and ends; how much has been read and written
4052 so far this period).
4053 DataDirectory/control_auth_cookie
4055 This file can be used only when cookie authentication is enabled.
4056 Used for cookie authentication with the controller. Location can be
4057 overridden by the CookieAuthFile configuration option. Regenerated
4058 on startup. See control-spec.txt in torspec for details.
4059 DataDirectory/lock
4061 This file is used to prevent two Tor instances from using the same
4062 data directory. If access to this file is locked, data directory is
4063 already in use by Tor.
4064 DataDirectory/key-pinning-journal
4066 Used by authorities. A line-based file that records mappings
4067 between RSA1024 and Ed25519 identity keys. Authorities enforce
4068 these mappings, so that once a relay has picked an Ed25519 key,
4069 stealing or factoring the RSA1024 key will no longer let an
4070 attacker impersonate the relay.
4071 KeyDirectory/authority_identity_key
4073 A v3 directory authority’s master identity key, used to
4074 authenticate its signing key. Tor doesn’t use this while it’s
4075 running. The tor-gencert program uses this. If you’re running an
4076 authority, you should keep this key offline, and not put it in this
4077 file.
4078 KeyDirectory/authority_certificate
4080 Only directory authorities use this file. A v3 directory
4081 authority’s certificate which authenticates the authority’s current
4082 vote- and consensus-signing key using its master identity key.
4083 KeyDirectory/authority_signing_key
4085 Only directory authorities use this file. A v3 directory
4086 authority’s signing key that is used to sign votes and consensuses.
4087 Corresponds to the authority_certificate cert.
4088 KeyDirectory/legacy_certificate
4090 As authority_certificate; used only when V3AuthUseLegacyKey is set.
4091 See documentation for V3AuthUseLegacyKey.
4092 KeyDirectory/legacy_signing_key
4094 As authority_signing_key: used only when V3AuthUseLegacyKey is set.
4095 See documentation for V3AuthUseLegacyKey.
4096 KeyDirectory/secret_id_key
4098 A relay’s RSA1024 permanent identity key, including private and
4099 public components. Used to sign router descriptors, and to sign
4100 other keys.
4101 KeyDirectory/ed25519_master_id_public_key
4103 The public part of a relay’s Ed25519 permanent identity key.
4104 KeyDirectory/ed25519_master_id_secret_key
4106 The private part of a relay’s Ed25519 permanent identity key. This
4107 key is used to sign the medium-term ed25519 signing key. This file
4108 can be kept offline or encrypted. If so, Tor will not be able to
4109 generate new signing keys automatically; you’ll need to use tor
4110 --keygen to do so.
4111 KeyDirectory/ed25519_signing_secret_key
4113 The private and public components of a relay’s medium-term Ed25519
4114 signing key. This key is authenticated by the Ed25519 master key,
4115 which in turn authenticates other keys (and router descriptors).
4116 KeyDirectory/ed25519_signing_cert
4118 The certificate which authenticates "ed25519_signing_secret_key" as
4119 having been signed by the Ed25519 master key.
4120 KeyDirectory/secret_onion_key and secret_onion_key.old
4122 A relay’s RSA1024 short-term onion key. Used to decrypt old-style
4123 ("TAP") circuit extension requests. The .old file holds the
4124 previously generated key, which the relay uses to handle any
4125 requests that were made by clients that didn’t have the new one.
4126 KeyDirectory/secret_onion_key_ntor and secret_onion_key_ntor.old
4128 A relay’s Curve25519 short-term onion key. Used to handle modern
4129 ("ntor") circuit extension requests. The .old file holds the
4130 previously generated key, which the relay uses to handle any
4131 requests that were made by clients that didn’t have the new one.
4132 DataDirectory/fingerprint
4134 Only used by servers. Contains the fingerprint of the server’s RSA
4135 identity key.
4136 DataDirectory/fingerprint-ed25519
4138 Only used by servers. Contains the fingerprint of the server’s
4139 ed25519 identity key.
4140 DataDirectory/hashed-fingerprint
4142 Only used by bridges. Contains the hashed fingerprint of the
4143 bridge’s identity key. (That is, the hash of the hash of the
4144 identity key.)
4145 DataDirectory/approved-routers
4147 Only used by authoritative directory servers. Each line lists a
4148 status and an identity, separated by whitespace. Identities can be
4149 hex-encoded RSA fingerprints, or base-64 encoded ed25519 public
4150 keys. See the fingerprint file in a tor relay’s DataDirectory for
4151 an example fingerprint line. If the status is !reject, then
4152 descriptors from the given identity are rejected by this server. If
4153 it is !invalid then descriptors are accepted, but marked in the
4154 vote as not valid. If it is !badexit, then the authority will vote
4155 for it to receive a BadExit flag, indicating that it shouldn’t be
4156 used for traffic leaving the Tor network. If it is !middleonly,
4157 then the authority will vote for it to only be used in the middle
4158 of circuits. (Neither rejected nor invalid relays are included in
4159 the consensus.)
4160 DataDirectory/v3-status-votes
4162 Only for v3 authoritative directory servers. This file contains
4163 status votes from all the authoritative directory servers.
4164 CacheDirectory/unverified-consensus
4166 Contains a network consensus document that has been downloaded, but
4167 which we didn’t have the right certificates to check yet.
4168 CacheDirectory/unverified-microdesc-consensus
4170 Contains a microdescriptor-flavored network consensus document that
4171 has been downloaded, but which we didn’t have the right
4172 certificates to check yet.
4173 DataDirectory/unparseable-desc
4175 Onion server descriptors that Tor was unable to parse are dumped to
4176 this file. Only used for debugging.
4177 DataDirectory/router-stability
4179 Only used by authoritative directory servers. Tracks measurements
4180 for router mean-time-between-failures so that authorities have a
4181 fair idea of how to set their Stable flags.
4182 DataDirectory/stats/dirreq-stats
4184 Only used by directory caches and authorities. This file is used to
4185 collect directory request statistics.
4186 DataDirectory/stats/entry-stats
4188 Only used by servers. This file is used to collect incoming
4189 connection statistics by Tor entry nodes.
4190 DataDirectory/stats/bridge-stats
4192 Only used by servers. This file is used to collect incoming
4193 connection statistics by Tor bridges.
4194 DataDirectory/stats/exit-stats
4196 Only used by servers. This file is used to collect outgoing
4197 connection statistics by Tor exit routers.
4198 DataDirectory/stats/buffer-stats
4200 Only used by servers. This file is used to collect buffer usage
4201 history.
4202 DataDirectory/stats/conn-stats
4204 Only used by servers. This file is used to collect approximate
4205 connection history (number of active connections over time).
4206 DataDirectory/stats/hidserv-stats
4208 Only used by servers. This file is used to collect approximate
4209 counts of what fraction of the traffic is hidden service rendezvous
4210 traffic, and approximately how many hidden services the relay has
4211 seen.
4212 DataDirectory/networkstatus-bridges`
4214 Only used by authoritative bridge directories. Contains information
4215 about bridges that have self-reported themselves to the bridge
4216 authority.
4217 HiddenServiceDirectory/hostname
4219 The <base32-encoded-fingerprint>.onion domain name for this hidden
4220 service. If the hidden service is restricted to authorized clients
4221 only, this file also contains authorization data for all clients.
4222 Note
4224 The clients will ignore any extra subdomains prepended to a
4225 hidden service hostname. Supposing you have "xyz.onion" as your
4226 hostname, you can ask your clients to connect to
4227 "www.xyz.onion" or "irc.xyz.onion" for virtual-hosting
4228 purposes.
4229 HiddenServiceDirectory/private_key
4231 Contains the private key for this hidden service.
4232 HiddenServiceDirectory/client_keys
4234 Contains authorization data for a hidden service that is only
4235 accessible by authorized clients.
4236 HiddenServiceDirectory/onion_service_non_anonymous
4238 This file is present if a hidden service key was created in
4239 HiddenServiceNonAnonymousMode.
4240
4242 For more information, refer to the Tor Project website at
4243 https://www.torproject.org/ and the Tor specifications at
4244 https://spec.torproject.org. See also torsocks(1) and torify(1).
4245
4247 Because Tor is still under development, there may be plenty of bugs.
4248 Please report them at https://bugs.torproject.org/.
4249Tor 01/12/2023 TOR(1)