1TOR(1) Tor Manual TOR(1)
2
6 tor - The second-generation onion router
7
9 tor [OPTION value]...
10
12 Tor is a connection-oriented anonymizing communication service. Users
13 choose a source-routed path through a set of nodes, and negotiate a
14 "virtual circuit" through the network, in which each node knows its
15 predecessor and successor, but no others. Traffic flowing down the
16 circuit is unwrapped by a symmetric key at each node, which reveals the
17 downstream node.
18 Basically, Tor provides a distributed network of servers or relays
20 ("onion routers"). Users bounce their TCP streams — web traffic, ftp,
21 ssh, etc. — around the network, and recipients, observers, and even the
22 relays themselves have difficulty tracking the source of the stream.
23 By default, tor will act as a client only. To help the network by
25 providing bandwidth as a relay, change the ORPort configuration option
26 — see below. Please also consult the documentation on the Tor Project’s
27 website.
28
30 -h, -help
31 Display a short help message and exit.
32 -f FILE
34 Specify a new configuration file to contain further Tor
35 configuration options OR pass - to make Tor read its configuration
36 from standard input. (Default: /etc/tor/torrc, or $HOME/.torrc if
37 that file is not found)
38 --allow-missing-torrc
40 Do not require that configuration file specified by -f exist if
41 default torrc can be accessed.
42 --defaults-torrc FILE
44 Specify a file in which to find default values for Tor options. The
45 contents of this file are overridden by those in the regular
46 configuration file, and by those on the command line. (Default:
47 /etc/tor/torrc-defaults.)
48 --ignore-missing-torrc
50 Specifies that Tor should treat a missing torrc file as though it
51 were empty. Ordinarily, Tor does this for missing default torrc
52 files, but not for those specified on the command line.
53 --hash-password PASSWORD
55 Generates a hashed password for control port access.
56 --list-fingerprint
58 Generate your keys and output your nickname and fingerprint.
59 --verify-config
61 Verify the configuration file is valid.
62 --service install [--options command-line options]
64 Install an instance of Tor as a Windows service, with the provided
65 command-line options. Current instructions can be found at
66 https://www.torproject.org/docs/faq#NTService
67 --service remove|start|stop
69 Remove, start, or stop a configured Tor Windows service.
70 --nt-service
72 Used internally to implement a Windows service.
73 --list-torrc-options
75 List all valid options.
76 --list-deprecated-options
78 List all valid options that are scheduled to become obsolete in a
79 future version. (This is a warning, not a promise.)
80 --version
82 Display Tor version and exit.
83 --quiet|--hush
85 Override the default console log. By default, Tor starts out
86 logging messages at level "notice" and higher to the console. It
87 stops doing so after it parses its configuration, if the
88 configuration tells it to log anywhere else. You can override this
89 behavior with the --hush option, which tells Tor to only send
90 warnings and errors to the console, or with the --quiet option,
91 which tells Tor not to log to the console at all.
92 --keygen [--newpass]
94 Running "tor --keygen" creates a new ed25519 master identity key
95 for a relay, or only a fresh temporary signing key and certificate,
96 if you already have a master key. Optionally you can encrypt the
97 master identity key with a passphrase: Tor will ask you for one. If
98 you don’t want to encrypt the master key, just don’t enter any
99 passphrase when asked.
100 The --newpass option should be used with --keygen only when you
103 need to add, change, or remove a passphrase on an existing ed25519
104 master identity key. You will be prompted for the old passphase (if
105 any), and the new passphrase (if any).
106 When generating a master key, you will probably want to use
109 --DataDirectory to control where the keys and certificates will be
110 stored, and --SigningKeyLifetime to control their lifetimes. Their
111 behavior is as documented in the server options section below. (You
112 must have write access to the specified DataDirectory.)
113 To use the generated files, you must copy them to the
116 DataDirectory/keys directory of your Tor daemon, and make sure that
117 they are owned by the user actually running the Tor daemon on your
118 system.
119 --passphrase-fd FILEDES
121 Filedescriptor to read the passphrase from. Note that unlike with
122 the tor-gencert program, the entire file contents are read and used
123 as the passphrase, including any trailing newlines. Default: read
124 from the terminal.
125 --key-expiration [purpose]
127 The purpose specifies which type of key certificate to determine
128 the expiration of. The only currently recognised purpose is "sign".
129 Running "tor --key-expiration sign" will attempt to find your
132 signing key certificate and will output, both in the logs as well
133 as to stdout, the signing key certificate’s expiration time in
134 ISO-8601 format. For example, the output sent to stdout will be of
135 the form: "signing-cert-expiry: 2017-07-25 08:30:15 UTC"
136 Other options can be specified on the command-line in the format
138 "--option value", in the format "option value", or in a configuration
139 file. For instance, you can tell Tor to start listening for SOCKS
140 connections on port 9999 by passing --SocksPort 9999 or SocksPort 9999
141 to it on the command line, or by putting "SocksPort 9999" in the
142 configuration file. You will need to quote options with spaces in them:
143 if you want Tor to log all debugging messages to debug.log, you will
144 probably need to say --Log debug file debug.log.
145 Options on the command line override those in configuration files. See
147 the next section for more information.
148
150 All configuration options in a configuration are written on a single
151 line by default. They take the form of an option name and a value, or
152 an option name and a quoted value (option value or option "value").
153 Anything after a # character is treated as a comment. Options are
154 case-insensitive. C-style escaped characters are allowed inside quoted
155 values. To split one configuration entry into multiple lines, use a
156 single backslash character (\) before the end of the line. Comments can
157 be used in such multiline entries, but they must start at the beginning
158 of a line.
159 Configuration options can be imported from files or folders using the
161 %include option with the value being a path. If the path is a file, the
162 options from the file will be parsed as if they were written where the
163 %include option is. If the path is a folder, all files on that folder
164 will be parsed following lexical order. Files starting with a dot are
165 ignored. Files on subfolders are ignored. The %include option can be
166 used recursively.
167 By default, an option on the command line overrides an option found in
169 the configuration file, and an option in a configuration file overrides
170 one in the defaults file.
171 This rule is simple for options that take a single value, but it can
173 become complicated for options that are allowed to occur more than
174 once: if you specify four SocksPorts in your configuration file, and
175 one more SocksPort on the command line, the option on the command line
176 will replace all of the SocksPorts in the configuration file. If this
177 isn’t what you want, prefix the option name with a plus sign (+), and
178 it will be appended to the previous set of options instead. For
179 example, setting SocksPort 9100 will use only port 9100, but setting
180 +SocksPort 9100 will use ports 9100 and 9050 (because this is the
181 default).
182 Alternatively, you might want to remove every instance of an option in
184 the configuration file, and not replace it at all: you might want to
185 say on the command line that you want no SocksPorts at all. To do that,
186 prefix the option name with a forward slash (/). You can use the plus
187 sign (+) and the forward slash (/) in the configuration file and on the
188 command line.
189
191 BandwidthRate N
192 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
193 A token bucket limits the average incoming bandwidth usage on this
194 node to the specified number of bytes per second, and the average
195 outgoing bandwidth usage to that same value. If you want to run a
196 relay in the public network, this needs to be at the very least 75
197 KBytes for a relay (that is, 600 kbits) or 50 KBytes for a bridge
198 (400 kbits) — but of course, more is better; we recommend at least
199 250 KBytes (2 mbits) if possible. (Default: 1 GByte)
200 Note that this option, and other bandwidth-limiting options, apply
203 to TCP data only: They do not count TCP headers or DNS traffic.
204 With this option, and in other options that take arguments in
207 bytes, KBytes, and so on, other formats are also supported.
208 Notably, "KBytes" can also be written as "kilobytes" or "kb";
209 "MBytes" can be written as "megabytes" or "MB"; "kbits" can be
210 written as "kilobits"; and so forth. Tor also accepts "byte" and
211 "bit" in the singular. The prefixes "tera" and "T" are also
212 recognized. If no units are given, we default to bytes. To avoid
213 confusion, we recommend writing "bytes" or "bits" explicitly, since
214 it’s easy to forget that "B" means bytes, not bits.
215 BandwidthBurst N
217 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
218 Limit the maximum token bucket size (also known as the burst) to
219 the given number of bytes in each direction. (Default: 1 GByte)
220 MaxAdvertisedBandwidth N
222 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
223 If set, we will not advertise more than this amount of bandwidth
224 for our BandwidthRate. Server operators who want to reduce the
225 number of clients who ask to build circuits through them (since
226 this is proportional to advertised bandwidth rate) can thus reduce
227 the CPU demands on their server without impacting network
228 performance.
229 RelayBandwidthRate N
231 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
232 If not 0, a separate token bucket limits the average incoming
233 bandwidth usage for _relayed traffic_ on this node to the specified
234 number of bytes per second, and the average outgoing bandwidth
235 usage to that same value. Relayed traffic currently is calculated
236 to include answers to directory requests, but that may change in
237 future versions. They do not include directory fetches by the relay
238 (from authority or other relays), because that is considered
239 "client" activity. (Default: 0)
240 RelayBandwidthBurst N
242 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
243 If not 0, limit the maximum token bucket size (also known as the
244 burst) for _relayed traffic_ to the given number of bytes in each
245 direction. They do not include directory fetches by the relay (from
246 authority or other relays), because that is considered "client"
247 activity. (Default: 0)
248 PerConnBWRate N
250 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
251 If this option is set manually, or via the "perconnbwrate"
252 consensus field, Tor will use it for separate rate limiting for
253 each connection from a non-relay. (Default: 0)
254 PerConnBWBurst N
256 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
257 If this option is set manually, or via the "perconnbwburst"
258 consensus field, Tor will use it for separate rate limiting for
259 each connection from a non-relay. (Default: 0)
260 ClientTransportPlugin transport socks4|socks5 IP:PORT,
262 ClientTransportPlugin transport exec path-to-binary [options]
263 In its first form, when set along with a corresponding Bridge line,
264 the Tor client forwards its traffic to a SOCKS-speaking proxy on
265 "IP:PORT". (IPv4 addresses should written as-is; IPv6 addresses
266 should be wrapped in square brackets.) It’s the duty of that proxy
267 to properly forward the traffic to the bridge.
268 In its second form, when set along with a corresponding Bridge
271 line, the Tor client launches the pluggable transport proxy
272 executable in path-to-binary using options as its command-line
273 options, and forwards its traffic to it. It’s the duty of that
274 proxy to properly forward the traffic to the bridge.
275 ServerTransportPlugin transport exec path-to-binary [options]
277 The Tor relay launches the pluggable transport proxy in
278 path-to-binary using options as its command-line options, and
279 expects to receive proxied client traffic from it.
280 ServerTransportListenAddr transport IP:PORT
282 When this option is set, Tor will suggest IP:PORT as the listening
283 address of any pluggable transport proxy that tries to launch
284 transport. (IPv4 addresses should written as-is; IPv6 addresses
285 should be wrapped in square brackets.)
286 ServerTransportOptions transport k=v k=v ...
288 When this option is set, Tor will pass the k=v parameters to any
289 pluggable transport proxy that tries to launch transport.
290 (Example: ServerTransportOptions obfs45 shared-secret=bridgepasswd
292 cache=/var/lib/tor/cache)
293 ExtORPort [address:]port|auto
295 Open this port to listen for Extended ORPort connections from your
296 pluggable transports.
297 ExtORPortCookieAuthFile Path
299 If set, this option overrides the default location and file name
300 for the Extended ORPort’s cookie file — the cookie file is needed
301 for pluggable transports to communicate through the Extended
302 ORPort.
303 ExtORPortCookieAuthFileGroupReadable 0|1
305 If this option is set to 0, don’t allow the filesystem group to
306 read the Extended OR Port cookie file. If the option is set to 1,
307 make the cookie file readable by the default GID. [Making the file
308 readable by other groups is not yet implemented; let us know if you
309 need this for some reason.] (Default: 0)
310 ConnLimit NUM
312 The minimum number of file descriptors that must be available to
313 the Tor process before it will start. Tor will ask the OS for as
314 many file descriptors as the OS will allow (you can find this by
315 "ulimit -H -n"). If this number is less than ConnLimit, then Tor
316 will refuse to start.
317 Tor relays need thousands of sockets, to connect to every other
320 relay. If you are running a private bridge, you can reduce the
321 number of sockets that Tor uses. For example, to limit Tor to 500
322 sockets, run "ulimit -n 500" in a shell. Then start tor in the same
323 shell, with ConnLimit 500. You may also need to set DisableOOSCheck
324 0.
325 Unless you have severely limited sockets, you probably don’t need
328 to adjust ConnLimit itself. It has no effect on Windows, since that
329 platform lacks getrlimit(). (Default: 1000)
330 DisableNetwork 0|1
332 When this option is set, we don’t listen for or accept any
333 connections other than controller connections, and we close (and
334 don’t reattempt) any outbound connections. Controllers sometimes
335 use this option to avoid using the network until Tor is fully
336 configured. Tor will make still certain network-related calls (like
337 DNS lookups) as a part of its configuration process, even if
338 DisableNetwork is set. (Default: 0)
339 ConstrainedSockets 0|1
341 If set, Tor will tell the kernel to attempt to shrink the buffers
342 for all sockets to the size specified in ConstrainedSockSize. This
343 is useful for virtual servers and other environments where system
344 level TCP buffers may be limited. If you’re on a virtual server,
345 and you encounter the "Error creating network socket: No buffer
346 space available" message, you are likely experiencing this problem.
347 The preferred solution is to have the admin increase the buffer
350 pool for the host itself via /proc/sys/net/ipv4/tcp_mem or
351 equivalent facility; this configuration option is a second-resort.
352 The DirPort option should also not be used if TCP buffers are
355 scarce. The cached directory requests consume additional sockets
356 which exacerbates the problem.
357 You should not enable this feature unless you encounter the "no
360 buffer space available" issue. Reducing the TCP buffers affects
361 window size for the TCP stream and will reduce throughput in
362 proportion to round trip time on long paths. (Default: 0)
363 ConstrainedSockSize N bytes|KBytes
365 When ConstrainedSockets is enabled the receive and transmit buffers
366 for all sockets will be set to this limit. Must be a value between
367 2048 and 262144, in 1024 byte increments. Default of 8192 is
368 recommended.
369 ControlPort PORT|unix:path|auto [flags]
371 If set, Tor will accept connections on this port and allow those
372 connections to control the Tor process using the Tor Control
373 Protocol (described in control-spec.txt in torspec). Note: unless
374 you also specify one or more of HashedControlPassword or
375 CookieAuthentication, setting this option will cause Tor to allow
376 any process on the local host to control it. (Setting both
377 authentication methods means either method is sufficient to
378 authenticate to Tor.) This option is required for many Tor
379 controllers; most use the value of 9051. If a unix domain socket is
380 used, you may quote the path using standard C escape sequences. Set
381 it to "auto" to have Tor pick a port for you. (Default: 0)
382 Recognized flags are...
385 GroupWritable
387 Unix domain sockets only: makes the socket get created as
388 group-writable.
389 WorldWritable
391 Unix domain sockets only: makes the socket get created as
392 world-writable.
393 RelaxDirModeCheck
395 Unix domain sockets only: Do not insist that the directory that
396 holds the socket be read-restricted.
397 ControlSocket Path
399 Like ControlPort, but listens on a Unix domain socket, rather than
400 a TCP socket. 0 disables ControlSocket. (Unix and Unix-like
401 systems only.) (Default: 0)
402 ControlSocketsGroupWritable 0|1
404 If this option is set to 0, don’t allow the filesystem group to
405 read and write unix sockets (e.g. ControlSocket). If the option is
406 set to 1, make the control socket readable and writable by the
407 default GID. (Default: 0)
408 HashedControlPassword hashed_password
410 Allow connections on the control port if they present the password
411 whose one-way hash is hashed_password. You can compute the hash of
412 a password by running "tor --hash-password password". You can
413 provide several acceptable passwords by using more than one
414 HashedControlPassword line.
415 CookieAuthentication 0|1
417 If this option is set to 1, allow connections on the control port
418 when the connecting process knows the contents of a file named
419 "control_auth_cookie", which Tor will create in its data directory.
420 This authentication method should only be used on systems with good
421 filesystem security. (Default: 0)
422 CookieAuthFile Path
424 If set, this option overrides the default location and file name
425 for Tor’s cookie file. (See CookieAuthentication above.)
426 CookieAuthFileGroupReadable 0|1
428 If this option is set to 0, don’t allow the filesystem group to
429 read the cookie file. If the option is set to 1, make the cookie
430 file readable by the default GID. [Making the file readable by
431 other groups is not yet implemented; let us know if you need this
432 for some reason.] (Default: 0)
433 ControlPortWriteToFile Path
435 If set, Tor writes the address and port of any control port it
436 opens to this address. Usable by controllers to learn the actual
437 control port when ControlPort is set to "auto".
438 ControlPortFileGroupReadable 0|1
440 If this option is set to 0, don’t allow the filesystem group to
441 read the control port file. If the option is set to 1, make the
442 control port file readable by the default GID. (Default: 0)
443 DataDirectory DIR
445 Store working data in DIR. Can not be changed while tor is running.
446 (Default: ~/.tor if your home directory is not /; otherwise,
447 /var/lib/tor. On Windows, the default is your ApplicationData
448 folder.)
449 DataDirectoryGroupReadable 0|1
451 If this option is set to 0, don’t allow the filesystem group to
452 read the DataDirectory. If the option is set to 1, make the
453 DataDirectory readable by the default GID. (Default: 0)
454 CacheDirectory DIR
456 Store cached directory data in DIR. Can not be changed while tor is
457 running. (Default: uses the value of DataDirectory.)
458 CacheDirectoryGroupReadable 0|1|auto
460 If this option is set to 0, don’t allow the filesystem group to
461 read the CacheDirectory. If the option is set to 1, make the
462 CacheDirectory readable by the default GID. If the option is
463 "auto", then we use the setting for DataDirectoryGroupReadable when
464 the CacheDirectory is the same as the DataDirectory, and 0
465 otherwise. (Default: auto)
466 FallbackDir ipv4address:port orport=port id=fingerprint [weight=num]
468 [ipv6=[ipv6address]:orport]
469 When we’re unable to connect to any directory cache for directory
470 info (usually because we don’t know about any yet) we try a
471 directory authority. Clients also simultaneously try a FallbackDir,
472 to avoid hangs on client startup if a directory authority is down.
473 Clients retry FallbackDirs more often than directory authorities,
474 to reduce the load on the directory authorities. By default, the
475 directory authorities are also FallbackDirs. Specifying a
476 FallbackDir replaces Tor’s default hard-coded FallbackDirs (if
477 any). (See the DirAuthority entry for an explanation of each flag.)
478 UseDefaultFallbackDirs 0|1
480 Use Tor’s default hard-coded FallbackDirs (if any). (When a
481 FallbackDir line is present, it replaces the hard-coded
482 FallbackDirs, regardless of the value of UseDefaultFallbackDirs.)
483 (Default: 1)
484 DirAuthority [nickname] [flags] ipv4address:port fingerprint
486 Use a nonstandard authoritative directory server at the provided
487 address and port, with the specified key fingerprint. This option
488 can be repeated many times, for multiple authoritative directory
489 servers. Flags are separated by spaces, and determine what kind of
490 an authority this directory is. By default, an authority is not
491 authoritative for any directory style or version unless an
492 appropriate flag is given. Tor will use this authority as a bridge
493 authoritative directory if the "bridge" flag is set. If a flag
494 "orport=port" is given, Tor will use the given port when opening
495 encrypted tunnels to the dirserver. If a flag "weight=num" is
496 given, then the directory server is chosen randomly with
497 probability proportional to that weight (default 1.0). If a flag
498 "v3ident=fp" is given, the dirserver is a v3 directory authority
499 whose v3 long-term signing key has the fingerprint fp. Lastly, if
500 an "ipv6=[ipv6address]:orport" flag is present, then the directory
501 authority is listening for IPv6 connections on the indicated IPv6
502 address and OR Port.
503 Tor will contact the authority at ipv4address to download directory
506 documents. The provided port value is a dirport; clients ignore
507 this in favor of the specified "orport=" value. If an IPv6 ORPort
508 is supplied, Tor will also download directory documents at the IPv6
509 ORPort.
510 If no DirAuthority line is given, Tor will use the default
513 directory authorities. NOTE: this option is intended for setting up
514 a private Tor network with its own directory authorities. If you
515 use it, you will be distinguishable from other users, because you
516 won’t believe the same authorities they do.
517 DirAuthorityFallbackRate NUM
519 When configured to use both directory authorities and fallback
520 directories, the directory authorities also work as fallbacks. They
521 are chosen with their regular weights, multiplied by this number,
522 which should be 1.0 or less. The default is less than 1, to reduce
523 load on authorities. (Default: 0.1)
524 AlternateDirAuthority [nickname] [flags] ipv4address:port fingerprint
526 AlternateBridgeAuthority [nickname] [flags] ipv4address:port
528 fingerprint
529 These options behave as DirAuthority, but they replace fewer of the
530 default directory authorities. Using AlternateDirAuthority replaces
531 the default Tor directory authorities, but leaves the default
532 bridge authorities in place. Similarly, AlternateBridgeAuthority
533 replaces the default bridge authority, but leaves the directory
534 authorities alone.
535 DisableAllSwap 0|1
537 If set to 1, Tor will attempt to lock all current and future memory
538 pages, so that memory cannot be paged out. Windows, OS X and
539 Solaris are currently not supported. We believe that this feature
540 works on modern Gnu/Linux distributions, and that it should work on
541 *BSD systems (untested). This option requires that you start your
542 Tor as root, and you should use the User option to properly reduce
543 Tor’s privileges. Can not be changed while tor is running.
544 (Default: 0)
545 DisableDebuggerAttachment 0|1
547 If set to 1, Tor will attempt to prevent basic debugging attachment
548 attempts by other processes. This may also keep Tor from generating
549 core files if it crashes. It has no impact for users who wish to
550 attach if they have CAP_SYS_PTRACE or if they are root. We believe
551 that this feature works on modern Gnu/Linux distributions, and that
552 it may also work on *BSD systems (untested). Some modern Gnu/Linux
553 systems such as Ubuntu have the kernel.yama.ptrace_scope sysctl and
554 by default enable it as an attempt to limit the PTRACE scope for
555 all user processes by default. This feature will attempt to limit
556 the PTRACE scope for Tor specifically - it will not attempt to
557 alter the system wide ptrace scope as it may not even exist. If you
558 wish to attach to Tor with a debugger such as gdb or strace you
559 will want to set this to 0 for the duration of your debugging.
560 Normal users should leave it on. Disabling this option while Tor is
561 running is prohibited. (Default: 1)
562 FetchDirInfoEarly 0|1
564 If set to 1, Tor will always fetch directory information like other
565 directory caches, even if you don’t meet the normal criteria for
566 fetching early. Normal users should leave it off. (Default: 0)
567 FetchDirInfoExtraEarly 0|1
569 If set to 1, Tor will fetch directory information before other
570 directory caches. It will attempt to download directory information
571 closer to the start of the consensus period. Normal users should
572 leave it off. (Default: 0)
573 FetchHidServDescriptors 0|1
575 If set to 0, Tor will never fetch any hidden service descriptors
576 from the rendezvous directories. This option is only useful if
577 you’re using a Tor controller that handles hidden service fetches
578 for you. (Default: 1)
579 FetchServerDescriptors 0|1
581 If set to 0, Tor will never fetch any network status summaries or
582 server descriptors from the directory servers. This option is only
583 useful if you’re using a Tor controller that handles directory
584 fetches for you. (Default: 1)
585 FetchUselessDescriptors 0|1
587 If set to 1, Tor will fetch every consensus flavor, and all server
588 descriptors and authority certificates referenced by those
589 consensuses, except for extra info descriptors. When this option is
590 1, Tor will also keep fetching descriptors, even when idle. If set
591 to 0, Tor will avoid fetching useless descriptors: flavors that it
592 is not using to build circuits, and authority certificates it does
593 not trust. When Tor hasn’t built any application circuits, it will
594 go idle, and stop fetching descriptors. This option is useful if
595 you’re using a tor client with an external parser that uses a full
596 consensus. This option fetches all documents except extrainfo
597 descriptors, DirCache fetches and serves all documents except
598 extrainfo descriptors, DownloadExtraInfo* fetches extrainfo
599 documents, and serves them if DirCache is on, and
600 UseMicrodescriptors changes the flavour of consensues and
601 descriptors that is fetched and used for building circuits.
602 (Default: 0)
603 HTTPProxy host[:port]
605 Tor will make all its directory requests through this host:port (or
606 host:80 if port is not specified), rather than connecting directly
607 to any directory servers. (DEPRECATED: As of 0.3.1.0-alpha you
608 should use HTTPSProxy.)
609 HTTPProxyAuthenticator username:password
611 If defined, Tor will use this username:password for Basic HTTP
612 proxy authentication, as in RFC 2617. This is currently the only
613 form of HTTP proxy authentication that Tor supports; feel free to
614 submit a patch if you want it to support others. (DEPRECATED: As of
615 0.3.1.0-alpha you should use HTTPSProxyAuthenticator.)
616 HTTPSProxy host[:port]
618 Tor will make all its OR (SSL) connections through this host:port
619 (or host:443 if port is not specified), via HTTP CONNECT rather
620 than connecting directly to servers. You may want to set
621 FascistFirewall to restrict the set of ports you might try to
622 connect to, if your HTTPS proxy only allows connecting to certain
623 ports.
624 HTTPSProxyAuthenticator username:password
626 If defined, Tor will use this username:password for Basic HTTPS
627 proxy authentication, as in RFC 2617. This is currently the only
628 form of HTTPS proxy authentication that Tor supports; feel free to
629 submit a patch if you want it to support others.
630 Sandbox 0|1
632 If set to 1, Tor will run securely through the use of a syscall
633 sandbox. Otherwise the sandbox will be disabled. The option is
634 currently an experimental feature. It only works on Linux-based
635 operating systems, and only when Tor has been built with the
636 libseccomp library. This option can not be changed while tor is
637 running.
638 When the Sandbox is 1, the following options can not be changed
640 when tor is running: Address ConnLimit CookieAuthFile
641 DirPortFrontPage ExtORPortCookieAuthFile Logs
642 ServerDNSResolvConfFile Tor must remain in client or server mode
643 (some changes to ClientOnly and ORPort are not allowed).
644 ClientOnionAuthDir and any files in it won’t reload on HUP signal.
645 (Default: 0)
646 Socks4Proxy host[:port]
648 Tor will make all OR connections through the SOCKS 4 proxy at
649 host:port (or host:1080 if port is not specified).
650 Socks5Proxy host[:port]
652 Tor will make all OR connections through the SOCKS 5 proxy at
653 host:port (or host:1080 if port is not specified).
654 Socks5ProxyUsername username
656 Socks5ProxyPassword password
658 If defined, authenticate to the SOCKS 5 server using username and
659 password in accordance to RFC 1929. Both username and password must
660 be between 1 and 255 characters.
661 UnixSocksGroupWritable 0|1
663 If this option is set to 0, don’t allow the filesystem group to
664 read and write unix sockets (e.g. SocksPort unix:). If the option
665 is set to 1, make the Unix socket readable and writable by the
666 default GID. (Default: 0)
667 KeepalivePeriod NUM
669 To keep firewalls from expiring connections, send a padding
670 keepalive cell every NUM seconds on open connections that are in
671 use. (Default: 5 minutes)
672 Log minSeverity[-maxSeverity] stderr|stdout|syslog
674 Send all messages between minSeverity and maxSeverity to the
675 standard output stream, the standard error stream, or to the system
676 log. (The "syslog" value is only supported on Unix.) Recognized
677 severity levels are debug, info, notice, warn, and err. We advise
678 using "notice" in most cases, since anything more verbose may
679 provide sensitive information to an attacker who obtains the logs.
680 If only one severity level is given, all messages of that level or
681 higher will be sent to the listed destination.
682 Log minSeverity[-maxSeverity] file FILENAME
684 As above, but send log messages to the listed filename. The "Log"
685 option may appear more than once in a configuration file. Messages
686 are sent to all the logs that match their severity level.
687 Log [domain,...]minSeverity[-maxSeverity] ... file FILENAME
689 Log [domain,...]minSeverity[-maxSeverity] ... stderr|stdout|syslog
691 As above, but select messages by range of log severity and by a set
692 of "logging domains". Each logging domain corresponds to an area of
693 functionality inside Tor. You can specify any number of severity
694 ranges for a single log statement, each of them prefixed by a
695 comma-separated list of logging domains. You can prefix a domain
696 with ~ to indicate negation, and use * to indicate "all domains".
697 If you specify a severity range without a list of domains, it
698 matches all domains.
699 This is an advanced feature which is most useful for debugging one
702 or two of Tor’s subsystems at a time.
703 The currently recognized domains are: general, crypto, net, config,
706 fs, protocol, mm, http, app, control, circ, rend, bug, dir,
707 dirserv, or, edge, acct, hist, handshake, heartbeat, channel,
708 sched, guard, consdiff, and dos. Domain names are case-insensitive.
709 For example, "Log [handshake]debug [~net,~mm]info notice stdout"
712 sends to stdout: all handshake messages of any severity, all
713 info-and-higher messages from domains other than networking and
714 memory management, and all messages of severity notice or higher.
715 LogMessageDomains 0|1
717 If 1, Tor includes message domains with each log message. Every log
718 message currently has at least one domain; most currently have
719 exactly one. This doesn’t affect controller log messages. (Default:
720 0)
721 MaxUnparseableDescSizeToLog N bytes|KBytes|MBytes|GBytes|TBytes
723 Unparseable descriptors (e.g. for votes, consensuses, routers) are
724 logged in separate files by hash, up to the specified size in
725 total. Note that only files logged during the lifetime of this Tor
726 process count toward the total; this is intended to be used to
727 debug problems without opening live servers to resource exhaustion
728 attacks. (Default: 10 MB)
729 OutboundBindAddress IP
731 Make all outbound connections originate from the IP address
732 specified. This is only useful when you have multiple network
733 interfaces, and you want all of Tor’s outgoing connections to use a
734 single one. This option may be used twice, once with an IPv4
735 address and once with an IPv6 address. IPv6 addresses should be
736 wrapped in square brackets. This setting will be ignored for
737 connections to the loopback addresses (127.0.0.0/8 and ::1), and is
738 not used for DNS requests as well.
739 OutboundBindAddressOR IP
741 Make all outbound non-exit (relay and other) connections originate
742 from the IP address specified. This option overrides
743 OutboundBindAddress for the same IP version. This option may be
744 used twice, once with an IPv4 address and once with an IPv6
745 address. IPv6 addresses should be wrapped in square brackets. This
746 setting will be ignored for connections to the loopback addresses
747 (127.0.0.0/8 and ::1).
748 OutboundBindAddressExit IP
750 Make all outbound exit connections originate from the IP address
751 specified. This option overrides OutboundBindAddress for the same
752 IP version. This option may be used twice, once with an IPv4
753 address and once with an IPv6 address. IPv6 addresses should be
754 wrapped in square brackets. This setting will be ignored for
755 connections to the loopback addresses (127.0.0.0/8 and ::1).
756 PidFile FILE
758 On startup, write our PID to FILE. On clean shutdown, remove FILE.
759 Can not be changed while tor is running.
760 ProtocolWarnings 0|1
762 If 1, Tor will log with severity 'warn' various cases of other
763 parties not following the Tor specification. Otherwise, they are
764 logged with severity 'info'. (Default: 0)
765 RunAsDaemon 0|1
767 If 1, Tor forks and daemonizes to the background. This option has
768 no effect on Windows; instead you should use the --service
769 command-line option. Can not be changed while tor is running.
770 (Default: 0)
771 LogTimeGranularity NUM
773 Set the resolution of timestamps in Tor’s logs to NUM milliseconds.
774 NUM must be positive and either a divisor or a multiple of 1
775 second. Note that this option only controls the granularity written
776 by Tor to a file or console log. Tor does not (for example) "batch
777 up" log messages to affect times logged by a controller, times
778 attached to syslog messages, or the mtime fields on log files.
779 (Default: 1 second)
780 TruncateLogFile 0|1
782 If 1, Tor will overwrite logs at startup and in response to a HUP
783 signal, instead of appending to them. (Default: 0)
784 SyslogIdentityTag tag
786 When logging to syslog, adds a tag to the syslog identity such that
787 log entries are marked with "Tor-tag". Can not be changed while tor
788 is running. (Default: none)
789 AndroidIdentityTag tag
791 When logging to Android’s logging subsystem, adds a tag to the log
792 identity such that log entries are marked with "Tor-tag". Can not
793 be changed while tor is running. (Default: none)
794 SafeLogging 0|1|relay
796 Tor can scrub potentially sensitive strings from log messages (e.g.
797 addresses) by replacing them with the string [scrubbed]. This way
798 logs can still be useful, but they don’t leave behind personally
799 identifying information about what sites a user might have visited.
800 If this option is set to 0, Tor will not perform any scrubbing, if
803 it is set to 1, all potentially sensitive strings are replaced. If
804 it is set to relay, all log messages generated when acting as a
805 relay are sanitized, but all messages generated when acting as a
806 client are not. Note: Tor may not heed this option when logging at
807 log levels below Notice. (Default: 1)
808 User Username
810 On startup, setuid to this user and setgid to their primary group.
811 Can not be changed while tor is running.
812 KeepBindCapabilities 0|1|auto
814 On Linux, when we are started as root and we switch our identity
815 using the User option, the KeepBindCapabilities option tells us
816 whether to try to retain our ability to bind to low ports. If this
817 value is 1, we try to keep the capability; if it is 0 we do not;
818 and if it is auto, we keep the capability only if we are configured
819 to listen on a low port. Can not be changed while tor is running.
820 (Default: auto.)
821 HardwareAccel 0|1
823 If non-zero, try to use built-in (static) crypto hardware
824 acceleration when available. Can not be changed while tor is
825 running. (Default: 0)
826 AccelName NAME
828 When using OpenSSL hardware crypto acceleration attempt to load the
829 dynamic engine of this name. This must be used for any dynamic
830 hardware engine. Names can be verified with the openssl engine
831 command. Can not be changed while tor is running.
832 AccelDir DIR
834 Specify this option if using dynamic hardware acceleration and the
835 engine implementation library resides somewhere other than the
836 OpenSSL default. Can not be changed while tor is running.
837 AvoidDiskWrites 0|1
839 If non-zero, try to write to disk less frequently than we would
840 otherwise. This is useful when running on flash memory or other
841 media that support only a limited number of writes. (Default: 0)
842 CircuitPriorityHalflife NUM
844 If this value is set, we override the default algorithm for
845 choosing which circuit’s cell to deliver or relay next. It is
846 delivered first to the circuit that has the lowest weighted cell
847 count, where cells are weighted exponentially according to this
848 value (in seconds). If the value is -1, it is taken from the
849 consensus if possible else it will fallback to the default value of
850 30. Minimum: 1, Maximum: 2147483647. This can be defined as a float
851 value. This is an advanced option; you generally shouldn’t have to
852 mess with it. (Default: -1)
853 CountPrivateBandwidth 0|1
855 If this option is set, then Tor’s rate-limiting applies not only to
856 remote connections, but also to connections to private addresses
857 like 127.0.0.1 or 10.0.0.1. This is mostly useful for debugging
858 rate-limiting. (Default: 0)
859 ExtendByEd25519ID 0|1|auto
861 If this option is set to 1, we always try to include a relay’s
862 Ed25519 ID when telling the proceeding relay in a circuit to extend
863 to it. If this option is set to 0, we never include Ed25519 IDs
864 when extending circuits. If the option is set to "default", we obey
865 a parameter in the consensus document. (Default: auto)
866 NoExec 0|1
868 If this option is set to 1, then Tor will never launch another
869 executable, regardless of the settings of ClientTransportPlugin or
870 ServerTransportPlugin. Once this option has been set to 1, it
871 cannot be set back to 0 without restarting Tor. (Default: 0)
872 Schedulers KIST|KISTLite|Vanilla
874 Specify the scheduler type that tor should use. The scheduler is
875 responsible for moving data around within a Tor process. This is an
876 ordered list by priority which means that the first value will be
877 tried first and if unavailable, the second one is tried and so on.
878 It is possible to change these values at runtime. This option
879 mostly effects relays, and most operators should leave it set to
880 its default value. (Default: KIST,KISTLite,Vanilla)
881 The possible scheduler types are:
883 KIST: Kernel-Informed Socket Transport. Tor will use TCP
885 information from the kernel to make informed decisions regarding
886 how much data to send and when to send it. KIST also handles
887 traffic in batches (see KISTSchedRunInterval) in order to improve
888 traffic prioritization decisions. As implemented, KIST will only
889 work on Linux kernel version 2.6.39 or higher.
890 KISTLite: Same as KIST but without kernel support. Tor will use all
892 the same mechanics as with KIST, including the batching, but its
893 decisions regarding how much data to send will not be as good.
894 KISTLite will work on all kernels and operating systems, and the
895 majority of the benefits of KIST are still realized with KISTLite.
896 Vanilla: The scheduler that Tor used before KIST was implemented.
898 It sends as much data as possible, as soon as possible. Vanilla
899 will work on all kernels and operating systems.
900 KISTSchedRunInterval NUM msec
902 If KIST or KISTLite is used in the Schedulers option, this controls
903 at which interval the scheduler tick is. If the value is 0 msec,
904 the value is taken from the consensus if possible else it will
905 fallback to the default 10 msec. Maximum possible value is 100
906 msec. (Default: 0 msec)
907 KISTSockBufSizeFactor NUM
909 If KIST is used in Schedulers, this is a multiplier of the
910 per-socket limit calculation of the KIST algorithm. (Default: 1.0)
911
913 The following options are useful only for clients (that is, if
914 SocksPort, HTTPTunnelPort, TransPort, DNSPort, or NATDPort is
915 non-zero):
916 Bridge [transport] IP:ORPort [fingerprint]
918 When set along with UseBridges, instructs Tor to use the relay at
919 "IP:ORPort" as a "bridge" relaying into the Tor network. If
920 "fingerprint" is provided (using the same format as for
921 DirAuthority), we will verify that the relay running at that
922 location has the right fingerprint. We also use fingerprint to look
923 up the bridge descriptor at the bridge authority, if it’s provided
924 and if UpdateBridgesFromAuthority is set too.
925 If "transport" is provided, it must match a ClientTransportPlugin
928 line. We then use that pluggable transport’s proxy to transfer data
929 to the bridge, rather than connecting to the bridge directly. Some
930 transports use a transport-specific method to work out the remote
931 address to connect to. These transports typically ignore the
932 "IP:ORPort" specified in the bridge line.
933 Tor passes any "key=val" settings to the pluggable transport proxy
936 as per-connection arguments when connecting to the bridge. Consult
937 the documentation of the pluggable transport for details of what
938 arguments it supports.
939 LearnCircuitBuildTimeout 0|1
941 If 0, CircuitBuildTimeout adaptive learning is disabled. (Default:
942 1)
943 CircuitBuildTimeout NUM
945 Try for at most NUM seconds when building circuits. If the circuit
946 isn’t open in that time, give up on it. If LearnCircuitBuildTimeout
947 is 1, this value serves as the initial value to use before a
948 timeout is learned. If LearnCircuitBuildTimeout is 0, this value is
949 the only value used. (Default: 60 seconds)
950 CircuitsAvailableTimeout NUM
952 Tor will attempt to keep at least one open, unused circuit
953 available for this amount of time. This option governs how long
954 idle circuits are kept open, as well as the amount of time Tor will
955 keep a circuit open to each of the recently used ports. This way
956 when the Tor client is entirely idle, it can expire all of its
957 circuits, and then expire its TLS connections. Note that the actual
958 timeout value is uniformly randomized from the specified value to
959 twice that amount. (Default: 30 minutes; Max: 24 hours)
960 CircuitStreamTimeout NUM
962 If non-zero, this option overrides our internal timeout schedule
963 for how many seconds until we detach a stream from a circuit and
964 try a new circuit. If your network is particularly slow, you might
965 want to set this to a number like 60. (Default: 0)
966 ClientOnly 0|1
968 If set to 1, Tor will not run as a relay or serve directory
969 requests, even if the ORPort, ExtORPort, or DirPort options are
970 set. (This config option is mostly unnecessary: we added it back
971 when we were considering having Tor clients auto-promote themselves
972 to being relays if they were stable and fast enough. The current
973 behavior is simply that Tor is a client unless ORPort, ExtORPort,
974 or DirPort are configured.) (Default: 0)
975 ConnectionPadding 0|1|auto
977 This option governs Tor’s use of padding to defend against some
978 forms of traffic analysis. If it is set to auto, Tor will send
979 padding only if both the client and the relay support it. If it is
980 set to 0, Tor will not send any padding cells. If it is set to 1,
981 Tor will still send padding for client connections regardless of
982 relay support. Only clients may set this option. This option should
983 be offered via the UI to mobile users for use where bandwidth may
984 be expensive. (Default: auto)
985 ReducedConnectionPadding 0|1
987 If set to 1, Tor will not not hold OR connections open for very
988 long, and will send less padding on these connections. Only clients
989 may set this option. This option should be offered via the UI to
990 mobile users for use where bandwidth may be expensive. (Default: 0)
991 ExcludeNodes node,node,...
993 A list of identity fingerprints, country codes, and address
994 patterns of nodes to avoid when building a circuit. Country codes
995 are 2-letter ISO3166 codes, and must be wrapped in braces;
996 fingerprints may be preceded by a dollar sign. (Example:
997 ExcludeNodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, {cc},
998 255.254.0.0/8)
999 By default, this option is treated as a preference that Tor is
1002 allowed to override in order to keep working. For example, if you
1003 try to connect to a hidden service, but you have excluded all of
1004 the hidden service’s introduction points, Tor will connect to one
1005 of them anyway. If you do not want this behavior, set the
1006 StrictNodes option (documented below).
1007 Note also that if you are a relay, this (and the other node
1010 selection options below) only affects your own circuits that Tor
1011 builds for you. Clients can still build circuits through you to any
1012 node. Controllers can tell Tor to build circuits through any node.
1013 Country codes are case-insensitive. The code "{??}" refers to nodes
1016 whose country can’t be identified. No country code, including {??},
1017 works if no GeoIPFile can be loaded. See also the
1018 GeoIPExcludeUnknown option below.
1019 ExcludeExitNodes node,node,...
1021 A list of identity fingerprints, country codes, and address
1022 patterns of nodes to never use when picking an exit node---that is,
1023 a node that delivers traffic for you outside the Tor network. Note
1024 that any node listed in ExcludeNodes is automatically considered to
1025 be part of this list too. See the ExcludeNodes option for more
1026 information on how to specify nodes. See also the caveats on the
1027 "ExitNodes" option below.
1028 GeoIPExcludeUnknown 0|1|auto
1030 If this option is set to auto, then whenever any country code is
1031 set in ExcludeNodes or ExcludeExitNodes, all nodes with unknown
1032 country ({??} and possibly {A1}) are treated as excluded as well.
1033 If this option is set to 1, then all unknown countries are treated
1034 as excluded in ExcludeNodes and ExcludeExitNodes. This option has
1035 no effect when a GeoIP file isn’t configured or can’t be found.
1036 (Default: auto)
1037 ExitNodes node,node,...
1039 A list of identity fingerprints, country codes, and address
1040 patterns of nodes to use as exit node---that is, a node that
1041 delivers traffic for you outside the Tor network. See the
1042 ExcludeNodes option for more information on how to specify nodes.
1043 Note that if you list too few nodes here, or if you exclude too
1046 many exit nodes with ExcludeExitNodes, you can degrade
1047 functionality. For example, if none of the exits you list allows
1048 traffic on port 80 or 443, you won’t be able to browse the web.
1049 Note also that not every circuit is used to deliver traffic outside
1052 of the Tor network. It is normal to see non-exit circuits (such as
1053 those used to connect to hidden services, those that do directory
1054 fetches, those used for relay reachability self-tests, and so on)
1055 that end at a non-exit node. To keep a node from being used
1056 entirely, see ExcludeNodes and StrictNodes.
1057 The ExcludeNodes option overrides this option: any node listed in
1060 both ExitNodes and ExcludeNodes is treated as excluded.
1061 The .exit address notation, if enabled via MapAddress, overrides
1064 this option.
1065 EntryNodes node,node,...
1067 A list of identity fingerprints and country codes of nodes to use
1068 for the first hop in your normal circuits. Normal circuits include
1069 all circuits except for direct connections to directory servers.
1070 The Bridge option overrides this option; if you have configured
1071 bridges and UseBridges is 1, the Bridges are used as your entry
1072 nodes.
1073 The ExcludeNodes option overrides this option: any node listed in
1076 both EntryNodes and ExcludeNodes is treated as excluded. See the
1077 ExcludeNodes option for more information on how to specify nodes.
1078 StrictNodes 0|1
1080 If StrictNodes is set to 1, Tor will treat solely the ExcludeNodes
1081 option as a requirement to follow for all the circuits you
1082 generate, even if doing so will break functionality for you
1083 (StrictNodes applies to neither ExcludeExitNodes nor to ExitNodes).
1084 If StrictNodes is set to 0, Tor will still try to avoid nodes in
1085 the ExcludeNodes list, but it will err on the side of avoiding
1086 unexpected errors. Specifically, StrictNodes 0 tells Tor that it is
1087 okay to use an excluded node when it is necessary to perform relay
1088 reachability self-tests, connect to a hidden service, provide a
1089 hidden service to a client, fulfill a .exit request, upload
1090 directory information, or download directory information. (Default:
1091 0)
1092 FascistFirewall 0|1
1094 If 1, Tor will only create outgoing connections to ORs running on
1095 ports that your firewall allows (defaults to 80 and 443; see
1096 FirewallPorts). This will allow you to run Tor as a client behind a
1097 firewall with restrictive policies, but will not allow you to run
1098 as a server behind such a firewall. If you prefer more fine-grained
1099 control, use ReachableAddresses instead.
1100 FirewallPorts PORTS
1102 A list of ports that your firewall allows you to connect to. Only
1103 used when FascistFirewall is set. This option is deprecated; use
1104 ReachableAddresses instead. (Default: 80, 443)
1105 ReachableAddresses IP[/MASK][:PORT]...
1107 A comma-separated list of IP addresses and ports that your firewall
1108 allows you to connect to. The format is as for the addresses in
1109 ExitPolicy, except that "accept" is understood unless "reject" is
1110 explicitly provided. For example, 'ReachableAddresses 99.0.0.0/8,
1111 reject 18.0.0.0/8:80, accept *:80' means that your firewall allows
1112 connections to everything inside net 99, rejects port 80
1113 connections to net 18, and accepts connections to port 80
1114 otherwise. (Default: 'accept *:*'.)
1115 ReachableDirAddresses IP[/MASK][:PORT]...
1117 Like ReachableAddresses, a list of addresses and ports. Tor will
1118 obey these restrictions when fetching directory information, using
1119 standard HTTP GET requests. If not set explicitly then the value of
1120 ReachableAddresses is used. If HTTPProxy is set then these
1121 connections will go through that proxy. (DEPRECATED: This option
1122 has had no effect for some time.)
1123 ReachableORAddresses IP[/MASK][:PORT]...
1125 Like ReachableAddresses, a list of addresses and ports. Tor will
1126 obey these restrictions when connecting to Onion Routers, using
1127 TLS/SSL. If not set explicitly then the value of ReachableAddresses
1128 is used. If HTTPSProxy is set then these connections will go
1129 through that proxy.
1130 The separation between ReachableORAddresses and
1133 ReachableDirAddresses is only interesting when you are connecting
1134 through proxies (see HTTPProxy and HTTPSProxy). Most proxies limit
1135 TLS connections (which Tor uses to connect to Onion Routers) to
1136 port 443, and some limit HTTP GET requests (which Tor uses for
1137 fetching directory information) to port 80.
1138 HidServAuth onion-address auth-cookie [service-name]
1140 Client authorization for a hidden service. Valid onion addresses
1141 contain 16 characters in a-z2-7 plus ".onion", and valid auth
1142 cookies contain 22 characters in A-Za-z0-9+/. The service name is
1143 only used for internal purposes, e.g., for Tor controllers. This
1144 option may be used multiple times for different hidden services. If
1145 a hidden service uses authorization and this option is not set, the
1146 hidden service is not accessible. Hidden services can be configured
1147 to require authorization using the HiddenServiceAuthorizeClient
1148 option.
1149 ClientOnionAuthDir path
1151 Path to the directory containing v3 hidden service authorization
1152 files. Each file is for a single onion address, and the files MUST
1153 have the suffix ".auth_private" (i.e. "bob_onion.auth_private").
1154 The content format MUST be:
1155 <onion-address>:descriptor:x25519:<base32-encoded-privkey>
1157 The <onion-address> MUST NOT have the ".onion" suffix. The
1159 <base32-encoded-privkey> is the base32 representation of the raw
1160 key bytes only (32 bytes for x25519). See Appendix G in the
1161 rend-spec-v3.txt file of torspec for more information.
1162 LongLivedPorts PORTS
1164 A list of ports for services that tend to have long-running
1165 connections (e.g. chat and interactive shells). Circuits for
1166 streams that use these ports will contain only high-uptime nodes,
1167 to reduce the chance that a node will go down before the stream is
1168 finished. Note that the list is also honored for circuits (both
1169 client and service side) involving hidden services whose virtual
1170 port is in this list. (Default: 21, 22, 706, 1863, 5050, 5190,
1171 5222, 5223, 6523, 6667, 6697, 8300)
1172 MapAddress address newaddress
1174 When a request for address arrives to Tor, it will transform to
1175 newaddress before processing it. For example, if you always want
1176 connections to www.example.com to exit via torserver (where
1177 torserver is the fingerprint of the server), use "MapAddress
1178 www.example.com www.example.com.torserver.exit". If the value is
1179 prefixed with a "*.", matches an entire domain. For example, if you
1180 always want connections to example.com and any if its subdomains to
1181 exit via torserver (where torserver is the fingerprint of the
1182 server), use "MapAddress *.example.com
1183 *.example.com.torserver.exit". (Note the leading "*." in each part
1184 of the directive.) You can also redirect all subdomains of a domain
1185 to a single address. For example, "MapAddress *.example.com
1186 www.example.com".
1187 NOTES:
1190 1. When evaluating MapAddress expressions Tor stops when it hits
1192 the most recently added expression that matches the requested
1193 address. So if you have the following in your torrc,
1194 www.torproject.org will map to 1.1.1.1:
1195 MapAddress www.torproject.org 2.2.2.2
1197 MapAddress www.torproject.org 1.1.1.1
1198 2. Tor evaluates the MapAddress configuration until it finds no
1200 matches. So if you have the following in your torrc,
1201 www.torproject.org will map to 2.2.2.2:
1202 MapAddress 1.1.1.1 2.2.2.2
1204 MapAddress www.torproject.org 1.1.1.1
1205 3. The following MapAddress expression is invalid (and will be
1207 ignored) because you cannot map from a specific address to a
1208 wildcard address:
1209 MapAddress www.torproject.org *.torproject.org.torserver.exit
1211 4. Using a wildcard to match only part of a string (as in
1213 *ample.com) is also invalid.
1214 NewCircuitPeriod NUM
1216 Every NUM seconds consider whether to build a new circuit.
1217 (Default: 30 seconds)
1218 MaxCircuitDirtiness NUM
1220 Feel free to reuse a circuit that was first used at most NUM
1221 seconds ago, but never attach a new stream to a circuit that is too
1222 old. For hidden services, this applies to the last time a circuit
1223 was used, not the first. Circuits with streams constructed with
1224 SOCKS authentication via SocksPorts that have
1225 KeepAliveIsolateSOCKSAuth also remain alive for MaxCircuitDirtiness
1226 seconds after carrying the last such stream. (Default: 10 minutes)
1227 MaxClientCircuitsPending NUM
1229 Do not allow more than NUM circuits to be pending at a time for
1230 handling client streams. A circuit is pending if we have begun
1231 constructing it, but it has not yet been completely constructed.
1232 (Default: 32)
1233 NodeFamily node,node,...
1235 The Tor servers, defined by their identity fingerprints, constitute
1236 a "family" of similar or co-administered servers, so never use any
1237 two of them in the same circuit. Defining a NodeFamily is only
1238 needed when a server doesn’t list the family itself (with
1239 MyFamily). This option can be used multiple times; each instance
1240 defines a separate family. In addition to nodes, you can also list
1241 IP address and ranges and country codes in {curly braces}. See the
1242 ExcludeNodes option for more information on how to specify nodes.
1243 EnforceDistinctSubnets 0|1
1245 If 1, Tor will not put two servers whose IP addresses are "too
1246 close" on the same circuit. Currently, two addresses are "too
1247 close" if they lie in the same /16 range. (Default: 1)
1248 SocksPort [address:]port|unix:path|auto [flags] [isolation flags]
1250 Open this port to listen for connections from SOCKS-speaking
1251 applications. Set this to 0 if you don’t want to allow application
1252 connections via SOCKS. Set it to "auto" to have Tor pick a port for
1253 you. This directive can be specified multiple times to bind to
1254 multiple addresses/ports. If a unix domain socket is used, you may
1255 quote the path using standard C escape sequences. (Default: 9050)
1256 NOTE: Although this option allows you to specify an IP address
1259 other than localhost, you should do so only with extreme caution.
1260 The SOCKS protocol is unencrypted and (as we use it)
1261 unauthenticated, so exposing it in this way could leak your
1262 information to anybody watching your network, and allow anybody to
1263 use your computer as an open proxy.
1264 The isolation flags arguments give Tor rules for which streams
1267 received on this SocksPort are allowed to share circuits with one
1268 another. Recognized isolation flags are:
1269 IsolateClientAddr
1271 Don’t share circuits with streams from a different client
1272 address. (On by default and strongly recommended when
1273 supported; you can disable it with NoIsolateClientAddr.
1274 Unsupported and force-disabled when using Unix domain sockets.)
1275 IsolateSOCKSAuth
1277 Don’t share circuits with streams for which different SOCKS
1278 authentication was provided. (For HTTPTunnelPort connections,
1279 this option looks at the Proxy-Authorization and
1280 X-Tor-Stream-Isolation headers. On by default; you can disable
1281 it with NoIsolateSOCKSAuth.)
1282 IsolateClientProtocol
1284 Don’t share circuits with streams using a different protocol.
1285 (SOCKS 4, SOCKS 5, TransPort connections, NATDPort connections,
1286 and DNSPort requests are all considered to be different
1287 protocols.)
1288 IsolateDestPort
1290 Don’t share circuits with streams targeting a different
1291 destination port.
1292 IsolateDestAddr
1294 Don’t share circuits with streams targeting a different
1295 destination address.
1296 KeepAliveIsolateSOCKSAuth
1298 If IsolateSOCKSAuth is enabled, keep alive circuits while they
1299 have at least one stream with SOCKS authentication active.
1300 After such a circuit is idle for more than MaxCircuitDirtiness
1301 seconds, it can be closed.
1302 SessionGroup=INT
1304 If no other isolation rules would prevent it, allow streams on
1305 this port to share circuits with streams from every other port
1306 with the same session group. (By default, streams received on
1307 different SocksPorts, TransPorts, etc are always isolated from
1308 one another. This option overrides that behavior.)
1309 Other recognized flags for a SocksPort are:
1311 NoIPv4Traffic
1313 Tell exits to not connect to IPv4 addresses in response to
1314 SOCKS requests on this connection.
1315 IPv6Traffic
1317 Tell exits to allow IPv6 addresses in response to SOCKS
1318 requests on this connection, so long as SOCKS5 is in use.
1319 (SOCKS4 can’t handle IPv6.)
1320 PreferIPv6
1322 Tells exits that, if a host has both an IPv4 and an IPv6
1323 address, we would prefer to connect to it via IPv6. (IPv4 is
1324 the default.)
1325 NoDNSRequest
1327 Do not ask exits to resolve DNS addresses in SOCKS5 requests.
1328 Tor will connect to IPv4 addresses, IPv6 addresses (if
1329 IPv6Traffic is set) and .onion addresses.
1330 NoOnionTraffic
1332 Do not connect to .onion addresses in SOCKS5 requests.
1333 OnionTrafficOnly
1335 Tell the tor client to only connect to .onion addresses in
1336 response to SOCKS5 requests on this connection. This is
1337 equivalent to NoDNSRequest, NoIPv4Traffic, NoIPv6Traffic. The
1338 corresponding NoOnionTrafficOnly flag is not supported.
1339 CacheIPv4DNS
1341 Tells the client to remember IPv4 DNS answers we receive from
1342 exit nodes via this connection.
1343 CacheIPv6DNS
1345 Tells the client to remember IPv6 DNS answers we receive from
1346 exit nodes via this connection.
1347 GroupWritable
1349 Unix domain sockets only: makes the socket get created as
1350 group-writable.
1351 WorldWritable
1353 Unix domain sockets only: makes the socket get created as
1354 world-writable.
1355 CacheDNS
1357 Tells the client to remember all DNS answers we receive from
1358 exit nodes via this connection.
1359 UseIPv4Cache
1361 Tells the client to use any cached IPv4 DNS answers we have
1362 when making requests via this connection. (NOTE: This option,
1363 or UseIPv6Cache or UseDNSCache, can harm your anonymity, and
1364 probably won’t help performance as much as you might expect.
1365 Use with care!)
1366 UseIPv6Cache
1368 Tells the client to use any cached IPv6 DNS answers we have
1369 when making requests via this connection.
1370 UseDNSCache
1372 Tells the client to use any cached DNS answers we have when
1373 making requests via this connection.
1374 PreferIPv6Automap
1376 When serving a hostname lookup request on this port that should
1377 get automapped (according to AutomapHostsOnResolve), if we
1378 could return either an IPv4 or an IPv6 answer, prefer an IPv6
1379 answer. (On by default.)
1380 PreferSOCKSNoAuth
1382 Ordinarily, when an application offers both "username/password
1383 authentication" and "no authentication" to Tor via SOCKS5, Tor
1384 selects username/password authentication so that
1385 IsolateSOCKSAuth can work. This can confuse some applications,
1386 if they offer a username/password combination then get confused
1387 when asked for one. You can disable this behavior, so that Tor
1388 will select "No authentication" when IsolateSOCKSAuth is
1389 disabled, or when this option is set.
1390 Flags are processed left to right. If flags conflict, the last flag
1392 on the line is used, and all earlier flags are ignored. No error is
1393 issued for conflicting flags.
1394 SocksPolicy policy,policy,...
1396 Set an entrance policy for this server, to limit who can connect to
1397 the SocksPort and DNSPort ports. The policies have the same form as
1398 exit policies below, except that port specifiers are ignored. Any
1399 address not matched by some entry in the policy is accepted.
1400 SocksTimeout NUM
1402 Let a socks connection wait NUM seconds handshaking, and NUM
1403 seconds unattached waiting for an appropriate circuit, before we
1404 fail it. (Default: 2 minutes)
1405 TokenBucketRefillInterval NUM [msec|second]
1407 Set the refill delay interval of Tor’s token bucket to NUM
1408 milliseconds. NUM must be between 1 and 1000, inclusive. When Tor
1409 is out of bandwidth, on a connection or globally, it will wait up
1410 to this long before it tries to use that connection again. Note
1411 that bandwidth limits are still expressed in bytes per second: this
1412 option only affects the frequency with which Tor checks to see
1413 whether previously exhausted connections may read again. Can not be
1414 changed while tor is running. (Default: 100 msec)
1415 TrackHostExits host,.domain,...
1417 For each value in the comma separated list, Tor will track recent
1418 connections to hosts that match this value and attempt to reuse the
1419 same exit node for each. If the value is prepended with a '.', it
1420 is treated as matching an entire domain. If one of the values is
1421 just a '.', it means match everything. This option is useful if you
1422 frequently connect to sites that will expire all your
1423 authentication cookies (i.e. log you out) if your IP address
1424 changes. Note that this option does have the disadvantage of making
1425 it more clear that a given history is associated with a single
1426 user. However, most people who would wish to observe this will
1427 observe it through cookies or other protocol-specific means anyhow.
1428 TrackHostExitsExpire NUM
1430 Since exit servers go up and down, it is desirable to expire the
1431 association between host and exit server after NUM seconds. The
1432 default is 1800 seconds (30 minutes).
1433 UpdateBridgesFromAuthority 0|1
1435 When set (along with UseBridges), Tor will try to fetch bridge
1436 descriptors from the configured bridge authorities when feasible.
1437 It will fall back to a direct request if the authority responds
1438 with a 404. (Default: 0)
1439 UseBridges 0|1
1441 When set, Tor will fetch descriptors for each bridge listed in the
1442 "Bridge" config lines, and use these relays as both entry guards
1443 and directory guards. (Default: 0)
1444 UseEntryGuards 0|1
1446 If this option is set to 1, we pick a few long-term entry servers,
1447 and try to stick with them. This is desirable because constantly
1448 changing servers increases the odds that an adversary who owns some
1449 servers will observe a fraction of your paths. Entry Guards can not
1450 be used by Directory Authorities or Single Onion Services. In these
1451 cases, this option is ignored. (Default: 1)
1452 GuardfractionFile FILENAME
1454 V3 authoritative directories only. Configures the location of the
1455 guardfraction file which contains information about how long relays
1456 have been guards. (Default: unset)
1457 UseGuardFraction 0|1|auto
1459 This option specifies whether clients should use the guardfraction
1460 information found in the consensus during path selection. If it’s
1461 set to auto, clients will do what the UseGuardFraction consensus
1462 parameter tells them to do. (Default: auto)
1463 NumEntryGuards NUM
1465 If UseEntryGuards is set to 1, we will try to pick a total of NUM
1466 routers as long-term entries for our circuits. If NUM is 0, we try
1467 to learn the number from the guard-n-primary-guards-to-use
1468 consensus parameter, and default to 1 if the consensus parameter
1469 isn’t set. (Default: 0)
1470 NumPrimaryGuards NUM
1472 If UseEntryGuards is set to 1, we will try to pick NUM routers for
1473 our primary guard list, which is the set of routers we strongly
1474 prefer when connecting to the Tor network. If NUM is 0, we try to
1475 learn the number from the guard-n-primary-guards consensus
1476 parameter, and default to 3 if the consensus parameter isn’t set.
1477 (Default: 0)
1478 NumDirectoryGuards NUM
1480 If UseEntryGuards is set to 1, we try to make sure we have at least
1481 NUM routers to use as directory guards. If this option is set to 0,
1482 use the value from the guard-n-primary-dir-guards-to-use consensus
1483 parameter, and default to 3 if the consensus parameter isn’t set.
1484 (Default: 0)
1485 GuardLifetime N days|weeks|months
1487 If nonzero, and UseEntryGuards is set, minimum time to keep a guard
1488 before picking a new one. If zero, we use the GuardLifetime
1489 parameter from the consensus directory. No value here may be less
1490 than 1 month or greater than 5 years; out-of-range values are
1491 clamped. (Default: 0)
1492 SafeSocks 0|1
1494 When this option is enabled, Tor will reject application
1495 connections that use unsafe variants of the socks protocol — ones
1496 that only provide an IP address, meaning the application is doing a
1497 DNS resolve first. Specifically, these are socks4 and socks5 when
1498 not doing remote DNS. (Default: 0)
1499 TestSocks 0|1
1501 When this option is enabled, Tor will make a notice-level log entry
1502 for each connection to the Socks port indicating whether the
1503 request used a safe socks protocol or an unsafe one (see above
1504 entry on SafeSocks). This helps to determine whether an application
1505 using Tor is possibly leaking DNS requests. (Default: 0)
1506 VirtualAddrNetworkIPv4 IPv4Address/bits
1508 VirtualAddrNetworkIPv6 [IPv6Address]/bits
1510 When Tor needs to assign a virtual (unused) address because of a
1511 MAPADDRESS command from the controller or the AutomapHostsOnResolve
1512 feature, Tor picks an unassigned address from this range.
1513 (Defaults: 127.192.0.0/10 and [FE80::]/10 respectively.)
1514 When providing proxy server service to a network of computers using
1517 a tool like dns-proxy-tor, change the IPv4 network to
1518 "10.192.0.0/10" or "172.16.0.0/12" and change the IPv6 network to
1519 "[FC00::]/7". The default VirtualAddrNetwork address ranges on a
1520 properly configured machine will route to the loopback or
1521 link-local interface. The maximum number of bits for the network
1522 prefix is set to 104 for IPv6 and 16 for IPv4. However, a wider
1523 network - smaller prefix length
1524 · is preferable since it reduces the chances for an attacker to
1526 guess the used IP. For local use, no change to the default
1527 VirtualAddrNetwork setting is needed.
1528 AllowNonRFC953Hostnames 0|1
1530 When this option is disabled, Tor blocks hostnames containing
1531 illegal characters (like @ and :) rather than sending them to an
1532 exit node to be resolved. This helps trap accidental attempts to
1533 resolve URLs and so on. (Default: 0)
1534 HTTPTunnelPort [address:]port|auto [isolation flags]
1536 Open this port to listen for proxy connections using the "HTTP
1537 CONNECT" protocol instead of SOCKS. Set this to 0 if you don’t want
1538 to allow "HTTP CONNECT" connections. Set the port to "auto" to have
1539 Tor pick a port for you. This directive can be specified multiple
1540 times to bind to multiple addresses/ports. See SOCKSPort for an
1541 explanation of isolation flags. (Default: 0)
1542 TransPort [address:]port|auto [isolation flags]
1544 Open this port to listen for transparent proxy connections. Set
1545 this to 0 if you don’t want to allow transparent proxy connections.
1546 Set the port to "auto" to have Tor pick a port for you. This
1547 directive can be specified multiple times to bind to multiple
1548 addresses/ports. See SOCKSPort for an explanation of isolation
1549 flags.
1550 TransPort requires OS support for transparent proxies, such as
1553 BSDs' pf or Linux’s IPTables. If you’re planning to use Tor as a
1554 transparent proxy for a network, you’ll want to examine and change
1555 VirtualAddrNetwork from the default setting. (Default: 0)
1556 TransProxyType default|TPROXY|ipfw|pf-divert
1558 TransProxyType may only be enabled when there is transparent proxy
1559 listener enabled.
1560 Set this to "TPROXY" if you wish to be able to use the TPROXY Linux
1563 module to transparently proxy connections that are configured using
1564 the TransPort option. Detailed information on how to configure the
1565 TPROXY feature can be found in the Linux kernel source tree in the
1566 file Documentation/networking/tproxy.txt.
1567 Set this option to "ipfw" to use the FreeBSD ipfw interface.
1570 On *BSD operating systems when using pf, set this to "pf-divert" to
1573 take advantage of divert-to rules, which do not modify the packets
1574 like rdr-to rules do. Detailed information on how to configure pf
1575 to use divert-to rules can be found in the pf.conf(5) manual page.
1576 On OpenBSD, divert-to is available to use on versions greater than
1577 or equal to OpenBSD 4.4.
1578 Set this to "default", or leave it unconfigured, to use regular
1581 IPTables on Linux, or to use pf rdr-to rules on *BSD systems.
1582 (Default: "default")
1585 NATDPort [address:]port|auto [isolation flags]
1587 Open this port to listen for connections from old versions of ipfw
1588 (as included in old versions of FreeBSD, etc) using the NATD
1589 protocol. Use 0 if you don’t want to allow NATD connections. Set
1590 the port to "auto" to have Tor pick a port for you. This directive
1591 can be specified multiple times to bind to multiple
1592 addresses/ports. See SocksPort for an explanation of isolation
1593 flags.
1594 This option is only for people who cannot use TransPort. (Default:
1597 0)
1598 AutomapHostsOnResolve 0|1
1600 When this option is enabled, and we get a request to resolve an
1601 address that ends with one of the suffixes in AutomapHostsSuffixes,
1602 we map an unused virtual address to that address, and return the
1603 new virtual address. This is handy for making ".onion" addresses
1604 work with applications that resolve an address and then connect to
1605 it. (Default: 0)
1606 AutomapHostsSuffixes SUFFIX,SUFFIX,...
1608 A comma-separated list of suffixes to use with
1609 AutomapHostsOnResolve. The "." suffix is equivalent to "all
1610 addresses." (Default: .exit,.onion).
1611 DNSPort [address:]port|auto [isolation flags]
1613 If non-zero, open this port to listen for UDP DNS requests, and
1614 resolve them anonymously. This port only handles A, AAAA, and PTR
1615 requests---it doesn’t handle arbitrary DNS request types. Set the
1616 port to "auto" to have Tor pick a port for you. This directive can
1617 be specified multiple times to bind to multiple addresses/ports.
1618 See SocksPort for an explanation of isolation flags. (Default: 0)
1619 ClientDNSRejectInternalAddresses 0|1
1621 If true, Tor does not believe any anonymously retrieved DNS answer
1622 that tells it that an address resolves to an internal address (like
1623 127.0.0.1 or 192.168.0.1). This option prevents certain
1624 browser-based attacks; it is not allowed to be set on the default
1625 network. (Default: 1)
1626 ClientRejectInternalAddresses 0|1
1628 If true, Tor does not try to fulfill requests to connect to an
1629 internal address (like 127.0.0.1 or 192.168.0.1) unless an exit
1630 node is specifically requested (for example, via a .exit hostname,
1631 or a controller request). If true, multicast DNS hostnames for
1632 machines on the local network (of the form *.local) are also
1633 rejected. (Default: 1)
1634 DownloadExtraInfo 0|1
1636 If true, Tor downloads and caches "extra-info" documents. These
1637 documents contain information about servers other than the
1638 information in their regular server descriptors. Tor does not use
1639 this information for anything itself; to save bandwidth, leave this
1640 option turned off. (Default: 0)
1641 WarnPlaintextPorts port,port,...
1643 Tells Tor to issue a warnings whenever the user tries to make an
1644 anonymous connection to one of these ports. This option is designed
1645 to alert users to services that risk sending passwords in the
1646 clear. (Default: 23,109,110,143)
1647 RejectPlaintextPorts port,port,...
1649 Like WarnPlaintextPorts, but instead of warning about risky port
1650 uses, Tor will instead refuse to make the connection. (Default:
1651 None)
1652 OptimisticData 0|1|auto
1654 When this option is set, and Tor is using an exit node that
1655 supports the feature, it will try optimistically to send data to
1656 the exit node without waiting for the exit node to report whether
1657 the connection succeeded. This can save a round-trip time for
1658 protocols like HTTP where the client talks first. If OptimisticData
1659 is set to auto, Tor will look at the UseOptimisticData parameter in
1660 the networkstatus. (Default: auto)
1661 HSLayer2Nodes node,node,...
1663 A list of identity fingerprints, nicknames, country codes, and
1664 address patterns of nodes that are allowed to be used as the second
1665 hop in all client or service-side Onion Service circuits. This
1666 option mitigates attacks where the adversary runs middle nodes and
1667 induces your client or service to create many circuits, in order to
1668 discover your primary guard node. (Default: Any node in the network
1669 may be used in the second hop.)
1670 (Example: HSLayer2Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234,
1672 {cc}, 255.254.0.0/8)
1673 When this is set, the resulting hidden service paths will look
1676 like:
1677 C - G - L2 - M - Rend
1679 C - G - L2 - M - HSDir
1681 C - G - L2 - M - Intro
1683 S - G - L2 - M - Rend
1685 S - G - L2 - M - HSDir
1687 S - G - L2 - M - Intro
1689 where C is this client, S is the service, G is the Guard node, L2
1692 is a node from this option, and M is a random middle node. Rend,
1693 HSDir, and Intro point selection is not affected by this option.
1694 This option may be combined with HSLayer3Nodes to create paths of
1696 the form:
1697 C - G - L2 - L3 - Rend
1699 C - G - L2 - L3 - M - HSDir
1701 C - G - L2 - L3 - M - Intro
1703 S - G - L2 - L3 - M - Rend
1705 S - G - L2 - L3 - HSDir
1707 S - G - L2 - L3 - Intro
1709 ExcludeNodes have higher priority than HSLayer2Nodes, which means
1712 that nodes specified in ExcludeNodes will not be picked.
1713 When either this option or HSLayer3Nodes are set, the /16 subnet
1715 and node family restrictions are removed for hidden service
1716 circuits. Additionally, we allow the guard node to be present as
1717 the Rend, HSDir, and IP node, and as the hop before it. This is
1718 done to prevent the adversary from inferring information about our
1719 guard, layer2, and layer3 node choices at later points in the path.
1720 This option is meant to be managed by a Tor controller such as
1722 https://github.com/mikeperry-tor/vanguards that selects and updates
1723 this set of nodes for you. Hence it does not do load balancing if
1724 fewer than 20 nodes are selected, and if no nodes in HSLayer2Nodes
1725 are currently available for use, Tor will not work. Please use
1726 extreme care if you are setting this option manually.
1727 HSLayer3Nodes node,node,...
1729 A list of identity fingerprints, nicknames, country codes, and
1730 address patterns of nodes that are allowed to be used as the third
1731 hop in all client and service-side Onion Service circuits. This
1732 option mitigates attacks where the adversary runs middle nodes and
1733 induces your client or service to create many circuits, in order to
1734 discover your primary or Layer2 guard nodes. (Default: Any node in
1735 the network may be used in the third hop.)
1736 (Example: HSLayer3Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234,
1738 {cc}, 255.254.0.0/8)
1739 When this is set by itself, the resulting hidden service paths will
1742 look like:
1743 C - G - M - L3 - Rend
1745 C - G - M - L3 - M - HSDir
1747 C - G - M - L3 - M - Intro
1749 S - G - M - L3 - M - Rend
1751 S - G - M - L3 - HSDir
1753 S - G - M - L3 - Intro
1755 where C is this client, S is the service, G is the Guard node, L2
1757 is a node from this option, and M is a random middle node. Rend,
1758 HSDir, and Intro point selection is not affected by this option.
1759 While it is possible to use this option by itself, it should be
1761 combined with HSLayer2Nodes to create paths of the form:
1762 C - G - L2 - L3 - Rend
1764 C - G - L2 - L3 - M - HSDir
1766 C - G - L2 - L3 - M - Intro
1768 S - G - L2 - L3 - M - Rend
1770 S - G - L2 - L3 - HSDir
1772 S - G - L2 - L3 - Intro
1774 ExcludeNodes have higher priority than HSLayer3Nodes, which means
1777 that nodes specified in ExcludeNodes will not be picked.
1778 When either this option or HSLayer2Nodes are set, the /16 subnet
1780 and node family restrictions are removed for hidden service
1781 circuits. Additionally, we allow the guard node to be present as
1782 the Rend, HSDir, and IP node, and as the hop before it. This is
1783 done to prevent the adversary from inferring information about our
1784 guard, layer2, and layer3 node choices at later points in the path.
1785 This option is meant to be managed by a Tor controller such as
1787 https://github.com/mikeperry-tor/vanguards that selects and updates
1788 this set of nodes for you. Hence it does not do load balancing if
1789 fewer than 20 nodes are selected, and if no nodes in HSLayer3Nodes
1790 are currently available for use, Tor will not work. Please use
1791 extreme care if you are setting this option manually.
1792 UseMicrodescriptors 0|1|auto
1794 Microdescriptors are a smaller version of the information that Tor
1795 needs in order to build its circuits. Using microdescriptors makes
1796 Tor clients download less directory information, thus saving
1797 bandwidth. Directory caches need to fetch regular descriptors and
1798 microdescriptors, so this option doesn’t save any bandwidth for
1799 them. For legacy reasons, auto is accepted, but it has the same
1800 effect as 1. (Default: auto)
1801 PathBiasCircThreshold NUM
1803 PathBiasNoticeRate NUM
1805 PathBiasWarnRate NUM
1807 PathBiasExtremeRate NUM
1809 PathBiasDropGuards NUM
1811 PathBiasScaleThreshold NUM
1813 These options override the default behavior of Tor’s (currently
1814 experimental) path bias detection algorithm. To try to find broken
1815 or misbehaving guard nodes, Tor looks for nodes where more than a
1816 certain fraction of circuits through that guard fail to get built.
1817 The PathBiasCircThreshold option controls how many circuits we need
1820 to build through a guard before we make these checks. The
1821 PathBiasNoticeRate, PathBiasWarnRate and PathBiasExtremeRate
1822 options control what fraction of circuits must succeed through a
1823 guard so we won’t write log messages. If less than
1824 PathBiasExtremeRate circuits succeed and PathBiasDropGuards is set
1825 to 1, we disable use of that guard.
1826 When we have seen more than PathBiasScaleThreshold circuits through
1829 a guard, we scale our observations by 0.5 (governed by the
1830 consensus) so that new observations don’t get swamped by old ones.
1831 By default, or if a negative value is provided for one of these
1834 options, Tor uses reasonable defaults from the networkstatus
1835 consensus document. If no defaults are available there, these
1836 options default to 150, .70, .50, .30, 0, and 300 respectively.
1837 PathBiasUseThreshold NUM
1839 PathBiasNoticeUseRate NUM
1841 PathBiasExtremeUseRate NUM
1843 PathBiasScaleUseThreshold NUM
1845 Similar to the above options, these options override the default
1846 behavior of Tor’s (currently experimental) path use bias detection
1847 algorithm.
1848 Where as the path bias parameters govern thresholds for
1851 successfully building circuits, these four path use bias parameters
1852 govern thresholds only for circuit usage. Circuits which receive no
1853 stream usage are not counted by this detection algorithm. A used
1854 circuit is considered successful if it is capable of carrying
1855 streams or otherwise receiving well-formed responses to RELAY
1856 cells.
1857 By default, or if a negative value is provided for one of these
1860 options, Tor uses reasonable defaults from the networkstatus
1861 consensus document. If no defaults are available there, these
1862 options default to 20, .80, .60, and 100, respectively.
1863 ClientUseIPv4 0|1
1865 If this option is set to 0, Tor will avoid connecting to directory
1866 servers and entry nodes over IPv4. Note that clients with an IPv4
1867 address in a Bridge, proxy, or pluggable transport line will try
1868 connecting over IPv4 even if ClientUseIPv4 is set to 0. (Default:
1869 1)
1870 ClientUseIPv6 0|1
1872 If this option is set to 1, Tor might connect to directory servers
1873 or entry nodes over IPv6. For IPv6 only hosts, you need to also set
1874 ClientUseIPv4 to 0 to disable IPv4. Note that clients configured
1875 with an IPv6 address in a Bridge, proxy, or pluggable transportline
1876 will try connecting over IPv6 even if ClientUseIPv6 is set to 0.
1877 (Default: 0)
1878 ClientPreferIPv6DirPort 0|1|auto
1880 If this option is set to 1, Tor prefers a directory port with an
1881 IPv6 address over one with IPv4, for direct connections, if a given
1882 directory server has both. (Tor also prefers an IPv6 DirPort if
1883 IPv4Client is set to 0.) If this option is set to auto, clients
1884 prefer IPv4. Other things may influence the choice. This option
1885 breaks a tie to the favor of IPv6. (Default: auto) (DEPRECATED:
1886 This option has had no effect for some time.)
1887 ClientPreferIPv6ORPort 0|1|auto
1889 If this option is set to 1, Tor prefers an OR port with an IPv6
1890 address over one with IPv4 if a given entry node has both. (Tor
1891 also prefers an IPv6 ORPort if IPv4Client is set to 0.) If this
1892 option is set to auto, Tor bridge clients prefer the configured
1893 bridge address, and other clients prefer IPv4. Other things may
1894 influence the choice. This option breaks a tie to the favor of
1895 IPv6. (Default: auto)
1896 PathsNeededToBuildCircuits NUM
1898 Tor clients don’t build circuits for user traffic until they know
1899 about enough of the network so that they could potentially
1900 construct enough of the possible paths through the network. If this
1901 option is set to a fraction between 0.25 and 0.95, Tor won’t build
1902 circuits until it has enough descriptors or microdescriptors to
1903 construct that fraction of possible paths. Note that setting this
1904 option too low can make your Tor client less anonymous, and setting
1905 it too high can prevent your Tor client from bootstrapping. If this
1906 option is negative, Tor will use a default value chosen by the
1907 directory authorities. If the directory authorities do not choose a
1908 value, Tor will default to 0.6. (Default: -1)
1909 ClientBootstrapConsensusAuthorityDownloadInitialDelay N
1911 Initial delay in seconds for when clients should download
1912 consensuses from authorities if they are bootstrapping (that is,
1913 they don’t have a usable, reasonably live consensus). Only used by
1914 clients fetching from a list of fallback directory mirrors. This
1915 schedule is advanced by (potentially concurrent) connection
1916 attempts, unlike other schedules, which are advanced by connection
1917 failures. (Default: 6)
1918 ClientBootstrapConsensusFallbackDownloadInitialDelay N
1920 Initial delay in seconds for when clients should download
1921 consensuses from fallback directory mirrors if they are
1922 bootstrapping (that is, they don’t have a usable, reasonably live
1923 consensus). Only used by clients fetching from a list of fallback
1924 directory mirrors. This schedule is advanced by (potentially
1925 concurrent) connection attempts, unlike other schedules, which are
1926 advanced by connection failures. (Default: 0)
1927 ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay N
1929 Initial delay in seconds for when clients should download
1930 consensuses from authorities if they are bootstrapping (that is,
1931 they don’t have a usable, reasonably live consensus). Only used by
1932 clients which don’t have or won’t fetch from a list of fallback
1933 directory mirrors. This schedule is advanced by (potentially
1934 concurrent) connection attempts, unlike other schedules, which are
1935 advanced by connection failures. (Default: 0)
1936 ClientBootstrapConsensusMaxInProgressTries NUM
1938 Try this many simultaneous connections to download a consensus
1939 before waiting for one to complete, timeout, or error out.
1940 (Default: 3)
1941
1943 The following options are useful only for servers (that is, if ORPort
1944 is non-zero):
1945 Address address
1947 The IPv4 address of this server, or a fully qualified domain name
1948 of this server that resolves to an IPv4 address. You can leave this
1949 unset, and Tor will try to guess your IPv4 address. This IPv4
1950 address is the one used to tell clients and other servers where to
1951 find your Tor server; it doesn’t affect the address that your
1952 server binds to. To bind to a different address, use the ORPort and
1953 OutboundBindAddress options.
1954 AssumeReachable 0|1
1956 This option is used when bootstrapping a new Tor network. If set to
1957 1, don’t do self-reachability testing; just upload your server
1958 descriptor immediately. If AuthoritativeDirectory is also set, this
1959 option instructs the dirserver to bypass remote reachability
1960 testing too and list all connected servers as running.
1961 BridgeRelay 0|1
1963 Sets the relay to act as a "bridge" with respect to relaying
1964 connections from bridge users to the Tor network. It mainly causes
1965 Tor to publish a server descriptor to the bridge database, rather
1966 than to the public directory authorities.
1967 Note: make sure that no MyFamily lines are present in your torrc
1970 when relay is configured in bridge mode.
1971 BridgeDistribution string
1973 If set along with BridgeRelay, Tor will include a new line in its
1974 bridge descriptor which indicates to the BridgeDB service how it
1975 would like its bridge address to be given out. Set it to "none" if
1976 you want BridgeDB to avoid distributing your bridge address, or
1977 "any" to let BridgeDB decide. (Default: any)
1978 Note: as of Oct 2017, the BridgeDB part of this option is not yet
1980 implemented. Until BridgeDB is updated to obey this option, your
1981 bridge will make this request, but it will not (yet) be obeyed.
1982 ContactInfo email_address
1984 Administrative contact information for this relay or bridge. This
1985 line can be used to contact you if your relay or bridge is
1986 misconfigured or something else goes wrong. Note that we archive
1987 and publish all descriptors containing these lines and that Google
1988 indexes them, so spammers might also collect them. You may want to
1989 obscure the fact that it’s an email address and/or generate a new
1990 address for this purpose.
1991 ContactInfo must be set to a working address if you run more than
1994 one relay or bridge. (Really, everybody running a relay or bridge
1995 should set it.)
1996 ExitRelay 0|1|auto
1998 Tells Tor whether to run as an exit relay. If Tor is running as a
1999 non-bridge server, and ExitRelay is set to 1, then Tor allows
2000 traffic to exit according to the ExitPolicy option (or the default
2001 ExitPolicy if none is specified).
2002 If ExitRelay is set to 0, no traffic is allowed to exit, and the
2005 ExitPolicy option is ignored.
2006 If ExitRelay is set to "auto", then Tor behaves as if it were set
2009 to 1, but warns the user if this would cause traffic to exit. In a
2010 future version, the default value will be 0. (Default: auto)
2011 ExitPolicy policy,policy,...
2013 Set an exit policy for this server. Each policy is of the form
2014 "accept[6]|reject[6] ADDR[/MASK][:PORT]". If /MASK is omitted then
2015 this policy just applies to the host given. Instead of giving a
2016 host or network you can also use "*" to denote the universe
2017 (0.0.0.0/0 and ::/0), or *4 to denote all IPv4 addresses, and *6 to
2018 denote all IPv6 addresses. PORT can be a single port number, an
2019 interval of ports "FROM_PORT-TO_PORT", or "*". If PORT is omitted,
2020 that means "*".
2021 For example, "accept 18.7.22.69:*,reject 18.0.0.0/8:*,accept *:*"
2024 would reject any IPv4 traffic destined for MIT except for
2025 web.mit.edu, and accept any other IPv4 or IPv6 traffic.
2026 Tor also allows IPv6 exit policy entries. For instance, "reject6
2029 [FC00::]/7:*" rejects all destinations that share 7 most
2030 significant bit prefix with address FC00::. Respectively, "accept6
2031 [C000::]/3:*" accepts all destinations that share 3 most
2032 significant bit prefix with address C000::.
2033 accept6 and reject6 only produce IPv6 exit policy entries. Using an
2036 IPv4 address with accept6 or reject6 is ignored and generates a
2037 warning. accept/reject allows either IPv4 or IPv6 addresses. Use *4
2038 as an IPv4 wildcard address, and *6 as an IPv6 wildcard address.
2039 accept/reject * expands to matching IPv4 and IPv6 wildcard address
2040 rules.
2041 To specify all IPv4 and IPv6 internal and link-local networks
2044 (including 0.0.0.0/8, 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16,
2045 10.0.0.0/8, 172.16.0.0/12, [::]/8, [FC00::]/7, [FE80::]/10,
2046 [FEC0::]/10, [FF00::]/8, and [::]/127), you can use the "private"
2047 alias instead of an address. ("private" always produces rules for
2048 IPv4 and IPv6 addresses, even when used with accept6/reject6.)
2049 Private addresses are rejected by default (at the beginning of your
2052 exit policy), along with any configured primary public IPv4 and
2053 IPv6 addresses. These private addresses are rejected unless you set
2054 the ExitPolicyRejectPrivate config option to 0. For example, once
2055 you’ve done that, you could allow HTTP to 127.0.0.1 and block all
2056 other connections to internal networks with "accept
2057 127.0.0.1:80,reject private:*", though that may also allow
2058 connections to your own computer that are addressed to its public
2059 (external) IP address. See RFC 1918 and RFC 3330 for more details
2060 about internal and reserved IP address space. See
2061 ExitPolicyRejectLocalInterfaces if you want to block every address
2062 on the relay, even those that aren’t advertised in the descriptor.
2063 This directive can be specified multiple times so you don’t have to
2066 put it all on one line.
2067 Policies are considered first to last, and the first match wins. If
2070 you want to allow the same ports on IPv4 and IPv6, write your rules
2071 using accept/reject *. If you want to allow different ports on IPv4
2072 and IPv6, write your IPv6 rules using accept6/reject6 *6, and your
2073 IPv4 rules using accept/reject *4. If you want to _replace_ the
2074 default exit policy, end your exit policy with either a reject *:*
2075 or an accept *:*. Otherwise, you’re _augmenting_ (prepending to)
2076 the default exit policy.
2077 If you want to use a reduced exit policy rather than the default
2080 exit policy, set "ReducedExitPolicy 1". If you want to replace the
2081 default exit policy with your custom exit policy, end your exit
2082 policy with either a reject : or an accept :. Otherwise, you’re
2083 augmenting (prepending to) the default or reduced exit policy.
2084 The default exit policy is:
2087 reject *:25
2089 reject *:119
2090 reject *:135-139
2091 reject *:445
2092 reject *:563
2093 reject *:1214
2094 reject *:4661-4666
2095 reject *:6346-6429
2096 reject *:6699
2097 reject *:6881-6999
2098 accept *:*
2099 Since the default exit policy uses accept/reject *, it applies to
2101 both IPv4 and IPv6 addresses.
2102 ExitPolicyRejectPrivate 0|1
2104 Reject all private (local) networks, along with the relay’s
2105 advertised public IPv4 and IPv6 addresses, at the beginning of your
2106 exit policy. See above entry on ExitPolicy. (Default: 1)
2107 ExitPolicyRejectLocalInterfaces 0|1
2109 Reject all IPv4 and IPv6 addresses that the relay knows about, at
2110 the beginning of your exit policy. This includes any
2111 OutboundBindAddress, the bind addresses of any port options, such
2112 as ControlPort or DNSPort, and any public IPv4 and IPv6 addresses
2113 on any interface on the relay. (If IPv6Exit is not set, all IPv6
2114 addresses will be rejected anyway.) See above entry on ExitPolicy.
2115 This option is off by default, because it lists all public relay IP
2116 addresses in the ExitPolicy, even those relay operators might
2117 prefer not to disclose. (Default: 0)
2118 ReducedExitPolicy 0|1
2120 If set, use a reduced exit policy rather than the default one.
2121 The reduced exit policy is an alternative to the default exit
2124 policy. It allows as many Internet services as possible while still
2125 blocking the majority of TCP ports. Currently, the policy allows
2126 approximately 65 ports. This reduces the odds that your node will
2127 be used for peer-to-peer applications.
2128 The reduced exit policy is:
2131 accept *:20-21
2133 accept *:22
2134 accept *:23
2135 accept *:43
2136 accept *:53
2137 accept *:79
2138 accept *:80-81
2139 accept *:88
2140 accept *:110
2141 accept *:143
2142 accept *:194
2143 accept *:220
2144 accept *:389
2145 accept *:443
2146 accept *:464
2147 accept *:465
2148 accept *:531
2149 accept *:543-544
2150 accept *:554
2151 accept *:563
2152 accept *:587
2153 accept *:636
2154 accept *:706
2155 accept *:749
2156 accept *:873
2157 accept *:902-904
2158 accept *:981
2159 accept *:989-990
2160 accept *:991
2161 accept *:992
2162 accept *:993
2163 accept *:994
2164 accept *:995
2165 accept *:1194
2166 accept *:1220
2167 accept *:1293
2168 accept *:1500
2169 accept *:1533
2170 accept *:1677
2171 accept *:1723
2172 accept *:1755
2173 accept *:1863
2174 accept *:2082
2175 accept *:2083
2176 accept *:2086-2087
2177 accept *:2095-2096
2178 accept *:2102-2104
2179 accept *:3128
2180 accept *:3389
2181 accept *:3690
2182 accept *:4321
2183 accept *:4643
2184 accept *:5050
2185 accept *:5190
2186 accept *:5222-5223
2187 accept *:5228
2188 accept *:5900
2189 accept *:6660-6669
2190 accept *:6679
2191 accept *:6697
2192 accept *:8000
2193 accept *:8008
2194 accept *:8074
2195 accept *:8080
2196 accept *:8082
2197 accept *:8087-8088
2198 accept *:8232-8233
2199 accept *:8332-8333
2200 accept *:8443
2201 accept *:8888
2202 accept *:9418
2203 accept *:9999
2204 accept *:10000
2205 accept *:11371
2206 accept *:19294
2207 accept *:19638
2208 accept *:50002
2209 accept *:64738
2210 reject *:*
2211 (Default: 0)
2213 IPv6Exit 0|1
2215 If set, and we are an exit node, allow clients to use us for IPv6
2216 traffic. (Default: 0)
2217 MaxOnionQueueDelay NUM [msec|second]
2219 If we have more onionskins queued for processing than we can
2220 process in this amount of time, reject new ones. (Default: 1750
2221 msec)
2222 MyFamily fingerprint,fingerprint,...
2224 Declare that this Tor relay is controlled or administered by a
2225 group or organization identical or similar to that of the other
2226 relays, defined by their (possibly $-prefixed) identity
2227 fingerprints. This option can be repeated many times, for
2228 convenience in defining large families: all fingerprints in all
2229 MyFamily lines are merged into one list. When two relays both
2230 declare that they are in the same 'family', Tor clients will not
2231 use them in the same circuit. (Each relay only needs to list the
2232 other servers in its family; it doesn’t need to list itself, but it
2233 won’t hurt if it does.) Do not list any bridge relay as it would
2234 compromise its concealment.
2235 When listing a node, it’s better to list it by fingerprint than by
2238 nickname: fingerprints are more reliable.
2239 If you run more than one relay, the MyFamily option on each relay
2242 must list all other relays, as described above.
2243 Note: do not use MyFamily when configuring your Tor instance as a
2246 brigde.
2247 Nickname name
2249 Set the server’s nickname to 'name'. Nicknames must be between 1
2250 and 19 characters inclusive, and must contain only the characters
2251 [a-zA-Z0-9]. If not set, Unnamed will be used. Relays can always be
2252 uniquely identified by their identity fingerprints.
2253 NumCPUs num
2255 How many processes to use at once for decrypting onionskins and
2256 other parallelizable operations. If this is set to 0, Tor will try
2257 to detect how many CPUs you have, defaulting to 1 if it can’t tell.
2258 (Default: 0)
2259 ORPort [address:]PORT|auto [flags]
2261 Advertise this port to listen for connections from Tor clients and
2262 servers. This option is required to be a Tor server. Set it to
2263 "auto" to have Tor pick a port for you. Set it to 0 to not run an
2264 ORPort at all. This option can occur more than once. (Default: 0)
2265 Tor recognizes these flags on each ORPort:
2268 NoAdvertise
2270 By default, we bind to a port and tell our users about it. If
2271 NoAdvertise is specified, we don’t advertise, but listen
2272 anyway. This can be useful if the port everybody will be
2273 connecting to (for example, one that’s opened on our firewall)
2274 is somewhere else.
2275 NoListen
2277 By default, we bind to a port and tell our users about it. If
2278 NoListen is specified, we don’t bind, but advertise anyway.
2279 This can be useful if something else (for example, a firewall’s
2280 port forwarding configuration) is causing connections to reach
2281 us.
2282 IPv4Only
2284 If the address is absent, or resolves to both an IPv4 and an
2285 IPv6 address, only listen to the IPv4 address.
2286 IPv6Only
2288 If the address is absent, or resolves to both an IPv4 and an
2289 IPv6 address, only listen to the IPv6 address.
2290 For obvious reasons, NoAdvertise and NoListen are mutually
2292 exclusive, and IPv4Only and IPv6Only are mutually exclusive.
2293 PublishServerDescriptor 0|1|v3|bridge,...
2295 This option specifies which descriptors Tor will publish when
2296 acting as a relay. You can choose multiple arguments, separated by
2297 commas.
2298 If this option is set to 0, Tor will not publish its descriptors to
2301 any directories. (This is useful if you’re testing out your server,
2302 or if you’re using a Tor controller that handles directory
2303 publishing for you.) Otherwise, Tor will publish its descriptors of
2304 all type(s) specified. The default is "1", which means "if running
2305 as a relay or bridge, publish descriptors to the appropriate
2306 authorities". Other possibilities are "v3", meaning "publish as if
2307 you’re a relay", and "bridge", meaning "publish as if you’re a
2308 bridge".
2309 ShutdownWaitLength NUM
2311 When we get a SIGINT and we’re a server, we begin shutting down: we
2312 close listeners and start refusing new circuits. After NUM seconds,
2313 we exit. If we get a second SIGINT, we exit immediately. (Default:
2314 30 seconds)
2315 SSLKeyLifetime N minutes|hours|days|weeks
2317 When creating a link certificate for our outermost SSL handshake,
2318 set its lifetime to this amount of time. If set to 0, Tor will
2319 choose some reasonable random defaults. (Default: 0)
2320 HeartbeatPeriod N minutes|hours|days|weeks
2322 Log a heartbeat message every HeartbeatPeriod seconds. This is a
2323 log level notice message, designed to let you know your Tor server
2324 is still alive and doing useful things. Settings this to 0 will
2325 disable the heartbeat. Otherwise, it must be at least 30 minutes.
2326 (Default: 6 hours)
2327 MainloopStats 0|1
2329 Log main loop statistics every HeartbeatPeriod seconds. This is a
2330 log level notice message designed to help developers instrumenting
2331 Tor’s main event loop. (Default: 0)
2332 AccountingMax N
2334 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
2335 Limits the max number of bytes sent and received within a set time
2336 period using a given calculation rule (see: AccountingStart,
2337 AccountingRule). Useful if you need to stay under a specific
2338 bandwidth. By default, the number used for calculation is the max
2339 of either the bytes sent or received. For example, with
2340 AccountingMax set to 1 GByte, a server could send 900 MBytes and
2341 receive 800 MBytes and continue running. It will only hibernate
2342 once one of the two reaches 1 GByte. This can be changed to use the
2343 sum of the both bytes received and sent by setting the
2344 AccountingRule option to "sum" (total bandwidth in/out). When the
2345 number of bytes remaining gets low, Tor will stop accepting new
2346 connections and circuits. When the number of bytes is exhausted,
2347 Tor will hibernate until some time in the next accounting period.
2348 To prevent all servers from waking at the same time, Tor will also
2349 wait until a random point in each period before waking up. If you
2350 have bandwidth cost issues, enabling hibernation is preferable to
2351 setting a low bandwidth, since it provides users with a collection
2352 of fast servers that are up some of the time, which is more useful
2353 than a set of slow servers that are always "available".
2354 AccountingRule sum|max|in|out
2356 How we determine when our AccountingMax has been reached (when we
2357 should hibernate) during a time interval. Set to "max" to calculate
2358 using the higher of either the sent or received bytes (this is the
2359 default functionality). Set to "sum" to calculate using the sent
2360 plus received bytes. Set to "in" to calculate using only the
2361 received bytes. Set to "out" to calculate using only the sent
2362 bytes. (Default: max)
2363 AccountingStart day|week|month [day] HH:MM
2365 Specify how long accounting periods last. If month is given, each
2366 accounting period runs from the time HH:MM on the dayth day of one
2367 month to the same day and time of the next. The relay will go at
2368 full speed, use all the quota you specify, then hibernate for the
2369 rest of the period. (The day must be between 1 and 28.) If week is
2370 given, each accounting period runs from the time HH:MM of the dayth
2371 day of one week to the same day and time of the next week, with
2372 Monday as day 1 and Sunday as day 7. If day is given, each
2373 accounting period runs from the time HH:MM each day to the same
2374 time on the next day. All times are local, and given in 24-hour
2375 time. (Default: "month 1 0:00")
2376 RefuseUnknownExits 0|1|auto
2378 Prevent nodes that don’t appear in the consensus from exiting using
2379 this relay. If the option is 1, we always block exit attempts from
2380 such nodes; if it’s 0, we never do, and if the option is "auto",
2381 then we do whatever the authorities suggest in the consensus (and
2382 block if the consensus is quiet on the issue). (Default: auto)
2383 ServerDNSResolvConfFile filename
2385 Overrides the default DNS configuration with the configuration in
2386 filename. The file format is the same as the standard Unix
2387 "resolv.conf" file (7). This option, like all other ServerDNS
2388 options, only affects name lookups that your server does on behalf
2389 of clients. (Defaults to use the system DNS configuration.)
2390 ServerDNSAllowBrokenConfig 0|1
2392 If this option is false, Tor exits immediately if there are
2393 problems parsing the system DNS configuration or connecting to
2394 nameservers. Otherwise, Tor continues to periodically retry the
2395 system nameservers until it eventually succeeds. (Default: 1)
2396 ServerDNSSearchDomains 0|1
2398 If set to 1, then we will search for addresses in the local search
2399 domain. For example, if this system is configured to believe it is
2400 in "example.com", and a client tries to connect to "www", the
2401 client will be connected to "www.example.com". This option only
2402 affects name lookups that your server does on behalf of clients.
2403 (Default: 0)
2404 ServerDNSDetectHijacking 0|1
2406 When this option is set to 1, we will test periodically to
2407 determine whether our local nameservers have been configured to
2408 hijack failing DNS requests (usually to an advertising site). If
2409 they are, we will attempt to correct this. This option only affects
2410 name lookups that your server does on behalf of clients. (Default:
2411 1)
2412 ServerDNSTestAddresses hostname,hostname,...
2414 When we’re detecting DNS hijacking, make sure that these valid
2415 addresses aren’t getting redirected. If they are, then our DNS is
2416 completely useless, and we’ll reset our exit policy to "reject
2417 *:*". This option only affects name lookups that your server does
2418 on behalf of clients. (Default: "www.google.com, www.mit.edu,
2419 www.yahoo.com, www.slashdot.org")
2420 ServerDNSAllowNonRFC953Hostnames 0|1
2422 When this option is disabled, Tor does not try to resolve hostnames
2423 containing illegal characters (like @ and :) rather than sending
2424 them to an exit node to be resolved. This helps trap accidental
2425 attempts to resolve URLs and so on. This option only affects name
2426 lookups that your server does on behalf of clients. (Default: 0)
2427 BridgeRecordUsageByCountry 0|1
2429 When this option is enabled and BridgeRelay is also enabled, and we
2430 have GeoIP data, Tor keeps a per-country count of how many client
2431 addresses have contacted it so that it can help the bridge
2432 authority guess which countries have blocked access to it.
2433 (Default: 1)
2434 ServerDNSRandomizeCase 0|1
2436 When this option is set, Tor sets the case of each character
2437 randomly in outgoing DNS requests, and makes sure that the case
2438 matches in DNS replies. This so-called "0x20 hack" helps resist
2439 some types of DNS poisoning attack. For more information, see
2440 "Increased DNS Forgery Resistance through 0x20-Bit Encoding". This
2441 option only affects name lookups that your server does on behalf of
2442 clients. (Default: 1)
2443 GeoIPFile filename
2445 A filename containing IPv4 GeoIP data, for use with by-country
2446 statistics.
2447 GeoIPv6File filename
2449 A filename containing IPv6 GeoIP data, for use with by-country
2450 statistics.
2451 CellStatistics 0|1
2453 Relays only. When this option is enabled, Tor collects statistics
2454 about cell processing (i.e. mean time a cell is spending in a
2455 queue, mean number of cells in a queue and mean number of processed
2456 cells per circuit) and writes them into disk every 24 hours. Onion
2457 router operators may use the statistics for performance monitoring.
2458 If ExtraInfoStatistics is enabled, it will published as part of
2459 extra-info document. (Default: 0)
2460 PaddingStatistics 0|1
2462 Relays only. When this option is enabled, Tor collects statistics
2463 for padding cells sent and received by this relay, in addition to
2464 total cell counts. These statistics are rounded, and omitted if
2465 traffic is low. This information is important for load balancing
2466 decisions related to padding. If ExtraInfoStatistics is enabled, it
2467 will be published as a part of extra-info document. (Default: 1)
2468 DirReqStatistics 0|1
2470 Relays and bridges only. When this option is enabled, a Tor
2471 directory writes statistics on the number and response time of
2472 network status requests to disk every 24 hours. Enables relay and
2473 bridge operators to monitor how much their server is being used by
2474 clients to learn about Tor network. If ExtraInfoStatistics is
2475 enabled, it will published as part of extra-info document.
2476 (Default: 1)
2477 EntryStatistics 0|1
2479 Relays only. When this option is enabled, Tor writes statistics on
2480 the number of directly connecting clients to disk every 24 hours.
2481 Enables relay operators to monitor how much inbound traffic that
2482 originates from Tor clients passes through their server to go
2483 further down the Tor network. If ExtraInfoStatistics is enabled, it
2484 will be published as part of extra-info document. (Default: 0)
2485 ExitPortStatistics 0|1
2487 Exit relays only. When this option is enabled, Tor writes
2488 statistics on the number of relayed bytes and opened stream per
2489 exit port to disk every 24 hours. Enables exit relay operators to
2490 measure and monitor amounts of traffic that leaves Tor network
2491 through their exit node. If ExtraInfoStatistics is enabled, it will
2492 be published as part of extra-info document. (Default: 0)
2493 ConnDirectionStatistics 0|1
2495 Relays only. When this option is enabled, Tor writes statistics on
2496 the amounts of traffic it passes between itself and other relays to
2497 disk every 24 hours. Enables relay operators to monitor how much
2498 their relay is being used as middle node in the circuit. If
2499 ExtraInfoStatistics is enabled, it will be published as part of
2500 extra-info document. (Default: 0)
2501 HiddenServiceStatistics 0|1
2503 Relays only. When this option is enabled, a Tor relay writes
2504 obfuscated statistics on its role as hidden-service directory,
2505 introduction point, or rendezvous point to disk every 24 hours. If
2506 ExtraInfoStatistics is also enabled, these statistics are further
2507 published to the directory authorities. (Default: 1)
2508 ExtraInfoStatistics 0|1
2510 When this option is enabled, Tor includes previously gathered
2511 statistics in its extra-info documents that it uploads to the
2512 directory authorities. (Default: 1)
2513 ExtendAllowPrivateAddresses 0|1
2515 When this option is enabled, Tor will connect to relays on
2516 localhost, RFC1918 addresses, and so on. In particular, Tor will
2517 make direct OR connections, and Tor routers allow EXTEND requests,
2518 to these private addresses. (Tor will always allow connections to
2519 bridges, proxies, and pluggable transports configured on private
2520 addresses.) Enabling this option can create security issues; you
2521 should probably leave it off. (Default: 0)
2522 MaxMemInQueues N bytes|KB|MB|GB
2524 This option configures a threshold above which Tor will assume that
2525 it needs to stop queueing or buffering data because it’s about to
2526 run out of memory. If it hits this threshold, it will begin killing
2527 circuits until it has recovered at least 10% of this memory. Do not
2528 set this option too low, or your relay may be unreliable under
2529 load. This option only affects some queues, so the actual process
2530 size will be larger than this. If this option is set to 0, Tor will
2531 try to pick a reasonable default based on your system’s physical
2532 memory. (Default: 0)
2533 DisableOOSCheck 0|1
2535 This option disables the code that closes connections when Tor
2536 notices that it is running low on sockets. Right now, it is on by
2537 default, since the existing out-of-sockets mechanism tends to kill
2538 OR connections more than it should. (Default: 1)
2539 SigningKeyLifetime N days|weeks|months
2541 For how long should each Ed25519 signing key be valid? Tor uses a
2542 permanent master identity key that can be kept offline, and
2543 periodically generates new "signing" keys that it uses online. This
2544 option configures their lifetime. (Default: 30 days)
2545 OfflineMasterKey 0|1
2547 If non-zero, the Tor relay will never generate or load its master
2548 secret key. Instead, you’ll have to use "tor --keygen" to manage
2549 the permanent ed25519 master identity key, as well as the
2550 corresponding temporary signing keys and certificates. (Default: 0)
2551 KeyDirectory DIR
2553 Store secret keys in DIR. Can not be changed while tor is running.
2554 (Default: the "keys" subdirectory of DataDirectory.)
2555 KeyDirectoryGroupReadable 0|1
2557 If this option is set to 0, don’t allow the filesystem group to
2558 read the KeywDirectory. If the option is set to 1, make the
2559 KeyDirectory readable by the default GID. (Default: 0)
2560 RephistTrackTime N seconds|minutes|hours|days|weeks
2562 Tells an authority, or other node tracking node reliability and
2563 history, that fine-grained information about nodes can be discarded
2564 when it hasn’t changed for a given amount of time. (Default: 24
2565 hours)
2566
2568 The following options are useful only for directory servers. (Relays
2569 with enough bandwidth automatically become directory servers; see
2570 DirCache for details.)
2571 DirPortFrontPage FILENAME
2573 When this option is set, it takes an HTML file and publishes it as
2574 "/" on the DirPort. Now relay operators can provide a disclaimer
2575 without needing to set up a separate webserver. There’s a sample
2576 disclaimer in contrib/operator-tools/tor-exit-notice.html.
2577 DirPort [address:]PORT|auto [flags]
2579 If this option is nonzero, advertise the directory service on this
2580 port. Set it to "auto" to have Tor pick a port for you. This option
2581 can occur more than once, but only one advertised DirPort is
2582 supported: all but one DirPort must have the NoAdvertise flag set.
2583 (Default: 0)
2584 The same flags are supported here as are supported by ORPort.
2587 DirPolicy policy,policy,...
2589 Set an entrance policy for this server, to limit who can connect to
2590 the directory ports. The policies have the same form as exit
2591 policies above, except that port specifiers are ignored. Any
2592 address not matched by some entry in the policy is accepted.
2593 DirCache 0|1
2595 When this option is set, Tor caches all current directory documents
2596 except extra info documents, and accepts client requests for them.
2597 If DownloadExtraInfo is set, cached extra info documents are also
2598 cached. Setting DirPort is not required for DirCache, because
2599 clients connect via the ORPort by default. Setting either DirPort
2600 or BridgeRelay and setting DirCache to 0 is not supported.
2601 (Default: 1)
2602 MaxConsensusAgeForDiffs N minutes|hours|days|weeks
2604 When this option is nonzero, Tor caches will not try to generate
2605 consensus diffs for any consensus older than this amount of time.
2606 If this option is set to zero, Tor will pick a reasonable default
2607 from the current networkstatus document. You should not set this
2608 option unless your cache is severely low on disk space or CPU. If
2609 you need to set it, keeping it above 3 or 4 hours will help clients
2610 much more than setting it to zero. (Default: 0)
2611
2613 Tor has three built-in mitigation options that can be individually
2614 enabled/disabled and fine-tuned, but by default Tor directory
2615 authorities will define reasonable values for relays and no explicit
2616 configuration is required to make use of these protections. The
2617 mitigations take place at relays, and are as follows:
2618 1. If a single client address makes too many concurrent connections
2620 (this is configurable via DoSConnectionMaxConcurrentCount), hang up
2621 on further connections.
2622 2. If a single client IP address (v4 or v6) makes circuits too quickly
2624 (default values are more than 3 per second, with an allowed burst
2625 of 90, see DoSCircuitCreationRate and DoSCircuitCreationBurst)
2626 while also having too many connections open (default is 3, see
2627 DoSCircuitCreationMinConnections), tor will refuse any new circuit
2628 (CREATE cells) for the next while (random value between 1 and 2
2629 hours).
2630 3. If a client asks to establish a rendezvous point to you directly
2632 (ex: Tor2Web client), ignore the request.
2633 These defenses can be manually controlled by torrc options, but relays
2635 will also take guidance from consensus parameters using these same
2636 names, so there’s no need to configure anything manually. In doubt, do
2637 not change those values.
2638 The values set by the consensus, if any, can be found here:
2640 https://consensus-health.torproject.org/#consensusparams
2641 If any of the DoS mitigations are enabled, a heartbeat message will
2643 appear in your log at NOTICE level which looks like:
2644 DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses.
2646 2238 connections closed. 8052 single hop clients refused.
2647 The following options are useful only for a public relay. They control
2649 the Denial of Service mitigation subsystem described above.
2650 DoSCircuitCreationEnabled 0|1|auto
2652 Enable circuit creation DoS mitigation. If set to 1 (enabled), tor
2653 will cache client IPs along with statistics in order to detect
2654 circuit DoS attacks. If an address is positively identified, tor
2655 will activate defenses against the address. See the
2656 DoSCircuitCreationDefenseType option for more details. This is a
2657 client to relay detection only. "auto" means use the consensus
2658 parameter. If not defined in the consensus, the value is 0.
2659 (Default: auto)
2660 DoSCircuitCreationMinConnections NUM
2662 Minimum threshold of concurrent connections before a client address
2663 can be flagged as executing a circuit creation DoS. In other words,
2664 once a client address reaches the circuit rate and has a minimum of
2665 NUM concurrent connections, a detection is positive. "0" means use
2666 the consensus parameter. If not defined in the consensus, the value
2667 is 3. (Default: 0)
2668 DoSCircuitCreationRate NUM
2670 The allowed circuit creation rate per second applied per client IP
2671 address. If this option is 0, it obeys a consensus parameter. If
2672 not defined in the consensus, the value is 3. (Default: 0)
2673 DoSCircuitCreationBurst NUM
2675 The allowed circuit creation burst per client IP address. If the
2676 circuit rate and the burst are reached, a client is marked as
2677 executing a circuit creation DoS. "0" means use the consensus
2678 parameter. If not defined in the consensus, the value is 90.
2679 (Default: 0)
2680 DoSCircuitCreationDefenseType NUM
2682 This is the type of defense applied to a detected client address.
2683 The possible values are:
2684 1: No defense.
2686 2: Refuse circuit creation for the
2688 DoSCircuitCreationDefenseTimePeriod period of time.
2689 "0" means use the consensus parameter. If not defined in the
2691 consensus, the value is 2. (Default: 0)
2692 DoSCircuitCreationDefenseTimePeriod N seconds|minutes|hours
2694 The base time period in seconds that the DoS defense is activated
2695 for. The actual value is selected randomly for each activation from
2696 N+1 to 3/2 * N. "0" means use the consensus parameter. If not
2697 defined in the consensus, the value is 3600 seconds (1 hour).
2698 (Default: 0)
2699 DoSConnectionEnabled 0|1|auto
2701 Enable the connection DoS mitigation. If set to 1 (enabled), for
2702 client address only, this allows tor to mitigate against large
2703 number of concurrent connections made by a single IP address.
2704 "auto" means use the consensus parameter. If not defined in the
2705 consensus, the value is 0. (Default: auto)
2706 DoSConnectionMaxConcurrentCount NUM
2708 The maximum threshold of concurrent connection from a client IP
2709 address. Above this limit, a defense selected by
2710 DoSConnectionDefenseType is applied. "0" means use the consensus
2711 parameter. If not defined in the consensus, the value is 100.
2712 (Default: 0)
2713 DoSConnectionDefenseType NUM
2715 This is the type of defense applied to a detected client address
2716 for the connection mitigation. The possible values are:
2717 1: No defense.
2719 2: Immediately close new connections.
2721 "0" means use the consensus parameter. If not defined in the
2723 consensus, the value is 2. (Default: 0)
2724 DoSRefuseSingleHopClientRendezvous 0|1|auto
2726 Refuse establishment of rendezvous points for single hop clients.
2727 In other words, if a client directly connects to the relay and
2728 sends an ESTABLISH_RENDEZVOUS cell, it is silently dropped. "auto"
2729 means use the consensus parameter. If not defined in the consensus,
2730 the value is 0. (Default: auto)
2731
2733 The following options enable operation as a directory authority, and
2734 control how Tor behaves as a directory authority. You should not need
2735 to adjust any of them if you’re running a regular relay or exit server
2736 on the public Tor network.
2737 AuthoritativeDirectory 0|1
2739 When this option is set to 1, Tor operates as an authoritative
2740 directory server. Instead of caching the directory, it generates
2741 its own list of good servers, signs it, and sends that to the
2742 clients. Unless the clients already have you listed as a trusted
2743 directory, you probably do not want to set this option.
2744 V3AuthoritativeDirectory 0|1
2746 When this option is set in addition to AuthoritativeDirectory, Tor
2747 generates version 3 network statuses and serves descriptors, etc as
2748 described in dir-spec.txt file of torspec (for Tor clients and
2749 servers running at least 0.2.0.x).
2750 VersioningAuthoritativeDirectory 0|1
2752 When this option is set to 1, Tor adds information on which
2753 versions of Tor are still believed safe for use to the published
2754 directory. Each version 1 authority is automatically a versioning
2755 authority; version 2 authorities provide this service optionally.
2756 See RecommendedVersions, RecommendedClientVersions, and
2757 RecommendedServerVersions.
2758 RecommendedVersions STRING
2760 STRING is a comma-separated list of Tor versions currently believed
2761 to be safe. The list is included in each directory, and nodes which
2762 pull down the directory learn whether they need to upgrade. This
2763 option can appear multiple times: the values from multiple lines
2764 are spliced together. When this is set then
2765 VersioningAuthoritativeDirectory should be set too.
2766 RecommendedPackages PACKAGENAME VERSION URL DIGESTTYPE=DIGEST
2768 Adds "package" line to the directory authority’s vote. This
2769 information is used to vote on the correct URL and digest for the
2770 released versions of different Tor-related packages, so that the
2771 consensus can certify them. This line may appear any number of
2772 times.
2773 RecommendedClientVersions STRING
2775 STRING is a comma-separated list of Tor versions currently believed
2776 to be safe for clients to use. This information is included in
2777 version 2 directories. If this is not set then the value of
2778 RecommendedVersions is used. When this is set then
2779 VersioningAuthoritativeDirectory should be set too.
2780 BridgeAuthoritativeDir 0|1
2782 When this option is set in addition to AuthoritativeDirectory, Tor
2783 accepts and serves server descriptors, but it caches and serves the
2784 main networkstatus documents rather than generating its own.
2785 (Default: 0)
2786 MinUptimeHidServDirectoryV2 N seconds|minutes|hours|days|weeks
2788 Minimum uptime of a v2 hidden service directory to be accepted as
2789 such by authoritative directories. (Default: 25 hours)
2790 RecommendedServerVersions STRING
2792 STRING is a comma-separated list of Tor versions currently believed
2793 to be safe for servers to use. This information is included in
2794 version 2 directories. If this is not set then the value of
2795 RecommendedVersions is used. When this is set then
2796 VersioningAuthoritativeDirectory should be set too.
2797 ConsensusParams STRING
2799 STRING is a space-separated list of key=value pairs that Tor will
2800 include in the "params" line of its networkstatus vote.
2801 DirAllowPrivateAddresses 0|1
2803 If set to 1, Tor will accept server descriptors with arbitrary
2804 "Address" elements. Otherwise, if the address is not an IP address
2805 or is a private IP address, it will reject the server descriptor.
2806 Additionally, Tor will allow exit policies for private networks to
2807 fulfill Exit flag requirements. (Default: 0)
2808 AuthDirBadExit AddressPattern...
2810 Authoritative directories only. A set of address patterns for
2811 servers that will be listed as bad exits in any network status
2812 document this authority publishes, if AuthDirListBadExits is set.
2813 (The address pattern syntax here and in the options below is the
2816 same as for exit policies, except that you don’t need to say
2817 "accept" or "reject", and ports are not needed.)
2818 AuthDirInvalid AddressPattern...
2820 Authoritative directories only. A set of address patterns for
2821 servers that will never be listed as "valid" in any network status
2822 document that this authority publishes.
2823 AuthDirReject AddressPattern...
2825 Authoritative directories only. A set of address patterns for
2826 servers that will never be listed at all in any network status
2827 document that this authority publishes, or accepted as an OR
2828 address in any descriptor submitted for publication by this
2829 authority.
2830 AuthDirBadExitCCs CC,...
2832 AuthDirInvalidCCs CC,...
2834 AuthDirRejectCCs CC,...
2836 Authoritative directories only. These options contain a
2837 comma-separated list of country codes such that any server in one
2838 of those country codes will be marked as a bad exit/invalid for
2839 use, or rejected entirely.
2840 AuthDirListBadExits 0|1
2842 Authoritative directories only. If set to 1, this directory has
2843 some opinion about which nodes are unsuitable as exit nodes. (Do
2844 not set this to 1 unless you plan to list non-functioning exits as
2845 bad; otherwise, you are effectively voting in favor of every
2846 declared exit as an exit.)
2847 AuthDirMaxServersPerAddr NUM
2849 Authoritative directories only. The maximum number of servers that
2850 we will list as acceptable on a single IP address. Set this to "0"
2851 for "no limit". (Default: 2)
2852 AuthDirFastGuarantee N
2854 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
2855 Authoritative directories only. If non-zero, always vote the Fast
2856 flag for any relay advertising this amount of capacity or more.
2857 (Default: 100 KBytes)
2858 AuthDirGuardBWGuarantee N
2860 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
2861 Authoritative directories only. If non-zero, this advertised
2862 capacity or more is always sufficient to satisfy the bandwidth
2863 requirement for the Guard flag. (Default: 2 MBytes)
2864 AuthDirPinKeys 0|1
2866 Authoritative directories only. If non-zero, do not allow any relay
2867 to publish a descriptor if any other relay has reserved its
2868 <Ed25519,RSA> identity keypair. In all cases, Tor records every
2869 keypair it accepts in a journal if it is new, or if it differs from
2870 the most recently accepted pinning for one of the keys it contains.
2871 (Default: 1)
2872 AuthDirSharedRandomness 0|1
2874 Authoritative directories only. Switch for the shared random
2875 protocol. If zero, the authority won’t participate in the protocol.
2876 If non-zero (default), the flag "shared-rand-participate" is added
2877 to the authority vote indicating participation in the protocol.
2878 (Default: 1)
2879 AuthDirTestEd25519LinkKeys 0|1
2881 Authoritative directories only. If this option is set to 0, then we
2882 treat relays as "Running" if their RSA key is correct when we probe
2883 them, regardless of their Ed25519 key. We should only ever set this
2884 option to 0 if there is some major bug in Ed25519 link
2885 authentication that causes us to label all the relays as not
2886 Running. (Default: 1)
2887 BridgePassword Password
2889 If set, contains an HTTP authenticator that tells a bridge
2890 authority to serve all requested bridge information. Used by the
2891 (only partially implemented) "bridge community" design, where a
2892 community of bridge relay operators all use an alternate bridge
2893 directory authority, and their target user audience can
2894 periodically fetch the list of available community bridges to stay
2895 up-to-date. (Default: not set)
2896 V3AuthVotingInterval N minutes|hours
2898 V3 authoritative directories only. Configures the server’s
2899 preferred voting interval. Note that voting will actually happen at
2900 an interval chosen by consensus from all the authorities' preferred
2901 intervals. This time SHOULD divide evenly into a day. (Default: 1
2902 hour)
2903 V3AuthVoteDelay N minutes|hours
2905 V3 authoritative directories only. Configures the server’s
2906 preferred delay between publishing its vote and assuming it has all
2907 the votes from all the other authorities. Note that the actual time
2908 used is not the server’s preferred time, but the consensus of all
2909 preferences. (Default: 5 minutes)
2910 V3AuthDistDelay N minutes|hours
2912 V3 authoritative directories only. Configures the server’s
2913 preferred delay between publishing its consensus and signature and
2914 assuming it has all the signatures from all the other authorities.
2915 Note that the actual time used is not the server’s preferred time,
2916 but the consensus of all preferences. (Default: 5 minutes)
2917 V3AuthNIntervalsValid NUM
2919 V3 authoritative directories only. Configures the number of
2920 VotingIntervals for which each consensus should be valid for.
2921 Choosing high numbers increases network partitioning risks;
2922 choosing low numbers increases directory traffic. Note that the
2923 actual number of intervals used is not the server’s preferred
2924 number, but the consensus of all preferences. Must be at least 2.
2925 (Default: 3)
2926 V3BandwidthsFile FILENAME
2928 V3 authoritative directories only. Configures the location of the
2929 bandwidth-authority generated file storing information on relays'
2930 measured bandwidth capacities. To avoid inconsistent reads,
2931 bandwidth data should be written to temporary file, then renamed to
2932 the configured filename. (Default: unset)
2933 V3AuthUseLegacyKey 0|1
2935 If set, the directory authority will sign consensuses not only with
2936 its own signing key, but also with a "legacy" key and certificate
2937 with a different identity. This feature is used to migrate
2938 directory authority keys in the event of a compromise. (Default: 0)
2939 AuthDirHasIPv6Connectivity 0|1
2941 Authoritative directories only. When set to 0, OR ports with an
2942 IPv6 address are not included in the authority’s votes. When set to
2943 1, IPv6 OR ports are tested for reachability like IPv4 OR ports. If
2944 the reachability test succeeds, the authority votes for the IPv6
2945 ORPort, and votes Running for the relay. If the reachability test
2946 fails, the authority does not vote for the IPv6 ORPort, and does
2947 not vote Running (Default: 0)
2948 The content of the consensus depends on the number of voting authorities
2951 that set AuthDirHasIPv6Connectivity:
2952 If no authorities set AuthDirHasIPv6Connectivity 1, there will be no
2954 IPv6 ORPorts in the consensus.
2955 If a minority of authorities set AuthDirHasIPv6Connectivity 1,
2957 unreachable IPv6 ORPorts will be removed from the consensus. But the
2958 majority of IPv4-only authorities will still vote the relay as Running.
2959 Reachable IPv6 ORPort lines will be included in the consensus
2960 If a majority of voting authorities set AuthDirHasIPv6Connectivity 1,
2962 relays with unreachable IPv6 ORPorts will not be listed as Running.
2963 Reachable IPv6 ORPort lines will be included in the consensus
2964 (To ensure that any valid majority will vote relays with unreachable
2965 IPv6 ORPorts not Running, 75% of authorities must set
2966 AuthDirHasIPv6Connectivity 1.)
2967 MinMeasuredBWsForAuthToIgnoreAdvertised N
2969 A total value, in abstract bandwidth units, describing how much
2970 measured total bandwidth an authority should have observed on the
2971 network before it will treat advertised bandwidths as wholly
2972 unreliable. (Default: 500)
2973
2975 The following options are used to configure a hidden service.
2976 HiddenServiceDir DIRECTORY
2978 Store data files for a hidden service in DIRECTORY. Every hidden
2979 service must have a separate directory. You may use this option
2980 multiple times to specify multiple services. If DIRECTORY does not
2981 exist, Tor will create it. (Note: in current versions of Tor, if
2982 DIRECTORY is a relative path, it will be relative to the current
2983 working directory of Tor instance, not to its DataDirectory. Do not
2984 rely on this behavior; it is not guaranteed to remain the same in
2985 future versions.)
2986 HiddenServicePort VIRTPORT [TARGET]
2988 Configure a virtual port VIRTPORT for a hidden service. You may use
2989 this option multiple times; each time applies to the service using
2990 the most recent HiddenServiceDir. By default, this option maps the
2991 virtual port to the same port on 127.0.0.1 over TCP. You may
2992 override the target port, address, or both by specifying a target
2993 of addr, port, addr:port, or unix:path. (You can specify an IPv6
2994 target as [addr]:port. Unix paths may be quoted, and may use
2995 standard C escapes.) You may also have multiple lines with the same
2996 VIRTPORT: when a user connects to that VIRTPORT, one of the TARGETs
2997 from those lines will be chosen at random. Note that address-port
2998 pairs have to be comma-separated.
2999 PublishHidServDescriptors 0|1
3001 If set to 0, Tor will run any hidden services you configure, but it
3002 won’t advertise them to the rendezvous directory. This option is
3003 only useful if you’re using a Tor controller that handles hidserv
3004 publishing for you. (Default: 1)
3005 HiddenServiceVersion 2|3
3007 A list of rendezvous service descriptor versions to publish for the
3008 hidden service. Currently, versions 2 and 3 are supported.
3009 (Default: 3)
3010 HiddenServiceAuthorizeClient auth-type client-name,client-name,...
3012 If configured, the hidden service is accessible for authorized
3013 clients only. The auth-type can either be 'basic' for a
3014 general-purpose authorization protocol or 'stealth' for a less
3015 scalable protocol that also hides service activity from
3016 unauthorized clients. Only clients that are listed here are
3017 authorized to access the hidden service. Valid client names are 1
3018 to 16 characters long and only use characters in A-Za-z0-9+-_ (no
3019 spaces). If this option is set, the hidden service is not
3020 accessible for clients without authorization any more. Generated
3021 authorization data can be found in the hostname file. Clients need
3022 to put this authorization data in their configuration file using
3023 HidServAuth. This option is only for v2 services; v3 services
3024 configure client authentication in a subdirectory of
3025 HiddenServiceDir instead (see the Client Authorization section).
3026 HiddenServiceAllowUnknownPorts 0|1
3028 If set to 1, then connections to unrecognized ports do not cause
3029 the current hidden service to close rendezvous circuits. (Setting
3030 this to 0 is not an authorization mechanism; it is instead meant to
3031 be a mild inconvenience to port-scanners.) (Default: 0)
3032 HiddenServiceExportCircuitID protocol
3034 The onion service will use the given protocol to expose the global
3035 circuit identifier of each inbound client circuit via the selected
3036 protocol. The only protocol supported right now 'haproxy'. This
3037 option is only for v3 services. (Default: none)
3038 The haproxy option works in the following way: when the feature is
3041 enabled, the Tor process will write a header line when a client is
3042 connecting to the onion service. The header will look like this:
3043 "PROXY TCP6 fc00:dead:beef:4dad::ffff:ffff ::1 65535 42\r\n"
3046 We encode the "global circuit identifier" as the last 32-bits of
3049 the first IPv6 address. All other values in the header can safely
3050 be ignored. You can compute the global circuit identifier using the
3051 following formula given the IPv6 address
3052 "fc00:dead:beef:4dad::AABB:CCDD":
3053 global_circuit_id = (0xAA << 24) + (0xBB << 16) + (0xCC << 8) +
3056 0xDD;
3057 In the case above, where the last 32-bit is 0xffffffff, the global
3060 circuit identifier would be 4294967295. You can use this value
3061 together with Tor’s control port where it is possible to terminate
3062 a circuit given the global circuit identifier. For more information
3063 about this see controls-spec.txt.
3064 The HAProxy version 1 proxy protocol is described in detail at
3067 https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
3068 HiddenServiceMaxStreams N
3070 The maximum number of simultaneous streams (connections) per
3071 rendezvous circuit. The maximum value allowed is 65535. (Setting
3072 this to 0 will allow an unlimited number of simultaneous streams.)
3073 (Default: 0)
3074 HiddenServiceMaxStreamsCloseCircuit 0|1
3076 If set to 1, then exceeding HiddenServiceMaxStreams will cause the
3077 offending rendezvous circuit to be torn down, as opposed to stream
3078 creation requests that exceed the limit being silently ignored.
3079 (Default: 0)
3080 RendPostPeriod N seconds|minutes|hours|days|weeks
3082 Every time the specified period elapses, Tor uploads any rendezvous
3083 service descriptors to the directory servers. This information is
3084 also uploaded whenever it changes. Minimum value allowed is 10
3085 minutes and maximum is 3.5 days. This option is only for v2
3086 services. (Default: 1 hour)
3087 HiddenServiceDirGroupReadable 0|1
3089 If this option is set to 1, allow the filesystem group to read the
3090 hidden service directory and hostname file. If the option is set to
3091 0, only owner is able to read the hidden service directory.
3092 (Default: 0) Has no effect on Windows.
3093 HiddenServiceNumIntroductionPoints NUM
3095 Number of introduction points the hidden service will have. You
3096 can’t have more than 10 for v2 service and 20 for v3. (Default: 3)
3097 HiddenServiceSingleHopMode 0|1
3099 Experimental - Non Anonymous Hidden Services on a tor instance in
3100 HiddenServiceSingleHopMode make one-hop (direct) circuits between
3101 the onion service server, and the introduction and rendezvous
3102 points. (Onion service descriptors are still posted using 3-hop
3103 paths, to avoid onion service directories blocking the service.)
3104 This option makes every hidden service instance hosted by a tor
3105 instance a Single Onion Service. One-hop circuits make Single Onion
3106 servers easily locatable, but clients remain location-anonymous.
3107 However, the fact that a client is accessing a Single Onion rather
3108 than a Hidden Service may be statistically distinguishable.
3109 WARNING: Once a hidden service directory has been used by a tor
3112 instance in HiddenServiceSingleHopMode, it can NEVER be used again
3113 for a hidden service. It is best practice to create a new hidden
3114 service directory, key, and address for each new Single Onion
3115 Service and Hidden Service. It is not possible to run Single Onion
3116 Services and Hidden Services from the same tor instance: they
3117 should be run on different servers with different IP addresses.
3118 HiddenServiceSingleHopMode requires HiddenServiceNonAnonymousMode
3121 to be set to 1. Since a Single Onion service is non-anonymous, you
3122 can not configure a SOCKSPort on a tor instance that is running in
3123 HiddenServiceSingleHopMode. Can not be changed while tor is
3124 running. (Default: 0)
3125 HiddenServiceNonAnonymousMode 0|1
3127 Makes hidden services non-anonymous on this tor instance. Allows
3128 the non-anonymous HiddenServiceSingleHopMode. Enables direct
3129 connections in the server-side hidden service protocol. If you are
3130 using this option, you need to disable all client-side services on
3131 your Tor instance, including setting SOCKSPort to "0". Can not be
3132 changed while tor is running. (Default: 0)
3133
3135 (Version 3 only)
3136 To configure client authorization on the service side, the
3138 "<HiddenServiceDir>/authorized_clients/" directory needs to exist. Each
3139 file in that directory should be suffixed with ".auth" (i.e.
3140 "alice.auth"; the file name is irrelevant) and its content format MUST
3141 be:
3142 <auth-type>:<key-type>:<base32-encoded-public-key>
3144 The supported <auth-type> are: "descriptor". The supported <key-type>
3146 are: "x25519". The <base32-encoded-public-key> is the base32
3147 representation of the raw key bytes only (32 bytes for x25519).
3148 Each file MUST contain one line only. Any malformed file will be
3150 ignored. Client authorization will only be enabled for the service if
3151 tor successfully loads at least one authorization file.
3152 Note that once you’ve configured client authorization, anyone else with
3154 the address won’t be able to access it from this point on. If no
3155 authorization is configured, the service will be accessible to anyone
3156 with the onion address.
3157 Revoking a client can be done by removing their ".auth" file, however
3159 the revocation will be in effect only after the tor process gets
3160 restarted even if a SIGHUP takes place.
3161 See the Appendix G in the rend-spec-v3.txt file of torspec for more
3163 information.
3164
3166 The following options are used for running a testing Tor network.
3167 TestingTorNetwork 0|1
3169 If set to 1, Tor adjusts default values of the configuration
3170 options below, so that it is easier to set up a testing Tor
3171 network. May only be set if non-default set of DirAuthorities is
3172 set. Cannot be unset while Tor is running. (Default: 0)
3173 ServerDNSAllowBrokenConfig 1
3176 DirAllowPrivateAddresses 1
3177 EnforceDistinctSubnets 0
3178 AssumeReachable 1
3179 AuthDirMaxServersPerAddr 0
3180 AuthDirMaxServersPerAuthAddr 0
3181 ClientBootstrapConsensusAuthorityDownloadInitialDelay 0
3182 ClientBootstrapConsensusFallbackDownloadInitialDelay 0
3183 ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay 0
3184 ClientDNSRejectInternalAddresses 0
3185 ClientRejectInternalAddresses 0
3186 CountPrivateBandwidth 1
3187 ExitPolicyRejectPrivate 0
3188 ExtendAllowPrivateAddresses 1
3189 V3AuthVotingInterval 5 minutes
3190 V3AuthVoteDelay 20 seconds
3191 V3AuthDistDelay 20 seconds
3192 MinUptimeHidServDirectoryV2 0 seconds
3193 TestingV3AuthInitialVotingInterval 5 minutes
3194 TestingV3AuthInitialVoteDelay 20 seconds
3195 TestingV3AuthInitialDistDelay 20 seconds
3196 TestingAuthDirTimeToLearnReachability 0 minutes
3197 TestingEstimatedDescriptorPropagationTime 0 minutes
3198 TestingServerDownloadInitialDelay 0
3199 TestingClientDownloadInitialDelay 0
3200 TestingServerConsensusDownloadInitialDelay 0
3201 TestingClientConsensusDownloadInitialDelay 0
3202 TestingBridgeDownloadInitialDelay 10
3203 TestingBridgeBootstrapDownloadInitialDelay 0
3204 TestingClientMaxIntervalWithoutRequest 5 seconds
3205 TestingDirConnectionMaxStall 30 seconds
3206 TestingEnableConnBwEvent 1
3207 TestingEnableCellStatsEvent 1
3208 TestingV3AuthInitialVotingInterval N minutes|hours
3210 Like V3AuthVotingInterval, but for initial voting interval before
3211 the first consensus has been created. Changing this requires that
3212 TestingTorNetwork is set. (Default: 30 minutes)
3213 TestingV3AuthInitialVoteDelay N minutes|hours
3215 Like V3AuthVoteDelay, but for initial voting interval before the
3216 first consensus has been created. Changing this requires that
3217 TestingTorNetwork is set. (Default: 5 minutes)
3218 TestingV3AuthInitialDistDelay N minutes|hours
3220 Like V3AuthDistDelay, but for initial voting interval before the
3221 first consensus has been created. Changing this requires that
3222 TestingTorNetwork is set. (Default: 5 minutes)
3223 TestingV3AuthVotingStartOffset N seconds|minutes|hours
3225 Directory authorities offset voting start time by this much.
3226 Changing this requires that TestingTorNetwork is set. (Default: 0)
3227 TestingAuthDirTimeToLearnReachability N minutes|hours
3229 After starting as an authority, do not make claims about whether
3230 routers are Running until this much time has passed. Changing this
3231 requires that TestingTorNetwork is set. (Default: 30 minutes)
3232 TestingEstimatedDescriptorPropagationTime N minutes|hours
3234 Clients try downloading server descriptors from directory caches
3235 after this time. Changing this requires that TestingTorNetwork is
3236 set. (Default: 10 minutes)
3237 TestingMinFastFlagThreshold N
3239 bytes|KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3240 Minimum value for the Fast flag. Overrides the ordinary minimum
3241 taken from the consensus when TestingTorNetwork is set. (Default:
3242 0.)
3243 TestingServerDownloadInitialDelay N
3245 Initial delay in seconds for when servers should download things in
3246 general. Changing this requires that TestingTorNetwork is set.
3247 (Default: 0)
3248 TestingClientDownloadInitialDelay N
3250 Initial delay in seconds for when clients should download things in
3251 general. Changing this requires that TestingTorNetwork is set.
3252 (Default: 0)
3253 TestingServerConsensusDownloadInitialDelay N
3255 Initial delay in seconds for when servers should download
3256 consensuses. Changing this requires that TestingTorNetwork is set.
3257 (Default: 0)
3258 TestingClientConsensusDownloadInitialDelay N
3260 Initial delay in seconds for when clients should download
3261 consensuses. Changing this requires that TestingTorNetwork is set.
3262 (Default: 0)
3263 TestingBridgeDownloadInitialDelay N
3265 Initial delay in seconds for when clients should download each
3266 bridge descriptor when they know that one or more of their
3267 configured bridges are running. Changing this requires that
3268 TestingTorNetwork is set. (Default: 10800)
3269 TestingBridgeBootstrapDownloadInitialDelay N
3271 Initial delay in seconds for when clients should download each
3272 bridge descriptor when they have just started, or when they can not
3273 contact any of their bridges. Changing this requires that
3274 TestingTorNetwork is set. (Default: 0)
3275 TestingClientMaxIntervalWithoutRequest N seconds|minutes
3277 When directory clients have only a few descriptors to request, they
3278 batch them until they have more, or until this amount of time has
3279 passed. Changing this requires that TestingTorNetwork is set.
3280 (Default: 10 minutes)
3281 TestingDirConnectionMaxStall N seconds|minutes
3283 Let a directory connection stall this long before expiring it.
3284 Changing this requires that TestingTorNetwork is set. (Default: 5
3285 minutes)
3286 TestingDirAuthVoteExit node,node,...
3288 A list of identity fingerprints, country codes, and address
3289 patterns of nodes to vote Exit for regardless of their uptime,
3290 bandwidth, or exit policy. See the ExcludeNodes option for more
3291 information on how to specify nodes.
3292 In order for this option to have any effect, TestingTorNetwork has
3295 to be set. See the ExcludeNodes option for more information on how
3296 to specify nodes.
3297 TestingDirAuthVoteExitIsStrict 0|1
3299 If True (1), a node will never receive the Exit flag unless it is
3300 specified in the TestingDirAuthVoteExit list, regardless of its
3301 uptime, bandwidth, or exit policy.
3302 In order for this option to have any effect, TestingTorNetwork has
3305 to be set.
3306 TestingDirAuthVoteGuard node,node,...
3308 A list of identity fingerprints and country codes and address
3309 patterns of nodes to vote Guard for regardless of their uptime and
3310 bandwidth. See the ExcludeNodes option for more information on how
3311 to specify nodes.
3312 In order for this option to have any effect, TestingTorNetwork has
3315 to be set.
3316 TestingDirAuthVoteGuardIsStrict 0|1
3318 If True (1), a node will never receive the Guard flag unless it is
3319 specified in the TestingDirAuthVoteGuard list, regardless of its
3320 uptime and bandwidth.
3321 In order for this option to have any effect, TestingTorNetwork has
3324 to be set.
3325 TestingDirAuthVoteHSDir node,node,...
3327 A list of identity fingerprints and country codes and address
3328 patterns of nodes to vote HSDir for regardless of their uptime and
3329 DirPort. See the ExcludeNodes option for more information on how to
3330 specify nodes.
3331 In order for this option to have any effect, TestingTorNetwork must
3334 be set.
3335 TestingDirAuthVoteHSDirIsStrict 0|1
3337 If True (1), a node will never receive the HSDir flag unless it is
3338 specified in the TestingDirAuthVoteHSDir list, regardless of its
3339 uptime and DirPort.
3340 In order for this option to have any effect, TestingTorNetwork has
3343 to be set.
3344 TestingEnableConnBwEvent 0|1
3346 If this option is set, then Tor controllers may register for
3347 CONN_BW events. Changing this requires that TestingTorNetwork is
3348 set. (Default: 0)
3349 TestingEnableCellStatsEvent 0|1
3351 If this option is set, then Tor controllers may register for
3352 CELL_STATS events. Changing this requires that TestingTorNetwork is
3353 set. (Default: 0)
3354 TestingMinExitFlagThreshold N
3356 KBytes|MBytes|GBytes|TBytes|KBits|MBits|GBits|TBits
3357 Sets a lower-bound for assigning an exit flag when running as an
3358 authority on a testing network. Overrides the usual default lower
3359 bound of 4 KB. (Default: 0)
3360 TestingLinkCertLifetime N seconds|minutes|hours|days|weeks|months
3362 Overrides the default lifetime for the certificates used to
3363 authenticate our X509 link cert with our ed25519 signing key.
3364 (Default: 2 days)
3365 TestingAuthKeyLifetime N seconds|minutes|hours|days|weeks|months
3367 Overrides the default lifetime for a signing Ed25519 TLS Link
3368 authentication key. (Default: 2 days)
3369 TestingLinkKeySlop N seconds|minutes|hours
3371 TestingAuthKeySlop N seconds|minutes|hours
3373 TestingSigningKeySlop N seconds|minutes|hours
3375 How early before the official expiration of a an Ed25519 signing
3376 key do we replace it and issue a new key? (Default: 3 hours for
3377 link and auth; 1 day for signing.)
3378
3380 These options are not saved to the torrc file by the "SAVECONF"
3381 controller command. Other options of this type are documented in
3382 control-spec.txt, section 5.4. End-users should mostly ignore them.
3383 __ControlPort, __DirPort, __DNSPort, __ExtORPort, __NATDPort, __ORPort,
3385 __SocksPort, \_\_TransPort
3386 These underscore-prefixed options are variants of the regular Port
3387 options. They behave the same, except they are not saved to the
3388 torrc file by the controller’s SAVECONF command.
3389
3391 Tor catches the following signals:
3392 SIGTERM
3394 Tor will catch this, clean up and sync to disk if necessary, and
3395 exit.
3396 SIGINT
3398 Tor clients behave as with SIGTERM; but Tor servers will do a
3399 controlled slow shutdown, closing listeners and waiting 30 seconds
3400 before exiting. (The delay can be configured with the
3401 ShutdownWaitLength config option.)
3402 SIGHUP
3404 The signal instructs Tor to reload its configuration (including
3405 closing and reopening logs), and kill and restart its helper
3406 processes if applicable.
3407 SIGUSR1
3409 Log statistics about current connections, past connections, and
3410 throughput.
3411 SIGUSR2
3413 Switch all logs to loglevel debug. You can go back to the old
3414 loglevels by sending a SIGHUP.
3415 SIGCHLD
3417 Tor receives this signal when one of its helper processes has
3418 exited, so it can clean up.
3419 SIGPIPE
3421 Tor catches this signal and ignores it.
3422 SIGXFSZ
3424 If this signal exists on your platform, Tor catches and ignores it.
3425
3427 /etc/tor/torrc
3428 The configuration file, which contains "option value" pairs.
3429 $HOME/.torrc
3431 Fallback location for torrc, if /etc/tor/torrc is not found.
3432 /var/lib/tor/
3434 The tor process stores keys and other data here.
3435 CacheDirectory/cached-certs
3437 This file holds downloaded directory key certificates that are used
3438 to verify authenticity of documents generated by Tor directory
3439 authorities.
3440 CacheDirectory/cached-consensus and/or cached-microdesc-consensus
3442 The most recent consensus network status document we’ve downloaded.
3443 CacheDirectory/cached-descriptors and cached-descriptors.new
3445 These files hold downloaded router statuses. Some routers may
3446 appear more than once; if so, the most recently published
3447 descriptor is used. Lines beginning with @-signs are annotations
3448 that contain more information about a given router. The ".new" file
3449 is an append-only journal; when it gets too large, all entries are
3450 merged into a new cached-descriptors file.
3451 CacheDirectory/cached-extrainfo and cached-extrainfo.new
3453 As "cached-descriptors", but holds optionally-downloaded
3454 "extra-info" documents. Relays use these documents to send
3455 inessential information about statistics, bandwidth history, and
3456 network health to the authorities. They aren’t fetched by default;
3457 see the DownloadExtraInfo option for more info.
3458 CacheDirectory/cached-microdescs and cached-microdescs.new
3460 These files hold downloaded microdescriptors. Lines beginning with
3461 @-signs are annotations that contain more information about a given
3462 router. The ".new" file is an append-only journal; when it gets too
3463 large, all entries are merged into a new cached-microdescs file.
3464 CacheDirectory/cached-routers and cached-routers.new
3466 Obsolete versions of cached-descriptors and cached-descriptors.new.
3467 When Tor can’t find the newer files, it looks here instead.
3468 DataDirectory/state
3470 A set of persistent key-value mappings. These are documented in the
3471 file. These include:
3472 · The current entry guards and their status.
3474 · The current bandwidth accounting values.
3476 · When the file was last written
3478 · What version of Tor generated the state file
3480 · A short history of bandwidth usage, as produced in the server
3482 descriptors.
3483 DataDirectory/sr-state
3485 Authority only. State file used to record information about the
3486 current status of the shared-random-value voting state.
3487 CacheDirectory/diff-cache
3489 Directory cache only. Holds older consensuses, and diffs from older
3490 consensuses to the most recent consensus of each type, compressed
3491 in various ways. Each file contains a set of key-value arguments
3492 describing its contents, followed by a single NUL byte, followed by
3493 the main file contents.
3494 DataDirectory/bw_accounting
3496 Used to track bandwidth accounting values (when the current period
3497 starts and ends; how much has been read and written so far this
3498 period). This file is obsolete, and the data is now stored in the
3499 'state' file instead.
3500 DataDirectory/control_auth_cookie
3502 Used for cookie authentication with the controller. Location can be
3503 overridden by the CookieAuthFile config option. Regenerated on
3504 startup. See control-spec.txt in torspec for details. Only used
3505 when cookie authentication is enabled.
3506 DataDirectory/lock
3508 This file is used to prevent two Tor instances from using same data
3509 directory. If access to this file is locked, data directory is
3510 already in use by Tor.
3511 DataDirectory/key-pinning-journal
3513 Used by authorities. A line-based file that records mappings
3514 between RSA1024 identity keys and Ed25519 identity keys.
3515 Authorities enforce these mappings, so that once a relay has picked
3516 an Ed25519 key, stealing or factoring the RSA1024 key will no
3517 longer let an attacker impersonate the relay.
3518 KeyDirectory/authority_identity_key
3520 A v3 directory authority’s master identity key, used to
3521 authenticate its signing key. Tor doesn’t use this while it’s
3522 running. The tor-gencert program uses this. If you’re running an
3523 authority, you should keep this key offline, and not actually put
3524 it here.
3525 KeyDirectory/authority_certificate
3527 A v3 directory authority’s certificate, which authenticates the
3528 authority’s current vote- and consensus-signing key using its
3529 master identity key. Only directory authorities use this file.
3530 KeyDirectory/authority_signing_key
3532 A v3 directory authority’s signing key, used to sign votes and
3533 consensuses. Only directory authorities use this file. Corresponds
3534 to the authority_certificate cert.
3535 KeyDirectory/legacy_certificate
3537 As authority_certificate: used only when V3AuthUseLegacyKey is set.
3538 See documentation for V3AuthUseLegacyKey.
3539 KeyDirectory/legacy_signing_key
3541 As authority_signing_key: used only when V3AuthUseLegacyKey is set.
3542 See documentation for V3AuthUseLegacyKey.
3543 KeyDirectory/secret_id_key
3545 A relay’s RSA1024 permanent identity key, including private and
3546 public components. Used to sign router descriptors, and to sign
3547 other keys.
3548 KeyDirectory/ed25519_master_id_public_key
3550 The public part of a relay’s Ed25519 permanent identity key.
3551 KeyDirectory/ed25519_master_id_secret_key
3553 The private part of a relay’s Ed25519 permanent identity key. This
3554 key is used to sign the medium-term ed25519 signing key. This file
3555 can be kept offline, or kept encrypted. If so, Tor will not be able
3556 to generate new signing keys itself; you’ll need to use tor
3557 --keygen yourself to do so.
3558 KeyDirectory/ed25519_signing_secret_key
3560 The private and public components of a relay’s medium-term Ed25519
3561 signing key. This key is authenticated by the Ed25519 master key,
3562 in turn authenticates other keys (and router descriptors).
3563 KeyDirectory/ed25519_signing_cert
3565 The certificate which authenticates "ed25519_signing_secret_key" as
3566 having been signed by the Ed25519 master key.
3567 KeyDirectory/secret_onion_key and secret_onion_key.old
3569 A relay’s RSA1024 short-term onion key. Used to decrypt old-style
3570 ("TAP") circuit extension requests. The ".old" file holds the
3571 previously generated key, which the relay uses to handle any
3572 requests that were made by clients that didn’t have the new one.
3573 KeyDirectory/secret_onion_key_ntor and secret_onion_key_ntor.old
3575 A relay’s Curve25519 short-term onion key. Used to handle modern
3576 ("ntor") circuit extension requests. The ".old" file holds the
3577 previously generated key, which the relay uses to handle any
3578 requests that were made by clients that didn’t have the new one.
3579 DataDirectory/fingerprint
3581 Only used by servers. Holds the fingerprint of the server’s
3582 identity key.
3583 DataDirectory/hashed-fingerprint
3585 Only used by bridges. Holds the hashed fingerprint of the bridge’s
3586 identity key. (That is, the hash of the hash of the identity key.)
3587 DataDirectory/approved-routers
3589 Only used by authoritative directory servers. This file lists the
3590 status of routers by their identity fingerprint. Each line lists a
3591 status and a fingerprint separated by whitespace. See your
3592 fingerprint file in the DataDirectory for an example line. If the
3593 status is !reject then descriptors from the given identity
3594 (fingerprint) are rejected by this server. If it is !invalid then
3595 descriptors are accepted but marked in the directory as not valid,
3596 that is, not recommended.
3597 DataDirectory/v3-status-votes
3599 Only for v3 authoritative directory servers. This file contains
3600 status votes from all the authoritative directory servers.
3601 CacheDirectory/unverified-consensus
3603 This file contains a network consensus document that has been
3604 downloaded, but which we didn’t have the right certificates to
3605 check yet.
3606 CacheDirectory/unverified-microdesc-consensus
3608 This file contains a microdescriptor-flavored network consensus
3609 document that has been downloaded, but which we didn’t have the
3610 right certificates to check yet.
3611 DataDirectory/unparseable-desc
3613 Onion server descriptors that Tor was unable to parse are dumped to
3614 this file. Only used for debugging.
3615 DataDirectory/router-stability
3617 Only used by authoritative directory servers. Tracks measurements
3618 for router mean-time-between-failures so that authorities have a
3619 good idea of how to set their Stable flags.
3620 DataDirectory/stats/dirreq-stats
3622 Only used by directory caches and authorities. This file is used to
3623 collect directory request statistics.
3624 DataDirectory/stats/entry-stats
3626 Only used by servers. This file is used to collect incoming
3627 connection statistics by Tor entry nodes.
3628 DataDirectory/stats/bridge-stats
3630 Only used by servers. This file is used to collect incoming
3631 connection statistics by Tor bridges.
3632 DataDirectory/stats/exit-stats
3634 Only used by servers. This file is used to collect outgoing
3635 connection statistics by Tor exit routers.
3636 DataDirectory/stats/buffer-stats
3638 Only used by servers. This file is used to collect buffer usage
3639 history.
3640 DataDirectory/stats/conn-stats
3642 Only used by servers. This file is used to collect approximate
3643 connection history (number of active connections over time).
3644 DataDirectory/stats/hidserv-stats
3646 Only used by servers. This file is used to collect approximate
3647 counts of what fraction of the traffic is hidden service rendezvous
3648 traffic, and approximately how many hidden services the relay has
3649 seen.
3650 DataDirectory/networkstatus-bridges
3652 Only used by authoritative bridge directories. Contains information
3653 about bridges that have self-reported themselves to the bridge
3654 authority.
3655 DataDirectory/approved-routers
3657 Authorities only. This file is used to configure which relays are
3658 known to be valid, invalid, and so forth.
3659 HiddenServiceDirectory/hostname
3661 The <base32-encoded-fingerprint>.onion domain name for this hidden
3662 service. If the hidden service is restricted to authorized clients
3663 only, this file also contains authorization data for all clients.
3664 Note that clients will ignore any extra subdomains prepended to a
3666 hidden service hostname. So if you have "xyz.onion" as your
3667 hostname, you can tell clients to connect to "www.xyz.onion" or
3668 "irc.xyz.onion" for virtual-hosting purposes.
3669 HiddenServiceDirectory/private_key
3671 The private key for this hidden service.
3672 HiddenServiceDirectory/client_keys
3674 Authorization data for a hidden service that is only accessible by
3675 authorized clients.
3676 HiddenServiceDirectory/onion_service_non_anonymous
3678 This file is present if a hidden service key was created in
3679 HiddenServiceNonAnonymousMode.
3680
3682 torsocks(1), torify(1)
3683 https://www.torproject.org/
3685 torspec: https://spec.torproject.org
3687
3689 Plenty, probably. Tor is still in development. Please report them at
3690 https://trac.torproject.org/.
3691
3693 Roger Dingledine [arma at mit.edu], Nick Mathewson [nickm at
3694 alum.mit.edu].
3695Tor 02/21/2019 TOR(1)