1TOR(1)                            Tor Manual                            TOR(1)
2
3
4

NAME

6       tor - The second-generation onion router
7

SYNOPSIS

9       tor [OPTION value]...
10

DESCRIPTION

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
19       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
25           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

COMMAND-LINE OPTIONS

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
35       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
45           Note
46           Configuration options on the command line override those in
47           configuration files. See THE CONFIGURATION FILE FORMAT for more
48           information.
49
50       The following options in this section are only recognized on the tor
51       command line, not in a configuration file.
52
53       -h, --help
54           Display a short help message and exit.
55
56       -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
62       --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
66       --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
72       --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
77       --hash-password PASSWORD
78           Generate a hashed password for control port access.
79
80       --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
85       --verify-config
86           Verify whether the configuration file is valid.
87
88       --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
94       --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
99       --service remove|start|stop
100           Remove, start, or stop a configured Tor Windows service.
101
102       --nt-service
103           Used internally to implement a Windows service.
104
105       --list-torrc-options
106           List all valid options.
107
108       --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
112       --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
116       --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
121       --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
131       --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
139
140           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
145               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
157       --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
164       --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
168
169           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
181       --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

THE CONFIGURATION FILE FORMAT

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
198       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
210       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
217       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
221       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
232       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

GENERAL OPTIONS

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
245       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
251
252           If the engine name is prefixed with a "!", then Tor will exit if
253           the engine cannot be loaded.
254
255       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
265       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
270       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
275       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
285
286           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
289
290           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
293
294           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
305       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
309       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
317       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
328       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
336
337           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
344       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
351
352           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
359
360           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
364       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
372
373           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
377
378           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
382
383           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
388       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
394       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
409
410           Recognized flags are:
411
412           GroupWritable
413               Unix domain sockets only: makes the socket get created as
414               group-writable.
415
416           WorldWritable
417               Unix domain sockets only: makes the socket get created as
418               world-writable.
419
420           RelaxDirModeCheck
421               Unix domain sockets only: Do not insist that the directory that
422               holds the socket be read-restricted.
423
424       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
429       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
434       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
439       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
445       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
452       CookieAuthFile Path
453           If set, this option overrides the default location and file name
454           for Tor’s cookie file. (See CookieAuthentication.)
455
456       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
463       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
469       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
475       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
480       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
489
490           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
502
503           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
509
510           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
516       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
523       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
533       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
550       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
559       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
566       ExtORPort [address:]port|auto
567           Open this port to listen for Extended ORPort connections from your
568           pluggable transports.
569
570           (Default: DataDirectory/extended_orport_auth_cookie)
571
572       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
578       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
585       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
596
597           FallbackDirs should be stable relays with stable IP addresses,
598           ports, and identity keys. They must have a DirPort.
599
600
601           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
606       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
611       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
617       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
623       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
629       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
647       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
652       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
659       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
665       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
672       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
680       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
686       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
691       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
700       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
710
711           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
720       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
725       Log [domain,...]minSeverity[-maxSeverity] ... file FILENAME
726
727       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
737
738           This is an advanced feature which is most useful for debugging one
739           or two of Tor’s subsystems at a time.
740
741
742           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
748
749           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
754       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
760       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
769       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
778       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
786       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
794           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
800           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
806           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
810           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
814           As an example, here only 5.6.7.8 will be allowed to connect:
815
816               MetricsPort 1.2.3.4:9035
817               MetricsPortPolicy accept 5.6.7.8
818
819       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
826           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
833       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
839       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
849       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
857       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
866       __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
871       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
877       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
883       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
894       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
898       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
903       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
911       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
922       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
928       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
934       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
940
941           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
948       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
956
957           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
963
964           Launching new Onion Services through the control port is not
965           supported with current syscall sandboxing implementation.
966
967
968           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
972
973           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
977
978           (Default: 0)
979
980       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
989
990           The possible scheduler types are:
991
992           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
999
1000           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
1006
1007           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
1011       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
1018       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
1022       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
1026       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
1030       Socks5ProxyUsername username
1031
1032       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
1037       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
1042       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
1052
1053               The only protocol supported right now 'haproxy'. This option is only for
1054               clients. (Default: none) +
1055
1056               The HAProxy version 1 proxy protocol is described in detail at
1057               https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt +
1058
1059               Both source IP address and source port will be set to zero.
1060
1061       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
1065       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
1071       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
1077       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

CLIENT OPTIONS

1082       The following options are useful only for clients (that is, if
1083       SocksPort, HTTPTunnelPort, TransPort, DNSPort, or NATDPort is
1084       non-zero):
1085
1086       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
1092       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
1100       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
1105       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
1114
1115           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
1122
1123           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
1128       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
1136       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
1142       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
1151       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
1160       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
1169       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
1174       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
1181       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
1187           <onion-address>:descriptor:x25519:<base32-encoded-privkey>
1188
1189           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
1194       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
1203       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
1212       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
1221       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
1229       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
1236       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
1244       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
1254       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
1260       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
1268       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
1275       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
1280       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
1288       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
1293       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
1303       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
1313       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
1330           NOTES:
1331
1332            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
1337                   MapAddress www.torproject.org 192.0.2.1
1338                   MapAddress www.torproject.org 198.51.100.1
1339
1340            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
1344                   MapAddress 198.51.100.1 203.0.113.1
1345                   MapAddress www.torproject.org 198.51.100.1
1346
1347            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
1351                   MapAddress www.torproject.org *.torproject.org.torserver.exit
1352
1353            4. Using a wildcard to match only part of a string (as in
1354               *ample.com) is also invalid.
1355
1356            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
1360            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
1365       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
1374       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
1380       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
1391
1392           This option is only for people who cannot use TransPort. (Default:
1393           0)
1394
1395       NewCircuitPeriod NUM
1396           Every NUM seconds consider whether to build a new circuit.
1397           (Default: 30 seconds)
1398
1399       PathBiasCircThreshold NUM
1400
1401       PathBiasDropGuards NUM
1402
1403       PathBiasExtremeRate NUM
1404
1405       PathBiasNoticeRate NUM
1406
1407       PathBiasWarnRate NUM
1408
1409       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
1415
1416           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
1424
1425           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
1429
1430           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
1435       PathBiasUseThreshold NUM
1436
1437       PathBiasNoticeUseRate NUM
1438
1439       PathBiasExtremeUseRate NUM
1440
1441       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
1446
1447           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
1455
1456           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
1461       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
1474       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
1484       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
1492       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
1499
1500           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
1507       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
1514       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
1521       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
1527       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
1532       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
1538       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
1549
1550           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
1557
1558           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
1564           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
1570           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
1577           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
1583           IsolateDestPort
1584               Don’t share circuits with streams targeting a different
1585               destination port.
1586
1587           IsolateDestAddr
1588               Don’t share circuits with streams targeting a different
1589               destination address.
1590
1591           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
1597           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
1604           Other recognized flags for a SocksPort are:
1605
1606           NoIPv4Traffic
1607               Tell exits to not connect to IPv4 addresses in response to
1608               SOCKS requests on this connection.
1609
1610           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
1615           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
1620           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
1625           NoOnionTraffic
1626               Do not connect to .onion addresses in SOCKS5 requests.
1627
1628           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
1634           CacheIPv4DNS
1635               Tells the client to remember IPv4 DNS answers we receive from
1636               exit nodes via this connection.
1637
1638           CacheIPv6DNS
1639               Tells the client to remember IPv6 DNS answers we receive from
1640               exit nodes via this connection.
1641
1642           GroupWritable
1643               Unix domain sockets only: makes the socket get created as
1644               group-writable.
1645
1646           WorldWritable
1647               Unix domain sockets only: makes the socket get created as
1648               world-writable.
1649
1650           CacheDNS
1651               Tells the client to remember all DNS answers we receive from
1652               exit nodes via this connection.
1653
1654           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
1661           UseIPv6Cache
1662               Tells the client to use any cached IPv6 DNS answers we have
1663               when making requests via this connection.
1664
1665           UseDNSCache
1666               Tells the client to use any cached DNS answers we have when
1667               making requests via this connection.
1668
1669           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
1675           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
1685           ExtendedErrors
1686               Return extended error code in the SOCKS reply. So far, the
1687               possible errors are:
1688
1689                   X'F0' Onion Service Descriptor Can Not be Found
1690
1691                   The requested onion service descriptor can't be found on the
1692                   hashring and thus not reachable by the client. (v3 only)
1693
1694                   X'F1' Onion Service Descriptor Is Invalid
1695
1696                   The requested onion service descriptor can't be parsed or
1697                   signature validation failed. (v3 only)
1698
1699                   X'F2' Onion Service Introduction Failed
1700
1701                   All introduction attempts failed either due to a combination of
1702                   NACK by the intro point or time out. (v3 only)
1703
1704                   X'F3' Onion Service Rendezvous Failed
1705
1706                   Every rendezvous circuit has timed out and thus the client is
1707                   unable to rendezvous with the service. (v3 only)
1708
1709                   X'F4' Onion Service Missing Client Authorization
1710
1711                   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
1715                   X'F5' Onion Service Wrong Client Authorization
1716
1717                   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
1722                   X'F6' Onion Service Invalid Address
1723
1724                   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
1728                   X'F7' Onion Service Introduction Timed Out
1729
1730                   Similar to X'F2' code but in this case, all introduction attempts
1731                   have failed due to a time out. (v3 only)
1732
1733           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
1737       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
1747       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
1760       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
1765       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
1775
1776           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
1781       TransProxyType default|TPROXY|ipfw|pf-divert
1782           TransProxyType may only be enabled when there is transparent proxy
1783           listener enabled.
1784
1785
1786           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
1792
1793           Set this option to "ipfw" to use the FreeBSD ipfw interface.
1794
1795
1796           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
1803
1804           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
1807
1808           (Default: "default")
1809
1810       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
1816       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
1821       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
1829       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
1835       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
1840       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
1847       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
1854       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
1862       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
1869       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
1878       VirtualAddrNetworkIPv4 IPv4Address/bits
1879
1880       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
1886
1887           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

CIRCUIT TIMEOUT OPTIONS

1900       The following options are useful for configuring timeouts related to
1901       building Tor circuits and using them:
1902
1903       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
1913       LearnCircuitBuildTimeout 0|1
1914           If 0, CircuitBuildTimeout adaptive learning is disabled. (Default:
1915           1)
1916
1917       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
1924       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
1930       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

DORMANT MODE OPTIONS

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
1939       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
1946           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
1954       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
1960       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
1968           After the first time Tor starts, it begins in dormant mode if it
1969           was dormant before, and not otherwise. (Default: 0)
1970
1971       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
1977       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

NODE SELECTION OPTIONS

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
1990       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
1998
1999           This option can appear multiple times: the values from multiple
2000           lines are spliced together.
2001
2002
2003           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
2007       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
2015
2016           This option can appear multiple times: the values from multiple
2017           lines are spliced together.
2018
2019
2020           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
2027
2028           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
2033
2034           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
2039       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
2048           This option can appear multiple times: the values from multiple
2049           lines are spliced together.
2050
2051
2052       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
2058
2059           This option can appear multiple times: the values from multiple
2060           lines are spliced together.
2061
2062
2063           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
2068
2069           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
2076
2077           The ExcludeNodes option overrides this option: any node listed in
2078           both ExitNodes and ExcludeNodes is treated as excluded.
2079
2080
2081           The .exit address notation, if enabled via MapAddress, overrides
2082           this option.
2083
2084       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
2093       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
2102           (Example: HSLayer2Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234,
2103           {cc}, 255.254.0.0/8)
2104
2105
2106           This option can appear multiple times: the values from multiple
2107           lines are spliced together.
2108
2109
2110           When this is set, the resulting hidden service paths will look
2111           like:
2112
2113           C - G - L2 - M - Rend
2114
2115           C - G - L2 - M - HSDir
2116
2117           C - G - L2 - M - Intro
2118
2119           S - G - L2 - M - Rend
2120
2121           S - G - L2 - M - HSDir
2122
2123           S - G - L2 - M - Intro
2124
2125
2126           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
2130           This option may be combined with HSLayer3Nodes to create paths of
2131           the form:
2132
2133           C - G - L2 - L3 - Rend
2134
2135           C - G - L2 - L3 - M - HSDir
2136
2137           C - G - L2 - L3 - M - Intro
2138
2139           S - G - L2 - L3 - M - Rend
2140
2141           S - G - L2 - L3 - HSDir
2142
2143           S - G - L2 - L3 - Intro
2144
2145
2146           ExcludeNodes have higher priority than HSLayer2Nodes, which means
2147           that nodes specified in ExcludeNodes will not be picked.
2148
2149           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
2156           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
2163       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
2172           (Example: HSLayer3Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234,
2173           {cc}, 255.254.0.0/8)
2174
2175
2176           This option can appear multiple times: the values from multiple
2177           lines are spliced together.
2178
2179
2180           When this is set by itself, the resulting hidden service paths will
2181           look like:
2182
2183           C - G - M - L3 - Rend
2184
2185           C - G - M - L3 - M - HSDir
2186
2187           C - G - M - L3 - M - Intro
2188
2189           S - G - M - L3 - M - Rend
2190
2191           S - G - M - L3 - HSDir
2192
2193           S - G - M - L3 - Intro
2194
2195           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
2199           While it is possible to use this option by itself, it should be
2200           combined with HSLayer2Nodes to create paths of the form:
2201
2202           C - G - L2 - L3 - Rend
2203
2204           C - G - L2 - L3 - M - HSDir
2205
2206           C - G - L2 - L3 - M - Intro
2207
2208           S - G - L2 - L3 - M - Rend
2209
2210           S - G - L2 - L3 - HSDir
2211
2212           S - G - L2 - L3 - Intro
2213
2214
2215           ExcludeNodes have higher priority than HSLayer3Nodes, which means
2216           that nodes specified in ExcludeNodes will not be picked.
2217
2218           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
2225           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
2232       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
2238           This option can appear multiple times: the values from multiple
2239           lines are spliced together.
2240
2241
2242           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
2248               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
2253               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
2257       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
2267       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

SERVER OPTIONS

2282       The following options are useful only for servers (that is, if ORPort
2283       is non-zero):
2284
2285       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
2307
2308           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
2313       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
2322       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
2335       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
2346       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
2353       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
2358       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
2363       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
2369
2370           Note: make sure that no MyFamily lines are present in your torrc
2371           when relay is configured in bridge mode.
2372
2373       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
2382       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
2391
2392           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
2396       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
2402       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
2412
2413           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
2417
2418           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
2424
2425           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
2432
2433           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
2440
2441           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
2454
2455           This directive can be specified multiple times so you don’t have to
2456           put it all on one line.
2457
2458
2459           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
2468
2469           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
2475
2476           The default exit policy is:
2477
2478               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
2490           Since the default exit policy uses accept/reject *, it applies to
2491           both IPv4 and IPv6 addresses.
2492
2493       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
2504       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
2509       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
2516
2517           If ExitRelay is set to 0, no traffic is allowed to exit, and the
2518           ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored.
2519
2520
2521           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
2527       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
2536       GeoIPFile filename
2537           A filename containing IPv4 GeoIP data, for use with by-country
2538           statistics.
2539
2540       GeoIPv6File filename
2541           A filename containing IPv6 GeoIP data, for use with by-country
2542           statistics.
2543
2544       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
2551       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
2556       KeyDirectory DIR
2557           Store secret keys in DIR. Can not be changed while tor is running.
2558           (Default: the "keys" subdirectory of DataDirectory.)
2559
2560       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
2568       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
2573       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
2584       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
2589       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
2602
2603           If you run more than one relay, the MyFamily option on each relay
2604           must list all other relays, as described above.
2605
2606
2607           Note: do not use MyFamily when configuring your Tor instance as a
2608           bridge.
2609
2610       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
2616       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
2622       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
2628       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
2634
2635           Tor recognizes these flags on each ORPort:
2636
2637           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
2644           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
2651           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
2655           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
2659           For obvious reasons, NoAdvertise and NoListen are mutually
2660           exclusive, and IPv4Only and IPv6Only are mutually exclusive.
2661
2662       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
2667
2668           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
2678       ReducedExitPolicy 0|1
2679           If set, use a reduced exit policy rather than the default one.
2680
2681
2682           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
2688
2689           The reduced exit policy is:
2690
2691               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
2771               (Default: 0)
2772
2773       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
2780       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
2786       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
2793       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
2801       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
2810       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
2819       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
2827       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
2835       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
2841       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
2845           (Example: ServerTransportOptions obfs45 shared-secret=bridgepasswd
2846           cache=/var/lib/tor/cache) (Default: none)
2847
2848       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
2853       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
2859       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
2865       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

STATISTICS OPTIONS

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
2875       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
2883       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
2892       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
2900       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
2909       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
2917       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
2925       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
2934       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
2941       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
2946           A relay is considered overloaded if at least one of these
2947           conditions is met:
2948
2949           •   Onionskins are starting to be dropped.
2950
2951           •   The OOM was invoked.
2952
2953           •   (Exit only) DNS timeout occurs X% of the time over Y seconds
2954               (values controlled by consensus parameters, see
2955               param-spec.txt).
2956
2957               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
2961           •   TCP Port exhaustion.
2962
2963           •   Connection rate limits have been reached (read and write side).
2964
2965       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

DIRECTORY SERVER OPTIONS

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
2979       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
2988       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
2994       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
3001
3002           The same flags are supported here as are supported by ORPort. This
3003           port can only be IPv4.
3004
3005           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
3010       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
3016       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

DENIAL OF SERVICE MITIGATION OPTIONS

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
3031       The following is a series of configuration options for relays and then
3032       options for onion services and how they work.
3033
3034       The mitigations take place at relays, and are as follows:
3035
3036        1. If a single client address makes too many concurrent connections
3037           (this is configurable via DoSConnectionMaxConcurrentCount), hang up
3038           on further connections.
3039
3040        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
3048        3. If a client asks to establish a rendezvous point to you directly
3049           (ex: Tor2Web client), ignore the request.
3050
3051       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
3056       The values set by the consensus, if any, can be found here:
3057       https://consensus-health.torproject.org/#consensusparams
3058
3059       If any of the DoS mitigations are enabled, a heartbeat message will
3060       appear in your log at NOTICE level which looks like:
3061
3062           DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses.
3063           2238 connections closed. 8052 single hop clients refused.
3064
3065       The following options are useful only for a public relay. They control
3066       the Denial of Service mitigation subsystem described above.
3067
3068       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
3078       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
3085       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
3092       DoSCircuitCreationDefenseType NUM
3093           This is the type of defense applied to a detected client address.
3094           The possible values are:
3095
3096           1: No defense.
3097
3098           2: Refuse circuit creation for the
3099           DoSCircuitCreationDefenseTimePeriod period of time.
3100
3101           "0" means use the consensus parameter. If not defined in the
3102           consensus, the value is 2. (Default: 0)
3103
3104       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
3112       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
3117       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
3124       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
3128           1: No defense.
3129
3130           2: Immediately close new connections.
3131
3132           "0" means use the consensus parameter. If not defined in the
3133           consensus, the value is 2. (Default: 0)
3134
3135       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
3142       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
3150       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
3156       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
3162       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
3169       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
3173       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
3179       The following options are per onion service:
3180
3181       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
3187           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
3192       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
3198       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
3204       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
3208       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
3216       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
3219       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
3227       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

DIRECTORY AUTHORITY SERVER OPTIONS

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
3237       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
3244       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
3250       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
3256       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
3261
3262           (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
3266       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
3271       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
3277       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
3283       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
3292
3293               The content of the consensus depends on the number of voting authorities
3294               that set AuthDirHasIPv6Connectivity:
3295
3296               If no authorities set AuthDirHasIPv6Connectivity 1, there will be no
3297               IPv6 ORPorts in the consensus.
3298
3299               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
3304               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
3311       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
3316       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
3323       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
3330       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
3335       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
3343       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
3350       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
3357       AuthDirBadExitCCs CC,...
3358
3359       AuthDirInvalidCCs CC,...
3360
3361       AuthDirMiddleOnlyCCs CC,...
3362
3363       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
3369       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
3376       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
3384       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
3390       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
3396       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
3401       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
3405       AuthDirVoteGuardGuaranteeWFU FRACTION
3406           A level of weighted fractional uptime (WFU) is that is sufficient
3407           to be a Guard. (Default: 0.98)
3408
3409       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
3414       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
3418       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
3427       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
3433       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
3440       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
3445       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
3451       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
3455       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
3462       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
3469       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
3477       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
3484       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
3493       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
3499       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
3506       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
3513       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
3520       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

HIDDEN SERVICE OPTIONS

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
3532       The next section describes the per service options that can only be set
3533       after the HiddenServiceDir directive
3534
3535       PER SERVICE OPTIONS:
3536
3537       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
3543       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
3555       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
3561       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
3567
3568           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
3572
3573           "PROXY TCP6 fc00:dead:beef:4dad::ffff:ffff ::1 65535 42\r\n"
3574
3575
3576           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
3582
3583           global_circuit_id = (0xAA << 24) + (0xBB << 16) + (0xCC << 8) +
3584           0xDD;
3585
3586
3587           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
3593
3594           The HAProxy version 1 protocol is described in detail at
3595           https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
3596
3597       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
3603           MasterOnionAddress <frontend_onion_address>
3604
3605           where <frontend_onion_address> is the onion address of the
3606           OnionBalance frontend (e.g.
3607           wrxdvcaqpuzakbfww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.onion).
3608
3609       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
3615       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
3621       HiddenServiceNumIntroductionPoints NUM
3622           Number of introduction points the hidden service will have. You
3623           can’t have more than 20. (Default: 3)
3624
3625       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
3638       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
3643       PER INSTANCE OPTIONS:
3644
3645       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
3657
3658           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
3666
3667           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
3673       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
3681       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

CLIENT AUTHORIZATION

3688       Service side:
3689
3690           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
3695           <auth-type>:<key-type>:<base32-encoded-public-key>
3696
3697           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
3701           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
3705           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
3709           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
3713       Client side:
3714
3715           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
3721           <56-char-onion-addr-without-.onion-part>:descriptor:x25519:<x25519 private key in base32>
3722
3723       For more information, please see
3724       https://2019.www.torproject.org/docs/tor-onion-service.html.en#ClientAuthorization
3725       .
3726

TESTING NETWORK OPTIONS

3728       The following options are used for running a testing Tor network.
3729
3730       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
3736
3737               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
3768       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
3773       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
3777       TestingAuthKeySlop N seconds|minutes|hours
3778
3779       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
3784       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
3790       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
3795       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
3800       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
3806       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
3812
3813           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
3817       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
3822
3823           In order for this option to have any effect, TestingTorNetwork has
3824           to be set.
3825
3826       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
3832
3833           In order for this option to have any effect, TestingTorNetwork has
3834           to be set.
3835
3836       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
3841
3842           In order for this option to have any effect, TestingTorNetwork has
3843           to be set.
3844
3845       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
3851
3852           In order for this option to have any effect, TestingTorNetwork must
3853           be set.
3854
3855       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
3860
3861           In order for this option to have any effect, TestingTorNetwork has
3862           to be set.
3863
3864       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
3869       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
3874       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
3879       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
3884       TestingLinkKeySlop N seconds|minutes|hours
3885
3886       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
3892       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
3898       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
3903       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
3908       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
3913       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
3918       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
3923       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
3928       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
3933       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

NON-PERSISTENT OPTIONS

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
3942       __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

SIGNALS

3949       Tor catches the following signals:
3950
3951       SIGTERM
3952           Tor will catch this, clean up and sync to disk if necessary, and
3953           exit.
3954
3955       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
3961       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
3966       SIGUSR1
3967           Log statistics about current connections, past connections, and
3968           throughput.
3969
3970       SIGUSR2
3971           Switch all logs to loglevel debug. You can go back to the old
3972           loglevels by sending a SIGHUP.
3973
3974       SIGCHLD
3975           Tor receives this signal when one of its helper processes has
3976           exited, so it can clean up.
3977
3978       SIGPIPE
3979           Tor catches this signal and ignores it.
3980
3981       SIGXFSZ
3982           If this signal exists on your platform, Tor catches and ignores it.
3983

FILES

3985       /etc/tor/torrc
3986           Default location of the configuration file.
3987
3988       $HOME/.torrc
3989           Fallback location for torrc, if /etc/tor/torrc is not found.
3990
3991       /var/lib/tor/
3992           The tor process stores keys and other data here.
3993
3994       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
3999       CacheDirectory/cached-consensus and/or cached-microdesc-consensus
4000           The most recent consensus network status document we’ve downloaded.
4001
4002       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
4010       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
4017       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
4023       DataDirectory/state
4024           Contains a set of persistent key-value mappings. These include:
4025
4026           •   the current entry guards and their status.
4027
4028           •   the current bandwidth accounting values.
4029
4030           •   when the file was last written
4031
4032           •   what version of Tor generated the state file
4033
4034           •   a short history of bandwidth usage, as produced in the server
4035               descriptors.
4036
4037       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
4041       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
4048       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
4054       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
4060       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
4065       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
4072       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
4079       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
4084       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
4089       KeyDirectory/legacy_certificate
4090           As authority_certificate; used only when V3AuthUseLegacyKey is set.
4091           See documentation for V3AuthUseLegacyKey.
4092
4093       KeyDirectory/legacy_signing_key
4094           As authority_signing_key: used only when V3AuthUseLegacyKey is set.
4095           See documentation for V3AuthUseLegacyKey.
4096
4097       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
4102       KeyDirectory/ed25519_master_id_public_key
4103           The public part of a relay’s Ed25519 permanent identity key.
4104
4105       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
4112       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
4117       KeyDirectory/ed25519_signing_cert
4118           The certificate which authenticates "ed25519_signing_secret_key" as
4119           having been signed by the Ed25519 master key.
4120
4121       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
4127       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
4133       DataDirectory/fingerprint
4134           Only used by servers. Contains the fingerprint of the server’s RSA
4135           identity key.
4136
4137       DataDirectory/fingerprint-ed25519
4138           Only used by servers. Contains the fingerprint of the server’s
4139           ed25519 identity key.
4140
4141       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
4146       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
4161       DataDirectory/v3-status-votes
4162           Only for v3 authoritative directory servers. This file contains
4163           status votes from all the authoritative directory servers.
4164
4165       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
4169       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
4174       DataDirectory/unparseable-desc
4175           Onion server descriptors that Tor was unable to parse are dumped to
4176           this file. Only used for debugging.
4177
4178       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
4183       DataDirectory/stats/dirreq-stats
4184           Only used by directory caches and authorities. This file is used to
4185           collect directory request statistics.
4186
4187       DataDirectory/stats/entry-stats
4188           Only used by servers. This file is used to collect incoming
4189           connection statistics by Tor entry nodes.
4190
4191       DataDirectory/stats/bridge-stats
4192           Only used by servers. This file is used to collect incoming
4193           connection statistics by Tor bridges.
4194
4195       DataDirectory/stats/exit-stats
4196           Only used by servers. This file is used to collect outgoing
4197           connection statistics by Tor exit routers.
4198
4199       DataDirectory/stats/buffer-stats
4200           Only used by servers. This file is used to collect buffer usage
4201           history.
4202
4203       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
4207       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
4213       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
4218       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
4223               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
4230       HiddenServiceDirectory/private_key
4231           Contains the private key for this hidden service.
4232
4233       HiddenServiceDirectory/client_keys
4234           Contains authorization data for a hidden service that is only
4235           accessible by authorized clients.
4236
4237       HiddenServiceDirectory/onion_service_non_anonymous
4238           This file is present if a hidden service key was created in
4239           HiddenServiceNonAnonymousMode.
4240

SEE ALSO

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

BUGS

4247       Because Tor is still under development, there may be plenty of bugs.
4248       Please report them at https://bugs.torproject.org/.
4249
4250
4251
4252Tor                               01/12/2023                            TOR(1)
Impressum