diff options
Diffstat (limited to 'doc/tor.1.txt')
| -rw-r--r-- | doc/tor.1.txt | 837 |
1 files changed, 622 insertions, 215 deletions
diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 8d51f6e3c2..74915b7119 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -30,7 +30,7 @@ Users bounce their TCP streams -- web traffic, ftp, ssh, etc. -- around the network, and recipients, observers, and even the relays themselves have difficulty tracking the source of the stream. -By default, **tor** will only act as a client only. To help the network +By default, **tor** will act as a client only. To help the network by providing bandwidth as a relay, change the **ORPort** configuration option -- see below. Please also consult the documentation on the Tor Project's website. @@ -42,7 +42,8 @@ COMMAND-LINE OPTIONS [[opt-f]] **-f** __FILE__:: Specify a new configuration file to contain further Tor configuration - options. (Default: @CONFDIR@/torrc, or $HOME/.torrc if that file is not + options OR pass *-* to make Tor read its configuration from standard + input. (Default: @CONFDIR@/torrc, or $HOME/.torrc if that file is not found) [[opt-allow-missing-torrc]] **--allow-missing-torrc**:: @@ -72,7 +73,7 @@ COMMAND-LINE OPTIONS [[opt-serviceinstall]] **--service install** [**--options** __command-line options__]:: Install an instance of Tor as a Windows service, with the provided command-line options. Current instructions can be found at - https://trac.torproject.org/projects/tor/wiki/doc/TorFAQ#HowdoIrunmyTorrelayasanNTservice + https://www.torproject.org/docs/faq#NTService [[opt-service]] **--service** **remove**|**start**|**stop**:: Remove, start, or stop a configured Tor Windows service. @@ -94,11 +95,34 @@ COMMAND-LINE OPTIONS which tells Tor to only send warnings and errors to the console, or with the **--quiet** option, which tells Tor not to log to the console at all. +[[opt-keygen]] **--keygen** [**--newpass**]:: + Running "tor --keygen" creates a new ed25519 master identity key for a + relay, or only a fresh temporary signing key and certificate, if you + already have a master key. Optionally you can encrypt the master identity + key with a passphrase: Tor will ask you for one. If you don't want to + encrypt the master key, just don't enter any passphrase when asked. + + + + The **--newpass** option should be used with --keygen only when you need + to add, change, or remove a passphrase on an existing ed25519 master + identity key. You will be prompted for the old passphase (if any), + and the new passphrase (if any). + + + + When generating a master key, you will probably want to use + **--DataDirectory** to control where the keys + and certificates will be stored, and **--SigningKeyLifetime** to + control their lifetimes. Their behavior is as documented in the + server options section below. (You must have write access to the specified + DataDirectory.) + + + + To use the generated files, you must copy them to the DataDirectory/keys + directory of your Tor daemon, and make sure that they are owned by the + user actually running the Tor daemon on your system. + Other options can be specified on the command-line in the format "--option value", in the format "option value", or in a configuration file. For instance, you can tell Tor to start listening for SOCKS connections on port -9999 by passing --SOCKSPort 9999 or SOCKSPort 9999 to it on the command line, -or by putting "SOCKSPort 9999" in the configuration file. You will need to +9999 by passing --SocksPort 9999 or SocksPort 9999 to it on the command line, +or by putting "SocksPort 9999" in the configuration file. You will need to quote options with spaces in them: if you want Tor to log all debugging messages to debug.log, you will probably need to say --Log 'debug file debug.log'. @@ -124,26 +148,31 @@ the defaults file. This rule is simple for options that take a single value, but it can become complicated for options that are allowed to occur more than once: if you -specify four SOCKSPorts in your configuration file, and one more SOCKSPort on +specify four SocksPorts in your configuration file, and one more SocksPort on the command line, the option on the command line will replace __all__ of the -SOCKSPorts in the configuration file. If this isn't what you want, prefix -the option name with a plus sign, and it will be appended to the previous set -of options instead. +SocksPorts in the configuration file. If this isn't what you want, prefix +the option name with a plus sign (+), and it will be appended to the previous +set of options instead. For example, setting SocksPort 9100 will use only +port 9100, but setting +SocksPort 9100 will use ports 9100 and 9050 (because +this is the default). Alternatively, you might want to remove every instance of an option in the configuration file, and not replace it at all: you might want to say on the -command line that you want no SOCKSPorts at all. To do that, prefix the -option name with a forward slash. +command line that you want no SocksPorts at all. To do that, prefix the +option name with a forward slash (/). You can use the plus sign (+) and the +forward slash (/) in the configuration file and on the command line. GENERAL OPTIONS --------------- [[BandwidthRate]] **BandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: - A token bucket limits the average incoming bandwidth usage on this node to - the specified number of bytes per second, and the average outgoing + A token bucket limits the average incoming bandwidth usage on this node + to the specified number of bytes per second, and the average outgoing bandwidth usage to that same value. If you want to run a relay in the - public network, this needs to be _at the very least_ 30 KBytes (that is, - 30720 bytes). (Default: 1 GByte) + + public network, this needs to be _at the very least_ 75 KBytes for a + relay (that is, 600 kbits) or 50 KBytes for a bridge (400 kbits) -- but of + course, more is better; we recommend at least 250 KBytes (2 mbits) if + possible. (Default: 1 GByte) + + With this option, and in other options that take arguments in bytes, KBytes, and so on, other formats are also supported. Notably, "KBytes" can @@ -215,7 +244,7 @@ GENERAL OPTIONS any pluggable transport proxy that tries to launch __transport__. + (Example: ServerTransportOptions obfs45 shared-secret=bridgepasswd cache=/var/lib/tor/cache) -[[ExtORPort]] **ExtORPort** \['address':]__port__|**auto** +[[ExtORPort]] **ExtORPort** \['address':]__port__|**auto**:: Open this port to listen for Extended ORPort connections from your pluggable transports. @@ -273,16 +302,28 @@ GENERAL OPTIONS all sockets will be set to this limit. Must be a value between 2048 and 262144, in 1024 byte increments. Default of 8192 is recommended. -[[ControlPort]] **ControlPort** __PORT__|**auto**:: +[[ControlPort]] **ControlPort** __PORT__|**unix:**__path__|**auto** [__flags__]:: If set, Tor will accept connections on this port and allow those connections to control the Tor process using the Tor Control Protocol - (described in control-spec.txt). Note: unless you also specify one or - more of **HashedControlPassword** or **CookieAuthentication**, - setting this option will cause Tor to allow any process on the local - host to control it. (Setting both authentication methods means either - method is sufficient to authenticate to Tor.) This + (described in control-spec.txt in + https://spec.torproject.org[torspec]). Note: unless you also + specify one or more of **HashedControlPassword** or + **CookieAuthentication**, setting this option will cause Tor to allow + any process on the local host to control it. (Setting both authentication + methods means eithermethod is sufficient to authenticate to Tor.) This option is required for many Tor controllers; most use the value of 9051. - Set it to "auto" to have Tor pick a port for you. (Default: 0) + Set it to "auto" to have Tor pick a port for you. (Default: 0) + + + + Recognized flags are... + **GroupWritable**;; + Unix domain sockets only: makes the socket get created as + group-writable. + **WorldWritable**;; + Unix domain sockets only: makes the socket get created as + world-writable. + **RelaxDirModeCheck**;; + Unix domain sockets only: Do not insist that the directory + that holds the socket be read-restricted. [[ControlListenAddress]] **ControlListenAddress** __IP__[:__PORT__]:: Bind the controller listener to this address. If you specify a port, bind @@ -294,7 +335,7 @@ GENERAL OPTIONS [[ControlSocket]] **ControlSocket** __Path__:: Like ControlPort, but listens on a Unix domain socket, rather than a TCP - socket. (Unix and Unix-like systems only.) + socket. '0' disables ControlSocket (Unix and Unix-like systems only.) [[ControlSocketsGroupWritable]] **ControlSocketsGroupWritable** **0**|**1**:: If this option is set to 0, don't allow the filesystem group to read and @@ -338,10 +379,26 @@ GENERAL OPTIONS [[DataDirectory]] **DataDirectory** __DIR__:: Store working data in DIR (Default: @LOCALSTATEDIR@/lib/tor) -[[FallbackDir]] **FallbackDir** __address__:__port__ orport=__port__ id=__fingerprint__ [weight=__num__]:: +[[DataDirectoryGroupReadable]] **DataDirectoryGroupReadable** **0**|**1**:: + If this option is set to 0, don't allow the filesystem group to read the + DataDirectory. If the option is set to 1, make the DataDirectory readable + by the default GID. (Default: 0) + +[[FallbackDir]] **FallbackDir** __address__:__port__ orport=__port__ id=__fingerprint__ [weight=__num__] [ipv6=__address__:__orport__]:: When we're unable to connect to any directory cache for directory info - (usually because we don't know about any yet) we try a FallbackDir. - By default, the directory authorities are also FallbackDirs. + (usually because we don't know about any yet) we try a directory authority. + Clients also simultaneously try a FallbackDir, to avoid hangs on client + startup if a directory authority is down. Clients retry FallbackDirs more + often than directory authorities, to reduce the load on the directory + authorities. + By default, the directory authorities are also FallbackDirs. Specifying a + FallbackDir replaces Tor's default hard-coded FallbackDirs (if any). + (See the **DirAuthority** entry for an explanation of each flag.) + +[[UseDefaultFallbackDirs]] **UseDefaultFallbackDirs** **0**|**1**:: + Use Tor's default hard-coded FallbackDirs (if any). (When a + FallbackDir line is present, it replaces the hard-coded FallbackDirs, + regardless of the value of UseDefaultFallbackDirs.) (Default: 1) [[DirAuthority]] **DirAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__:: Use a nonstandard authoritative directory server at the provided address @@ -354,9 +411,16 @@ GENERAL OPTIONS "bridge" flag is set. If a flag "orport=**port**" is given, Tor will use the given port when opening encrypted tunnels to the dirserver. If a flag "weight=**num**" is given, then the directory server is chosen randomly - with probability proportional to that weight (default 1.0). Lastly, if a + with probability proportional to that weight (default 1.0). If a flag "v3ident=**fp**" is given, the dirserver is a v3 directory authority - whose v3 long-term signing key has the fingerprint **fp**. + + whose v3 long-term signing key has the fingerprint **fp**. Lastly, + if an "ipv6=__address__:__orport__" flag is present, then the directory + authority is listening for IPv6 connections on the indicated IPv6 address + and OR Port. + + + + Tor will contact the authority at __address__:__port__ (the DirPort) to + download directory documents. If an IPv6 address is supplied, Tor will + also download directory documents at the IPv6 address on the DirPort. + + If no **DirAuthority** line is given, Tor will use the default directory authorities. NOTE: this option is intended for setting up a private Tor @@ -370,12 +434,6 @@ GENERAL OPTIONS chosen with their regular weights, multiplied by this number, which should be 1.0 or less. (Default: 1.0) -[[DynamicDHGroups]] **DynamicDHGroups** **0**|**1**:: - If this option is set to 1, when running as a server, generate our - own Diffie-Hellman group instead of using the one from Apache's mod_ssl. - This option may help circumvent censorship based on static - Diffie-Hellman parameters. (Default: 0) - [[AlternateDirAuthority]] **AlternateDirAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__ + [[AlternateBridgeAuthority]] **AlternateBridgeAuthority** [__nickname__] [**flags**] __address__:__port__ __ fingerprint__:: @@ -483,6 +541,11 @@ GENERAL OPTIONS in accordance to RFC 1929. Both username and password must be between 1 and 255 characters. +[[SocksSocketsGroupWritable]] **SocksSocketsGroupWritable** **0**|**1**:: + If this option is set to 0, don't allow the filesystem group to read and + write unix sockets (e.g. SocksSocket). If the option is set to 1, make + the SocksSocket socket readable and writable by the default GID. (Default: 0) + [[KeepalivePeriod]] **KeepalivePeriod** __NUM__:: To keep firewalls from expiring connections, send a padding keepalive cell every NUM seconds on open connections that are in use. If the connection @@ -550,7 +613,7 @@ GENERAL OPTIONS \'info'. (Default: 0) [[PredictedPortsRelevanceTime]] **PredictedPortsRelevanceTime** __NUM__:: - Set how long, after the client has mad an anonymized connection to a + Set how long, after the client has made an anonymized connection to a given port, we will try to make sure that we build circuits to exits that support that port. The maximum value for this option is 1 hour. (Default: 1 hour) @@ -568,6 +631,14 @@ GENERAL OPTIONS messages to affect times logged by a controller, times attached to syslog messages, or the mtime fields on log files. (Default: 1 second) +[[TruncateLogFile]] **TruncateLogFile** **0**|**1**:: + If 1, Tor will overwrite logs at startup and in response to a HUP signal, + instead of appending to them. (Default: 0) + +[[SyslogIdentityTag]] **SyslogIdentityTag** __tag__:: + When logging to syslog, adds a tag to the syslog identity such that + log entries are marked with "Tor-__tag__". (Default: none) + [[SafeLogging]] **SafeLogging** **0**|**1**|**relay**:: Tor can scrub potentially sensitive strings from log messages (e.g. addresses) by replacing them with the string [scrubbed]. This way logs can @@ -582,6 +653,14 @@ GENERAL OPTIONS [[User]] **User** __UID__:: On startup, setuid to this user and setgid to their primary group. +[[KeepBindCapabilities]] **KeepBindCapabilities** **0**|**1**|**auto**:: + On Linux, when we are started as root and we switch our identity using + the **User** option, the **KeepBindCapabilities** option tells us whether to + try to retain our ability to bind to low ports. If this value is 1, we + try to keep the capability; if it is 0 we do not; and if it is **auto**, + we keep the capability only if we are configured to listen on a low port. + (Default: auto.) + [[HardwareAccel]] **HardwareAccel** **0**|**1**:: If non-zero, try to use built-in (static) crypto hardware acceleration when available. (Default: 0) @@ -668,9 +747,12 @@ The following options are useful only for clients (that is, if fingerprint to look up the bridge descriptor at the bridge authority, if it's provided and if UpdateBridgesFromAuthority is set too. + + - If "transport" is provided, and matches to a ClientTransportPlugin - line, we use that pluggable transports proxy to transfer data to - the bridge. + If "transport" is provided, it must match a ClientTransportPlugin line. We + then use that pluggable transport's proxy to transfer data to the bridge, + rather than connecting to the bridge directly. Some transports use a + transport-specific method to work out the remote address to connect to. + These transports typically ignore the "IP:ORPort" specified in the bridge + line. [[LearnCircuitBuildTimeout]] **LearnCircuitBuildTimeout** **0**|**1**:: If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1) @@ -707,10 +789,12 @@ The following options are useful only for clients (that is, if unless ORPort, ExtORPort, or DirPort are configured.) (Default: 0) [[ExcludeNodes]] **ExcludeNodes** __node__,__node__,__...__:: - A list of identity fingerprints, nicknames, country codes and address - patterns of nodes to avoid when building a circuit. + A list of identity fingerprints, country codes, and address + patterns of nodes to avoid when building a circuit. Country codes are + 2-letter ISO3166 codes, and must + be wrapped in braces; fingerprints may be preceded by a dollar sign. (Example: - ExcludeNodes SlowServer, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + ExcludeNodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + By default, this option is treated as a preference that Tor is allowed to override in order to keep working. @@ -730,11 +814,13 @@ The following options are useful only for clients (that is, if [[ExcludeExitNodes]] **ExcludeExitNodes** __node__,__node__,__...__:: - A list of identity fingerprints, nicknames, country codes and address + A list of identity fingerprints, country codes, and address patterns of nodes to never use when picking an exit node---that is, a node that delivers traffic for you outside the Tor network. Note that any node listed in ExcludeNodes is automatically considered to be part of this - list too. See also the caveats on the "ExitNodes" option below. + list too. See + the **ExcludeNodes** option for more information on how to specify + nodes. See also the caveats on the "ExitNodes" option below. [[GeoIPExcludeUnknown]] **GeoIPExcludeUnknown** **0**|**1**|**auto**:: If this option is set to 'auto', then whenever any country code is set in @@ -745,9 +831,10 @@ The following options are useful only for clients (that is, if configured or can't be found. (Default: auto) [[ExitNodes]] **ExitNodes** __node__,__node__,__...__:: - A list of identity fingerprints, nicknames, country codes and address + A list of identity fingerprints, country codes, and address patterns of nodes to use as exit node---that is, a - node that delivers traffic for you outside the Tor network. + + node that delivers traffic for you outside the Tor network. See + the **ExcludeNodes** option for more information on how to specify nodes. + + Note that if you list too few nodes here, or if you exclude too many exit nodes with ExcludeExitNodes, you can degrade functionality. For example, @@ -768,7 +855,7 @@ The following options are useful only for clients (that is, if this option. [[EntryNodes]] **EntryNodes** __node__,__node__,__...__:: - A list of identity fingerprints, nicknames, and country codes of nodes + A list of identity fingerprints and country codes of nodes to use for the first hop in your normal circuits. Normal circuits include all circuits except for direct connections to directory servers. The Bridge @@ -776,7 +863,8 @@ The following options are useful only for clients (that is, if UseBridges is 1, the Bridges are used as your entry nodes. + + The ExcludeNodes option overrides this option: any node listed in both - EntryNodes and ExcludeNodes is treated as excluded. + EntryNodes and ExcludeNodes is treated as excluded. See + the **ExcludeNodes** option for more information on how to specify nodes. [[StrictNodes]] **StrictNodes** **0**|**1**:: If StrictNodes is set to 1, Tor will treat the ExcludeNodes option as a @@ -873,12 +961,12 @@ The following options are useful only for clients (that is, if When a request for address arrives to Tor, it will transform to newaddress before processing it. For example, if you always want connections to www.example.com to exit via __torserver__ (where __torserver__ is the - nickname of the server), use "MapAddress www.example.com + fingerprint of the server), use "MapAddress www.example.com www.example.com.torserver.exit". If the value is prefixed with a "\*.", matches an entire domain. For example, if you always want connections to example.com and any if its subdomains to exit via - __torserver__ (where __torserver__ is the nickname of the server), use + __torserver__ (where __torserver__ is the fingerprint of the server), use "MapAddress \*.example.com \*.example.com.torserver.exit". (Note the leading "*." in each part of the directive.) You can also redirect all subdomains of a domain to a single address. For example, "MapAddress @@ -917,7 +1005,9 @@ The following options are useful only for clients (that is, if Feel free to reuse a circuit that was first used at most NUM seconds ago, but never attach a new stream to a circuit that is too old. For hidden services, this applies to the __last__ time a circuit was used, not the - first. (Default: 10 minutes) + first. Circuits with streams constructed with SOCKS authentication via + SocksPorts that have **KeepAliveIsolateSOCKSAuth** ignore this value. + (Default: 10 minutes) [[MaxClientCircuitsPending]] **MaxClientCircuitsPending** __NUM__:: Do not allow more than NUM circuits to be pending at a time for handling @@ -925,27 +1015,36 @@ The following options are useful only for clients (that is, if but it has not yet been completely constructed. (Default: 32) [[NodeFamily]] **NodeFamily** __node__,__node__,__...__:: - The Tor servers, defined by their identity fingerprints or nicknames, + The Tor servers, defined by their identity fingerprints, constitute a "family" of similar or co-administered servers, so never use any two of them in the same circuit. Defining a NodeFamily is only needed when a server doesn't list the family itself (with MyFamily). This option - can be used multiple times. In addition to nodes, you can also list - IP address and ranges and country codes in {curly braces}. + can be used multiple times; each instance defines a separate family. In + addition to nodes, you can also list IP address and ranges and country + codes in {curly braces}. See the **ExcludeNodes** option for more + information on how to specify nodes. [[EnforceDistinctSubnets]] **EnforceDistinctSubnets** **0**|**1**:: If 1, Tor will not put two servers whose IP addresses are "too close" on the same circuit. Currently, two addresses are "too close" if they lie in the same /16 range. (Default: 1) -[[SOCKSPort]] **SOCKSPort** \['address':]__port__|**auto** [_flags_] [_isolation flags_]:: +[[SocksPort]] **SocksPort** \['address':]__port__|**unix:**__path__|**auto** [_flags_] [_isolation flags_]:: Open this port to listen for connections from SOCKS-speaking applications. Set this to 0 if you don't want to allow application connections via SOCKS. Set it to "auto" to have Tor pick a port for you. This directive can be specified multiple times to bind to multiple addresses/ports. (Default: 9050) + + + NOTE: Although this option allows you to specify an IP address + other than localhost, you should do so only with extreme caution. + The SOCKS protocol is unencrypted and (as we use it) + unauthenticated, so exposing it in this way could leak your + information to anybody watching your network, and allow anybody + to use your computer as an open proxy. + + + The _isolation flags_ arguments give Tor rules for which streams - received on this SOCKSPort are allowed to share circuits with one + received on this SocksPort are allowed to share circuits with one another. Recognized isolation flags are: **IsolateClientAddr**;; Don't share circuits with streams from a different @@ -960,20 +1059,23 @@ The following options are useful only for clients (that is, if (SOCKS 4, SOCKS 5, TransPort connections, NATDPort connections, and DNSPort requests are all considered to be different protocols.) **IsolateDestPort**;; - Don't share circuits with streams targetting a different + Don't share circuits with streams targeting a different destination port. **IsolateDestAddr**;; - Don't share circuits with streams targetting a different + Don't share circuits with streams targeting a different destination address. + **KeepAliveIsolateSOCKSAuth**;; + If **IsolateSOCKSAuth** is enabled, keep alive circuits that have + streams with SOCKS authentication set indefinitely. **SessionGroup=**__INT__;; If no other isolation rules would prevent it, allow streams on this port to share circuits with streams from every other port with the same session group. (By default, streams received - on different SOCKSPorts, TransPorts, etc are always isolated from one + on different SocksPorts, TransPorts, etc are always isolated from one another. This option overrides that behavior.) -[[OtherSOCKSPortFlags]]:: - Other recognized __flags__ for a SOCKSPort are: +[[OtherSocksPortFlags]]:: + Other recognized __flags__ for a SocksPort are: **NoIPv4Traffic**;; Tell exits to not connect to IPv4 addresses in response to SOCKS requests on this connection. @@ -984,20 +1086,18 @@ The following options are useful only for clients (that is, if **PreferIPv6**;; Tells exits that, if a host has both an IPv4 and an IPv6 address, we would prefer to connect to it via IPv6. (IPv4 is the default.) + - + - NOTE: Although this option allows you to specify an IP address - other than localhost, you should do so only with extreme caution. - The SOCKS protocol is unencrypted and (as we use it) - unauthenticated, so exposing it in this way could leak your - information to anybody watching your network, and allow anybody - to use your computer as an open proxy. + - + **CacheIPv4DNS**;; Tells the client to remember IPv4 DNS answers we receive from exit nodes via this connection. (On by default.) **CacheIPv6DNS**;; Tells the client to remember IPv6 DNS answers we receive from exit nodes via this connection. + **GroupWritable**;; + Unix domain sockets only: makes the socket get created as + group-writable. + **WorldWritable**;; + Unix domain sockets only: makes the socket get created as + world-writable. **CacheDNS**;; Tells the client to remember all DNS answers we receive from exit nodes via this connection. @@ -1014,7 +1114,7 @@ The following options are useful only for clients (that is, if requests via this connection. **PreferIPv6Automap**;; When serving a hostname lookup request on this port that - should get automapped (according to AutomapHostsOnResove), + should get automapped (according to AutomapHostsOnResolve), if we could return either an IPv4 or an IPv6 answer, prefer an IPv6 answer. (On by default.) **PreferSOCKSNoAuth**;; @@ -1027,14 +1127,14 @@ The following options are useful only for clients (that is, if authentication" when IsolateSOCKSAuth is disabled, or when this option is set. -[[SOCKSListenAddress]] **SOCKSListenAddress** __IP__[:__PORT__]:: +[[SocksListenAddress]] **SocksListenAddress** __IP__[:__PORT__]:: Bind to this address to listen for connections from Socks-speaking applications. (Default: 127.0.0.1) You can also specify a port (e.g. 192.168.0.1:9100). This directive can be specified multiple times to bind to multiple addresses/ports. (DEPRECATED: As of 0.2.3.x-alpha, you can - now use multiple SOCKSPort entries, and provide addresses for SOCKSPort - entries, so SOCKSListenAddress no longer has a purpose. For backward - compatibility, SOCKSListenAddress is only allowed when SOCKSPort is just + now use multiple SocksPort entries, and provide addresses for SocksPort + entries, so SocksListenAddress no longer has a purpose. For backward + compatibility, SocksListenAddress is only allowed when SocksPort is just a port number.) [[SocksPolicy]] **SocksPolicy** __policy__,__policy__,__...__:: @@ -1097,6 +1197,17 @@ The following options are useful only for clients (that is, if download any non-default directory material. It doesn't currently do anything when we lack a live consensus. (Default: 1) +[[GuardfractionFile]] **GuardfractionFile** __FILENAME__:: + V3 authoritative directories only. Configures the location of the + guardfraction file which contains information about how long relays + have been guards. (Default: unset) + +[[UseGuardFraction]] **UseGuardFraction** **0**|**1**|**auto**:: + This torrc option specifies whether clients should use the + guardfraction information found in the consensus during path + selection. If it's set to 'auto', clients will do what the + UseGuardFraction consensus parameter tells them to do. (Default: auto) + [[NumEntryGuards]] **NumEntryGuards** __NUM__:: If UseEntryGuards is set to 1, we will try to pick a total of NUM routers as long-term entries for our circuits. If NUM is 0, we try to learn @@ -1230,7 +1341,7 @@ The following options are useful only for clients (that is, if Use 0 if you don't want to allow NATD connections. Set the port to "auto" to have Tor pick a port for you. This directive can be specified multiple times to bind to multiple addresses/ports. See - SOCKSPort for an explanation of isolation flags. + + SocksPort for an explanation of isolation flags. + + This option is only for people who cannot use TransPort. (Default: 0) @@ -1258,7 +1369,7 @@ The following options are useful only for clients (that is, if doesn't handle arbitrary DNS request types. Set the port to "auto" to have Tor pick a port for you. This directive can be specified multiple times to bind to multiple - addresses/ports. See SOCKSPort for an explanation of isolation + addresses/ports. See SocksPort for an explanation of isolation flags. (Default: 0) [[DNSListenAddress]] **DNSListenAddress** __IP__[:__PORT__]:: @@ -1283,7 +1394,7 @@ The following options are useful only for clients (that is, if [[DownloadExtraInfo]] **DownloadExtraInfo** **0**|**1**:: If true, Tor downloads and caches "extra-info" documents. These documents contain information about servers other than the information in their - regular router descriptors. Tor does not use this information for anything + regular server descriptors. Tor does not use this information for anything itself; to save bandwidth, leave this option turned off. (Default: 0) [[WarnPlaintextPorts]] **WarnPlaintextPorts** __port__,__port__,__...__:: @@ -1318,6 +1429,22 @@ The following options are useful only for clients (that is, if To enable this option the compile time flag --enable-tor2webmode must be specified. (Default: 0) +[[Tor2webRendezvousPoints]] **Tor2webRendezvousPoints** __node__,__node__,__...__:: + A list of identity fingerprints, nicknames, country codes and + address patterns of nodes that are allowed to be used as RPs + in HS circuits; any other nodes will not be used as RPs. + (Example: + Tor2webRendezvousPoints Fastyfasty, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + + + This feature can only be used if Tor2webMode is also enabled. + + + ExcludeNodes have higher priority than Tor2webRendezvousPoints, + which means that nodes specified in ExcludeNodes will not be + picked as RPs. + + + If no nodes in Tor2webRendezvousPoints are currently available for + use, Tor will choose a random node when building HS circuits. + [[UseMicrodescriptors]] **UseMicrodescriptors** **0**|**1**|**auto**:: Microdescriptors are a smaller version of the information that Tor needs in order to build its circuits. Using microdescriptors makes Tor clients @@ -1391,17 +1518,33 @@ The following options are useful only for clients (that is, if If no defaults are available there, these options default to 20, .80, .60, and 100, respectively. +[[ClientUseIPv4]] **ClientUseIPv4** **0**|**1**:: + If this option is set to 0, Tor will avoid connecting to directory servers + and entry nodes over IPv4. Note that clients with an IPv4 + address in a **Bridge**, proxy, or pluggable transport line will try + connecting over IPv4 even if **ClientUseIPv4** is set to 0. (Default: 1) + [[ClientUseIPv6]] **ClientUseIPv6** **0**|**1**:: - If this option is set to 1, Tor might connect to entry nodes over - IPv6. Note that clients configured with an IPv6 address in a - **Bridge** line will try connecting over IPv6 even if - **ClientUseIPv6** is set to 0. (Default: 0) + If this option is set to 1, Tor might connect to directory servers or + entry nodes over IPv6. Note that clients configured with an IPv6 address + in a **Bridge**, proxy, or pluggable transport line will try connecting + over IPv6 even if **ClientUseIPv6** is set to 0. (Default: 0) + +[[ClientPreferIPv6DirPort]] **ClientPreferIPv6DirPort** **0**|**1**|**auto**:: + If this option is set to 1, Tor prefers a directory port with an IPv6 + address over one with IPv4, for direct connections, if a given directory + server has both. (Tor also prefers an IPv6 DirPort if IPv4Client is set to + 0.) If this option is set to auto, clients prefer IPv4. Other things may + influence the choice. This option breaks a tie to the favor of IPv6. + (Default: auto) -[[ClientPreferIPv6ORPort]] **ClientPreferIPv6ORPort** **0**|**1**:: +[[ClientPreferIPv6ORPort]] **ClientPreferIPv6ORPort** **0**|**1**|**auto**:: If this option is set to 1, Tor prefers an OR port with an IPv6 - address over one with IPv4 if a given entry node has both. Other - things may influence the choice. This option breaks a tie to the - favor of IPv6. (Default: 0) + address over one with IPv4 if a given entry node has both. (Tor also + prefers an IPv6 ORPort if IPv4Client is set to 0.) If this option is set + to auto, Tor bridge clients prefer the configured bridge address, and + other clients prefer IPv4. Other things may influence the choice. This + option breaks a tie to the favor of IPv6. (Default: auto) [[PathsNeededToBuildCircuits]] **PathsNeededToBuildCircuits** __NUM__:: Tor clients don't build circuits for user traffic until they know @@ -1415,15 +1558,44 @@ The following options are useful only for clients (that is, if Tor will use a default value chosen by the directory authorities. (Default: -1.) -[[Support022HiddenServices]] **Support022HiddenServices** **0**|**1**|**auto**:: - Tor hidden services running versions before 0.2.3.x required clients to - send timestamps, which can potentially be used to distinguish clients - whose view of the current time is skewed. If this option is set to 0, we - do not send this timestamp, and hidden services on obsolete Tor versions - will not work. If this option is set to 1, we send the timestamp. If - this optoin is "auto", we take a recommendation from the latest consensus - document. (Default: auto) - +[[ClientBootstrapConsensusAuthorityDownloadSchedule]] **ClientBootstrapConsensusAuthorityDownloadSchedule** __N__,__N__,__...__:: + Schedule for when clients should download consensuses from authorities + if they are bootstrapping (that is, they don't have a usable, reasonably + live consensus). Only used by clients fetching from a list of fallback + directory mirrors. This schedule is advanced by (potentially concurrent) + connection attempts, unlike other schedules, which are advanced by + connection failures. (Default: 10, 11, 3600, 10800, 25200, 54000, + 111600, 262800) + +[[ClientBootstrapConsensusFallbackDownloadSchedule]] **ClientBootstrapConsensusFallbackDownloadSchedule** __N__,__N__,__...__:: + Schedule for when clients should download consensuses from fallback + directory mirrors if they are bootstrapping (that is, they don't have a + usable, reasonably live consensus). Only used by clients fetching from a + list of fallback directory mirrors. This schedule is advanced by + (potentially concurrent) connection attempts, unlike other schedules, + which are advanced by connection failures. (Default: 0, 1, 4, 11, 3600, + 10800, 25200, 54000, 111600, 262800) + +[[ClientBootstrapConsensusAuthorityOnlyDownloadSchedule]] **ClientBootstrapConsensusAuthorityOnlyDownloadSchedule** __N__,__N__,__...__:: + Schedule for when clients should download consensuses from authorities + if they are bootstrapping (that is, they don't have a usable, reasonably + live consensus). Only used by clients which don't have or won't fetch + from a list of fallback directory mirrors. This schedule is advanced by + (potentially concurrent) connection attempts, unlike other schedules, + which are advanced by connection failures. (Default: 0, 3, 7, 3600, + 10800, 25200, 54000, 111600, 262800) + +[[ClientBootstrapConsensusMaxDownloadTries]] **ClientBootstrapConsensusMaxDownloadTries** __NUM__:: + Try this many times to download a consensus while bootstrapping using + fallback directory mirrors before giving up. (Default: 7) + +[[ClientBootstrapConsensusAuthorityOnlyMaxDownloadTries]] **ClientBootstrapConsensusAuthorityOnlyMaxDownloadTries** __NUM__:: + Try this many times to download a consensus while bootstrapping using + authorities before giving up. (Default: 4) + +[[ClientBootstrapConsensusMaxInProgressTries]] **ClientBootstrapConsensusMaxInProgressTries** __NUM__:: + Try this many simultaneous connections to download a consensus before + waiting for one to complete, timeout, or error out. (Default: 4) SERVER OPTIONS -------------- @@ -1456,8 +1628,8 @@ is non-zero): [[BridgeRelay]] **BridgeRelay** **0**|**1**:: Sets the relay to act as a "bridge" with respect to relaying connections from bridge users to the Tor network. It mainly causes Tor to publish a - server descriptor to the bridge database, rather than publishing a relay - descriptor to the public directory authorities. + server descriptor to the bridge database, rather than + to the public directory authorities. [[ContactInfo]] **ContactInfo** __email_address__:: Administrative contact information for this relay or bridge. This line @@ -1468,24 +1640,56 @@ is non-zero): that it's an email address and/or generate a new address for this purpose. +[[ExitRelay]] **ExitRelay** **0**|**1**|**auto**:: + Tells Tor whether to run as an exit relay. If Tor is running as a + non-bridge server, and ExitRelay is set to 1, then Tor allows traffic to + exit according to the ExitPolicy option (or the default ExitPolicy if + none is specified). + + + If ExitRelay is set to 0, no traffic is allowed to + exit, and the ExitPolicy option is ignored. + + + + If ExitRelay is set to "auto", then Tor behaves as if it were set to 1, but + warns the user if this would cause traffic to exit. In a future version, + the default value will be 0. (Default: auto) + [[ExitPolicy]] **ExitPolicy** __policy__,__policy__,__...__:: Set an exit policy for this server. Each policy is of the form - "**accept**|**reject** __ADDR__[/__MASK__][:__PORT__]". If /__MASK__ is + "**accept[6]**|**reject[6]** __ADDR__[/__MASK__][:__PORT__]". If /__MASK__ is omitted then this policy just applies to the host given. Instead of giving - a host or network you can also use "\*" to denote the universe (0.0.0.0/0). + a host or network you can also use "\*" to denote the universe (0.0.0.0/0 + and ::/128), or \*4 to denote all IPv4 addresses, and \*6 to denote all + IPv6 addresses. __PORT__ can be a single port number, an interval of ports "__FROM_PORT__-__TO_PORT__", or "\*". If __PORT__ is omitted, that means "\*". + + For example, "accept 18.7.22.69:\*,reject 18.0.0.0/8:\*,accept \*:\*" would - reject any traffic destined for MIT except for web.mit.edu, and accept - anything else. + - + - To specify all internal and link-local networks (including 0.0.0.0/8, - 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16, 10.0.0.0/8, and - 172.16.0.0/12), you can use the "private" alias instead of an address. - These addresses are rejected by default (at the beginning of your exit - policy), along with your public IP address, unless you set the + reject any IPv4 traffic destined for MIT except for web.mit.edu, and accept + any other IPv4 or IPv6 traffic. + + + + Tor also allows IPv6 exit policy entries. For instance, "reject6 [FC00::]/7:\*" + rejects all destinations that share 7 most significant bit prefix with + address FC00::. Respectively, "accept6 [C000::]/3:\*" accepts all destinations + that share 3 most significant bit prefix with address C000::. + + + + accept6 and reject6 only produce IPv6 exit policy entries. Using an IPv4 + address with accept6 or reject6 is ignored and generates a warning. + accept/reject allows either IPv4 or IPv6 addresses. Use \*4 as an IPv4 + wildcard address, and \*6 as an IPv6 wildcard address. accept/reject * + expands to matching IPv4 and IPv6 wildcard address rules. + + + + To specify all IPv4 and IPv6 internal and link-local networks (including + 0.0.0.0/8, 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16, 10.0.0.0/8, + 172.16.0.0/12, [::]/8, [FC00::]/7, [FE80::]/10, [FEC0::]/10, [FF00::]/8, + and [::]/127), you can use the "private" alias instead of an address. + ("private" always produces rules for IPv4 and IPv6 addresses, even when + used with accept6/reject6.) + + + + Private addresses are rejected by default (at the beginning of your exit + policy), along with any configured primary public IPv4 and IPv6 addresses, + and any public IPv4 and IPv6 addresses on any interface on the relay. + These private addresses are rejected unless you set the ExitPolicyRejectPrivate config option to 0. For example, once you've done that, you could allow HTTP to 127.0.0.1 and block all other connections to internal networks with "accept 127.0.0.1:80,reject private:\*", though that @@ -1493,18 +1697,17 @@ is non-zero): public (external) IP address. See RFC 1918 and RFC 3330 for more details about internal and reserved IP address space. + + - Tor also allow IPv6 exit policy entries. For instance, "reject6 [FC00::]/7:*" - rejects all destinations that share 7 most significant bit prefix with - address FC00::. Respectively, "accept6 [C000::]/3:*" accepts all destinations - that share 3 most significant bit prefix with address C000::. + - + This directive can be specified multiple times so you don't have to put it all on one line. + + Policies are considered first to last, and the first match wins. If you - want to \_replace_ the default exit policy, end your exit policy with - either a reject \*:* or an accept \*:*. Otherwise, you're \_augmenting_ - (prepending to) the default exit policy. The default exit policy is: + + want to allow the same ports on IPv4 and IPv6, write your rules using + accept/reject \*. If you want to allow different ports on IPv4 and IPv6, + write your IPv6 rules using accept6/reject6 \*6, and your IPv4 rules using + accept/reject \*4. If you want to \_replace_ the default exit policy, end + your exit policy with either a reject \*:* or an accept \*:*. Otherwise, + you're \_augmenting_ (prepending to) the default exit policy. The default + exit policy is: + reject *:25 reject *:119 @@ -1518,9 +1721,18 @@ is non-zero): reject *:6881-6999 accept *:* + Since the default exit policy uses accept/reject *, it applies to both + IPv4 and IPv6 addresses. + [[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**:: - Reject all private (local) networks, along with your own public IP address, - at the beginning of your exit policy. See above entry on ExitPolicy. + Reject all private (local) networks, along with any configured public + IPv4 and IPv6 addresses, at the beginning of your exit policy. (This + includes the IPv4 and IPv6 addresses advertised by the relay, any + OutboundBindAddress, and the bind addresses of any port options, such as + ORPort and DirPort.) This also rejects any public IPv4 and IPv6 addresses + on any interface on the relay. (If IPv6Exit is not set, all IPv6 addresses + will be rejected anyway.) + See above entry on ExitPolicy. (Default: 1) [[IPv6Exit]] **IPv6Exit** **0**|**1**:: @@ -1534,7 +1746,7 @@ is non-zero): [[MyFamily]] **MyFamily** __node__,__node__,__...__:: Declare that this Tor server is controlled or administered by a group or organization identical or similar to that of the other servers, defined by - their identity fingerprints or nicknames. When two servers both declare + their identity fingerprints. When two servers both declare that they are in the same \'family', Tor clients will not use them in the same circuit. (Each server only needs to list the other servers in its family; it doesn't need to list itself, but it won't hurt.) Do not list @@ -1628,22 +1840,37 @@ is non-zero): Log a heartbeat message every **HeartbeatPeriod** seconds. This is a log level __notice__ message, designed to let you know your Tor server is still alive and doing useful things. Settings this - to 0 will disable the heartbeat. (Default: 6 hours) + to 0 will disable the heartbeat. Otherwise, it must be at least 30 + minutes. (Default: 6 hours) [[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**|**TBytes**:: - Never send more than the specified number of bytes in a given accounting - period, or receive more than that number in the period. For example, with - AccountingMax set to 1 GByte, a server could send 900 MBytes and - receive 800 MBytes and continue running. It will only hibernate once - one of the two reaches 1 GByte. When the number of bytes gets low, - Tor will stop accepting new connections and circuits. When the - number of bytes is exhausted, Tor will hibernate until some - time in the next accounting period. To prevent all servers from waking at - the same time, Tor will also wait until a random point in each period - before waking up. If you have bandwidth cost issues, enabling hibernation - is preferable to setting a low bandwidth, since it provides users with a - collection of fast servers that are up some of the time, which is more - useful than a set of slow servers that are always "available". + Limits the max number of bytes sent and received within a set time period + using a given calculation rule (see: AccountingStart, AccountingRule). + Useful if you need to stay under a specific bandwidth. By default, the + number used for calculation is the max of either the bytes sent or + received. For example, with AccountingMax set to 1 GByte, a server + could send 900 MBytes and receive 800 MBytes and continue running. + It will only hibernate once one of the two reaches 1 GByte. This can + be changed to use the sum of the both bytes received and sent by setting + the AccountingRule option to "sum" (total bandwidth in/out). When the + number of bytes remaining gets low, Tor will stop accepting new connections + and circuits. When the number of bytes is exhausted, Tor will hibernate + until some time in the next accounting period. To prevent all servers + from waking at the same time, Tor will also wait until a random point + in each period before waking up. If you have bandwidth cost issues, + enabling hibernation is preferable to setting a low bandwidth, since + it provides users with a collection of fast servers that are up some + of the time, which is more useful than a set of slow servers that are + always "available". + +[[AccountingRule]] **AccountingRule** **sum**|**max**|**in**|**out**:: + How we determine when our AccountingMax has been reached (when we + should hibernate) during a time interval. Set to "max" to calculate + using the higher of either the sent or received bytes (this is the + default functionality). Set to "sum" to calculate using the sent + plus received bytes. Set to "in" to calculate using only the + received bytes. Set to "out" to calculate using only the sent bytes. + (Default: max) [[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__:: Specify how long accounting periods last. If **month** is given, each @@ -1693,7 +1920,7 @@ is non-zero): [[ServerDNSTestAddresses]] **ServerDNSTestAddresses** __address__,__address__,__...__:: When we're detecting DNS hijacking, make sure that these __valid__ addresses aren't getting redirected. If they are, then our DNS is completely useless, - and we'll reset our exit policy to "reject *:*". This option only affects + and we'll reset our exit policy to "reject \*:*". This option only affects name lookups that your server does on behalf of clients. (Default: "www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org") @@ -1731,25 +1958,58 @@ is non-zero): (Default: P256) [[CellStatistics]] **CellStatistics** **0**|**1**:: - When this option is enabled, Tor writes statistics on the mean time that - cells spend in circuit queues to disk every 24 hours. (Default: 0) + Relays only. + When this option is enabled, Tor collects statistics about cell + processing (i.e. mean time a cell is spending in a queue, mean + number of cells in a queue and mean number of processed cells per + circuit) and writes them into disk every 24 hours. Onion router + operators may use the statistics for performance monitoring. + If ExtraInfoStatistics is enabled, it will published as part of + extra-info document. (Default: 0) [[DirReqStatistics]] **DirReqStatistics** **0**|**1**:: + Relays and bridges only. When this option is enabled, a Tor directory writes statistics on the number and response time of network status requests to disk every 24 - hours. (Default: 1) + hours. Enables relay and bridge operators to monitor how much their + server is being used by clients to learn about Tor network. + If ExtraInfoStatistics is enabled, it will published as part of + extra-info document. (Default: 1) [[EntryStatistics]] **EntryStatistics** **0**|**1**:: + Relays only. When this option is enabled, Tor writes statistics on the number of - directly connecting clients to disk every 24 hours. (Default: 0) + directly connecting clients to disk every 24 hours. Enables relay + operators to monitor how much inbound traffic that originates from + Tor clients passes through their server to go further down the + Tor network. If ExtraInfoStatistics is enabled, it will be published + as part of extra-info document. (Default: 0) [[ExitPortStatistics]] **ExitPortStatistics** **0**|**1**:: - When this option is enabled, Tor writes statistics on the number of relayed - bytes and opened stream per exit port to disk every 24 hours. (Default: 0) + Exit relays only. + When this option is enabled, Tor writes statistics on the number of + relayed bytes and opened stream per exit port to disk every 24 hours. + Enables exit relay operators to measure and monitor amounts of traffic + that leaves Tor network through their exit node. If ExtraInfoStatistics + is enabled, it will be published as part of extra-info document. + (Default: 0) [[ConnDirectionStatistics]] **ConnDirectionStatistics** **0**|**1**:: - When this option is enabled, Tor writes statistics on the bidirectional use - of connections to disk every 24 hours. (Default: 0) + Relays only. + When this option is enabled, Tor writes statistics on the amounts of + traffic it passes between itself and other relays to disk every 24 + hours. Enables relay operators to monitor how much their relay is + being used as middle node in the circuit. If ExtraInfoStatistics is + enabled, it will be published as part of extra-info document. + (Default: 0) + +[[HiddenServiceStatistics]] **HiddenServiceStatistics** **0**|**1**:: + Relays only. + When this option is enabled, a Tor relay writes obfuscated + statistics on its role as hidden-service directory, introduction + point, or rendezvous point to disk every 24 hours. If + ExtraInfoStatistics is also enabled, these statistics are further + published to the directory authorities. (Default: 1) [[ExtraInfoStatistics]] **ExtraInfoStatistics** **0**|**1**:: When this option is enabled, Tor includes previously gathered statistics in @@ -1757,9 +2017,13 @@ is non-zero): (Default: 1) [[ExtendAllowPrivateAddresses]] **ExtendAllowPrivateAddresses** **0**|**1**:: - When this option is enabled, Tor routers allow EXTEND request to - localhost, RFC1918 addresses, and so on. This can create security issues; - you should probably leave it off. (Default: 0) + When this option is enabled, Tor will connect to relays on localhost, + RFC1918 addresses, and so on. In particular, Tor will make direct OR + connections, and Tor routers allow EXTEND requests, to these private + addresses. (Tor will always allow connections to bridges, proxies, and + pluggable transports configured on private addresses.) Enabling this + option can create security issues; you should probably leave it off. + (Default: 0) [[MaxMemInQueues]] **MaxMemInQueues** __N__ **bytes**|**KB**|**MB**|**GB**:: This option configures a threshold above which Tor will assume that it @@ -1771,6 +2035,19 @@ is non-zero): this. If this option is set to 0, Tor will try to pick a reasonable default based on your system's physical memory. (Default: 0) +[[SigningKeyLifetime]] **SigningKeyLifetime** __N__ **days**|**weeks**|**months**:: + For how long should each Ed25519 signing key be valid? Tor uses a + permanent master identity key that can be kept offline, and periodically + generates new "signing" keys that it uses online. This option + configures their lifetime. + (Default: 30 days) + +[[OfflineMasterKey]] **OfflineMasterKey** **0**|**1**:: + If non-zero, the Tor relay will never generate or load its master secret + key. Instead, you'll have to use "tor --keygen" to manage the permanent + ed25519 master identity key, as well as the corresponding temporary + signing keys and certificates. (Default: 0) + DIRECTORY SERVER OPTIONS ------------------------ @@ -1783,11 +2060,6 @@ if DirPort is non-zero): to set up a separate webserver. There's a sample disclaimer in contrib/operator-tools/tor-exit-notice.html. -[[HidServDirectoryV2]] **HidServDirectoryV2** **0**|**1**:: - When this option is set, Tor accepts and serves v2 hidden service - descriptors. Setting DirPort is not required for this, because clients - connect via the ORPort by default. (Default: 1) - [[DirPort]] **DirPort** \['address':]__PORT__|**auto** [_flags_]:: If this option is nonzero, advertise the directory service on this port. Set it to "auto" to have Tor pick a port for you. This option can occur @@ -1811,6 +2083,12 @@ if DirPort is non-zero): except that port specifiers are ignored. Any address not matched by some entry in the policy is accepted. +[[DirCache]] **DirCache** **0**|**1**:: + When this option is set, Tor caches all current directory documents and + accepts client requests for them. Setting DirPort is not required for this, + because clients connect via the ORPort by default. Setting either DirPort + or BridgeRelay and setting DirCache to 0 is not supported. (Default: 1) + DIRECTORY AUTHORITY SERVER OPTIONS ---------------------------------- @@ -1831,8 +2109,8 @@ on the public Tor network. [[V3AuthoritativeDirectory]] **V3AuthoritativeDirectory** **0**|**1**:: When this option is set in addition to **AuthoritativeDirectory**, Tor generates version 3 network statuses and serves descriptors, etc as - described in doc/spec/dir-spec.txt (for Tor clients and servers running at - least 0.2.0.x). + described in dir-spec.txt file of https://spec.torproject.org/[torspec] + (for Tor clients and servers running atleast 0.2.0.x). [[VersioningAuthoritativeDirectory]] **VersioningAuthoritativeDirectory** **0**|**1**:: When this option is set to 1, Tor adds information on which versions of @@ -1841,15 +2119,6 @@ on the public Tor network. authorities provide this service optionally. See **RecommendedVersions**, **RecommendedClientVersions**, and **RecommendedServerVersions**. -[[NamingAuthoritativeDirectory]] **NamingAuthoritativeDirectory** **0**|**1**:: - When this option is set to 1, then the server advertises that it has - opinions about nickname-to-fingerprint bindings. It will include these - opinions in its published network-status pages, by listing servers with - the flag "Named" if a correct binding between that nickname and fingerprint - has been registered with the dirserver. Naming dirservers will refuse to - accept or publish descriptors that contradict a registered binding. See - **approved-routers** in the **FILES** section below. - [[RecommendedVersions]] **RecommendedVersions** __STRING__:: STRING is a comma-separated list of Tor versions currently believed to be safe. The list is included in each directory, and nodes which pull down the @@ -1857,6 +2126,12 @@ on the public Tor network. multiple times: the values from multiple lines are spliced together. When this is set then **VersioningAuthoritativeDirectory** should be set too. +[[RecommendedPackages]] **RecommendedPackages** __PACKAGENAME__ __VERSION__ __URL__ __DIGESTTYPE__**=**__DIGEST__ :: + Adds "package" line to the directory authority's vote. This information + is used to vote on the correct URL and digest for the released versions + of different Tor-related packages, so that the consensus can certify + them. This line may appear any number of times. + [[RecommendedClientVersions]] **RecommendedClientVersions** __STRING__:: STRING is a comma-separated list of Tor versions currently believed to be safe for clients to use. This information is included in version 2 @@ -1866,7 +2141,7 @@ on the public Tor network. [[BridgeAuthoritativeDir]] **BridgeAuthoritativeDir** **0**|**1**:: When this option is set in addition to **AuthoritativeDirectory**, Tor - accepts and serves router descriptors, but it caches and serves the main + accepts and serves server descriptors, but it caches and serves the main networkstatus documents rather than generating its own. (Default: 0) [[MinUptimeHidServDirectoryV2]] **MinUptimeHidServDirectoryV2** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: @@ -1885,24 +2160,19 @@ on the public Tor network. in the "params" line of its networkstatus vote. [[DirAllowPrivateAddresses]] **DirAllowPrivateAddresses** **0**|**1**:: - If set to 1, Tor will accept router descriptors with arbitrary "Address" + If set to 1, Tor will accept server descriptors with arbitrary "Address" elements. Otherwise, if the address is not an IP address or is a private IP - address, it will reject the router descriptor. (Default: 0) + address, it will reject the server descriptor. (Default: 0) -[[AuthDirBadDir]] **AuthDirBadDir** __AddressPattern...__:: +[[AuthDirBadExit]] **AuthDirBadExit** __AddressPattern...__:: Authoritative directories only. A set of address patterns for servers that - will be listed as bad directories in any network status document this - authority publishes, if **AuthDirListBadDirs** is set. + + will be listed as bad exits in any network status document this authority + publishes, if **AuthDirListBadExits** is set. + (The address pattern syntax here and in the options below is the same as for exit policies, except that you don't need to say "accept" or "reject", and ports are not needed.) -[[AuthDirBadExit]] **AuthDirBadExit** __AddressPattern...__:: - Authoritative directories only. A set of address patterns for servers that - will be listed as bad exits in any network status document this authority - publishes, if **AuthDirListBadExits** is set. - [[AuthDirInvalid]] **AuthDirInvalid** __AddressPattern...__:: Authoritative directories only. A set of address patterns for servers that will never be listed as "valid" in any network status document that this @@ -1914,8 +2184,6 @@ on the public Tor network. authority publishes, or accepted as an OR address in any descriptor submitted for publication by this authority. -[[AuthDirBadDirCCs]] **AuthDirBadDirCCs** __CC__,... + - [[AuthDirBadExitCCs]] **AuthDirBadExitCCs** __CC__,... + [[AuthDirInvalidCCs]] **AuthDirInvalidCCs** __CC__,... + @@ -1923,28 +2191,15 @@ on the public Tor network. [[AuthDirRejectCCs]] **AuthDirRejectCCs** __CC__,...:: Authoritative directories only. These options contain a comma-separated list of country codes such that any server in one of those country codes - will be marked as a bad directory/bad exit/invalid for use, or rejected + will be marked as a bad exit/invalid for use, or rejected entirely. -[[AuthDirListBadDirs]] **AuthDirListBadDirs** **0**|**1**:: - Authoritative directories only. If set to 1, this directory has some - opinion about which nodes are unsuitable as directory caches. (Do not set - this to 1 unless you plan to list non-functioning directories as bad; - otherwise, you are effectively voting in favor of every declared - directory.) - [[AuthDirListBadExits]] **AuthDirListBadExits** **0**|**1**:: Authoritative directories only. If set to 1, this directory has some opinion about which nodes are unsuitable as exit nodes. (Do not set this to 1 unless you plan to list non-functioning exits as bad; otherwise, you are effectively voting in favor of every declared exit as an exit.) -[[AuthDirRejectUnlisted]] **AuthDirRejectUnlisted** **0**|**1**:: - Authoritative directories only. If set to 1, the directory server rejects - all uploaded server descriptors that aren't explicitly listed in the - fingerprints file. This acts as a "panic button" if we get hit with a Sybil - attack. (Default: 0) - [[AuthDirMaxServersPerAddr]] **AuthDirMaxServersPerAddr** __NUM__:: Authoritative directories only. The maximum number of servers that we will list as acceptable on a single IP address. Set this to "0" for "no limit". @@ -1964,6 +2219,13 @@ on the public Tor network. or more is always sufficient to satisfy the bandwidth requirement for the Guard flag. (Default: 250 KBytes) +[[AuthDirPinKeys]] **AuthDirPinKeys** **0**|**1**:: + Authoritative directories only. If non-zero, do not allow any relay to + publish a descriptor if any other relay has reserved its <Ed25519,RSA> + identity keypair. In all cases, Tor records every keypair it accepts + in a journal if it is new, or if it differs from the most recently + accepted pinning for one of the keys it contains. (Default: 0) + [[BridgePassword]] **BridgePassword** __Password__:: If set, contains an HTTP authenticator that tells a bridge authority to serve all requested bridge information. Used by the (only partially @@ -2015,11 +2277,6 @@ on the public Tor network. that fine-grained information about nodes can be discarded when it hasn't changed for a given amount of time. (Default: 24 hours) -[[VoteOnHidServDirectoriesV2]] **VoteOnHidServDirectoriesV2** **0**|**1**:: - When this option is set in addition to **AuthoritativeDirectory**, Tor - votes on whether to accept relays as hidden service directories. - (Default: 1) - [[AuthDirHasIPv6Connectivity]] **AuthDirHasIPv6Connectivity** **0**|**1**:: Authoritative directories only. When set to 0, OR ports with an IPv6 address are being accepted without reachability testing. @@ -2041,13 +2298,19 @@ The following options are used to configure a hidden service. Store data files for a hidden service in DIRECTORY. Every hidden service must have a separate directory. You may use this option multiple times to specify multiple services. DIRECTORY must be an existing directory. + (Note: in current versions of Tor, if DIRECTORY is a relative path, + it will be relative to current + working directory of Tor instance, not to its DataDirectory. Do not + rely on this behavior; it is not guaranteed to remain the same in future + versions.) [[HiddenServicePort]] **HiddenServicePort** __VIRTPORT__ [__TARGET__]:: Configure a virtual port VIRTPORT for a hidden service. You may use this option multiple times; each time applies to the service using the most - recent hiddenservicedir. By default, this option maps the virtual port to + recent HiddenServiceDir. By default, this option maps the virtual port to the same port on 127.0.0.1 over TCP. You may override the target port, - address, or both by specifying a target of addr, port, or addr:port. + address, or both by specifying a target of addr, port, addr:port, or + **unix:**__path__. (You can specify an IPv6 target as [addr]:port.) You may also have multiple lines with the same VIRTPORT: when a user connects to that VIRTPORT, one of the TARGETs from those lines will be chosen at random. @@ -2074,11 +2337,37 @@ The following options are used to configure a hidden service. found in the hostname file. Clients need to put this authorization data in their configuration file using **HidServAuth**. +[[HiddenServiceAllowUnknownPorts]] **HiddenServiceAllowUnknownPorts** **0**|**1**:: + If set to 1, then connections to unrecognized ports do not cause the + current hidden service to close rendezvous circuits. (Setting this to 0 is + not an authorization mechanism; it is instead meant to be a mild + inconvenience to port-scanners.) (Default: 0) + +[[HiddenServiceMaxStreams]] **HiddenServiceMaxStreams** __N__:: + The maximum number of simultaneous streams (connections) per rendezvous + circuit. (Setting this to 0 will allow an unlimited number of simultanous + streams.) (Default: 0) + +[[HiddenServiceMaxStreamsCloseCircuit]] **HiddenServiceMaxStreamsCloseCircuit** **0**|**1**:: + If set to 1, then exceeding **HiddenServiceMaxStreams** will cause the + offending rendezvous circuit to be torn down, as opposed to stream creation + requests that exceed the limit being silently ignored. (Default: 0) + [[RendPostPeriod]] **RendPostPeriod** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: Every time the specified period elapses, Tor uploads any rendezvous service descriptors to the directory servers. This information is also uploaded whenever it changes. (Default: 1 hour) +[[HiddenServiceDirGroupReadable]] **HiddenServiceDirGroupReadable** **0**|**1**:: + If this option is set to 1, allow the filesystem group to read the + hidden service directory and hostname file. If the option is set to 0, + only owner is able to read the hidden service directory. (Default: 0) + Has no effect on Windows. + +[[HiddenServiceNumIntroductionPoints]] **HiddenServiceNumIntroductionPoints** __NUM__:: + Number of introduction points the hidden service will have. You can't + have more than 10. (Default: 3) + TESTING NETWORK OPTIONS ----------------------- @@ -2097,6 +2386,14 @@ The following options are used for running a testing Tor network. AssumeReachable 1 AuthDirMaxServersPerAddr 0 AuthDirMaxServersPerAuthAddr 0 + ClientBootstrapConsensusAuthorityDownloadSchedule 0, 2, + 4 (for 40 seconds), 8, 16, 32, 60 + ClientBootstrapConsensusFallbackDownloadSchedule 0, 1, + 4 (for 40 seconds), 8, 16, 32, 60 + ClientBootstrapConsensusAuthorityOnlyDownloadSchedule 0, 1, + 4 (for 40 seconds), 8, 16, 32, 60 + ClientBootstrapConsensusMaxDownloadTries 80 + ClientBootstrapConsensusAuthorityOnlyMaxDownloadTries 80 ClientDNSRejectInternalAddresses 0 ClientRejectInternalAddresses 0 CountPrivateBandwidth 1 @@ -2151,7 +2448,7 @@ The following options are used for running a testing Tor network. that **TestingTorNetwork** is set. (Default: 30 minutes) [[TestingEstimatedDescriptorPropagationTime]] **TestingEstimatedDescriptorPropagationTime** __N__ **minutes**|**hours**:: - Clients try downloading router descriptors from directory caches after this + Clients try downloading server descriptors from directory caches after this time. Changing this requires that **TestingTorNetwork** is set. (Default: 10 minutes) @@ -2195,11 +2492,11 @@ The following options are used for running a testing Tor network. 5 minutes) [[TestingConsensusMaxDownloadTries]] **TestingConsensusMaxDownloadTries** __NUM__:: - Try this often to download a consensus before giving up. Changing + Try this many times to download a consensus before giving up. Changing this requires that **TestingTorNetwork** is set. (Default: 8) [[TestingDescriptorMaxDownloadTries]] **TestingDescriptorMaxDownloadTries** __NUM__:: - Try this often to download a router descriptor before giving up. + Try this often to download a server descriptor before giving up. Changing this requires that **TestingTorNetwork** is set. (Default: 8) [[TestingMicrodescMaxDownloadTries]] **TestingMicrodescMaxDownloadTries** __NUM__:: @@ -2210,8 +2507,26 @@ The following options are used for running a testing Tor network. Try this often to download a v3 authority certificate before giving up. Changing this requires that **TestingTorNetwork** is set. (Default: 8) +[[TestingDirAuthVoteExit]] **TestingDirAuthVoteExit** __node__,__node__,__...__:: + A list of identity fingerprints, country codes, and + address patterns of nodes to vote Exit for regardless of their + uptime, bandwidth, or exit policy. See the **ExcludeNodes** + option for more information on how to specify nodes. + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. See the **ExcludeNodes** option for more + information on how to specify nodes. + +[[TestingDirAuthVoteExitIsStrict]] **TestingDirAuthVoteExitIsStrict** **0**|**1** :: + If True (1), a node will never receive the Exit flag unless it is specified + in the **TestingDirAuthVoteExit** list, regardless of its uptime, bandwidth, + or exit policy. + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. + [[TestingDirAuthVoteGuard]] **TestingDirAuthVoteGuard** __node__,__node__,__...__:: - A list of identity fingerprints, nicknames, country codes and + A list of identity fingerprints and country codes and address patterns of nodes to vote Guard for regardless of their uptime and bandwidth. See the **ExcludeNodes** option for more information on how to specify nodes. @@ -2219,6 +2534,29 @@ The following options are used for running a testing Tor network. In order for this option to have any effect, **TestingTorNetwork** has to be set. +[[TestingDirAuthVoteGuardIsStrict]] **TestingDirAuthVoteGuardIsStrict** **0**|**1** :: + If True (1), a node will never receive the Guard flag unless it is specified + in the **TestingDirAuthVoteGuard** list, regardless of its uptime and bandwidth. + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. + +[[TestingDirAuthVoteHSDir]] **TestingDirAuthVoteHSDir** __node__,__node__,__...__:: + A list of identity fingerprints and country codes and + address patterns of nodes to vote HSDir for regardless of their + uptime and DirPort. See the **ExcludeNodes** option for more + information on how to specify nodes. + + + In order for this option to have any effect, **TestingTorNetwork** + must be set. + +[[TestingDirAuthVoteHSDirIsStrict]] **TestingDirAuthVoteHSDirIsStrict** **0**|**1** :: + If True (1), a node will never receive the HSDir flag unless it is specified + in the **TestingDirAuthVoteHSDir** list, regardless of its uptime and DirPort. + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. + [[TestingEnableConnBwEvent]] **TestingEnableConnBwEvent** **0**|**1**:: If this option is set, then Tor controllers may register for CONN_BW events. Changing this requires that **TestingTorNetwork** is set. @@ -2239,6 +2577,25 @@ The following options are used for running a testing Tor network. authority on a testing network. Overrides the usual default lower bound of 4 KB. (Default: 0) +[[TestingLinkCertLifetime]] **TestingLinkCertLifetime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**|**months**:: + Overrides the default lifetime for the certificates used to authenticate + our X509 link cert with our ed25519 signing key. + (Default: 2 days) + +[[TestingAuthKeyLifetime]] **TestingAuthKeyLifetime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**|**months**:: + Overrides the default lifetime for a signing Ed25519 TLS Link authentication + key. + (Default: 2 days) + +[[TestingLinkKeySlop]] **TestingLinkKeySlop** __N__ **seconds**|**minutes**|**hours** + + +[[TestingAuthKeySlop]] **TestingAuthKeySlop** __N__ **seconds**|**minutes**|**hours** + + +[[TestingSigningKeySlop]] **TestingSigningKeySlop** __N__ **seconds**|**minutes**|**hours**:: + How early before the official expiration of a an Ed25519 signing key do + we replace it and issue a new key? + (Default: 3 hours for link and auth; 1 day for signing.) + SIGNALS ------- @@ -2322,7 +2679,7 @@ __DataDirectory__**/state**:: below). - When the file was last written - What version of Tor generated the state file - - A short history of bandwidth usage, as produced in the router + - A short history of bandwidth usage, as produced in the server descriptors. __DataDirectory__**/bw_accounting**:: @@ -2334,8 +2691,8 @@ __DataDirectory__**/bw_accounting**:: __DataDirectory__**/control_auth_cookie**:: Used for cookie authentication with the controller. Location can be overridden by the CookieAuthFile config option. Regenerated on startup. See - control-spec.txt for details. Only used when cookie authentication is - enabled. + control-spec.txt in https://spec.torproject.org/[torspec] for details. + Only used when cookie authentication is enabled. __DataDirectory__**/lock**:: This file is used to prevent two Tor instances from using same data @@ -2345,6 +2702,61 @@ __DataDirectory__**/lock**:: __DataDirectory__**/keys/***:: Only used by servers. Holds identity keys and onion keys. +__DataDirectory__**/keys/authority_identity_key**:: + A v3 directory authority's master identity key, used to authenticate its + signing key. Tor doesn't use this while it's running. The tor-gencert + program uses this. If you're running an authority, you should keep this + key offline, and not actually put it here. + +__DataDirectory__**/keys/authority_certificate**:: + A v3 directory authority's certificate, which authenticates the authority's + current vote- and consensus-signing key using its master identity key. + Only directory authorities use this file. + +__DataDirectory__**/keys/authority_signing_key**:: + A v3 directory authority's signing key, used to sign votes and consensuses. + Only directory authorities use this file. Corresponds to the + **authority_certificate** cert. + +__DataDirectory__**/keys/legacy_certificate**:: + As authority_certificate: used only when V3AuthUseLegacyKey is set. + See documentation for V3AuthUseLegacyKey. + +__DataDirectory__**/keys/legacy_signing_key**:: + As authority_signing_key: used only when V3AuthUseLegacyKey is set. + See documentation for V3AuthUseLegacyKey. + +__DataDirectory__**/keys/secret_id_key**:: + A relay's RSA1024 permanent identity key, including private and public + components. Used to sign router descriptors, and to sign other keys. + +__DataDirectory__**/keys/ed25519_master_id_public_key**:: + The public part of a relay's Ed25519 permanent identity key. + +__DataDirectory__**/keys/ed25519_master_id_secret_key**:: + The private part of a relay's Ed25519 permanent identity key. This key + is used to sign the medium-term ed25519 signing key. This file can be + kept offline, or kept encrypted. If so, Tor will not be able to generate + new signing keys itself; you'll need to use tor --keygen yourself to do + so. + +__DataDirectory__**/keys/ed25519_signing_secret_key**:: + The private and public components of a relay's medium-term Ed25519 signing + key. This key is authenticated by the Ed25519 master key, in turn + authenticates other keys (and router descriptors). + +__DataDirectory__**/keys/ed25519_signing_cert**:: + The certificate which authenticates "ed25519_signing_secret_key" as + having been signed by the Ed25519 master key. + +__DataDirectory__**/keys/secret_onion_key**:: + A relay's RSA1024 short-term onion key. Used to decrypt old-style ("TAP") + circuit extension requests. + +__DataDirectory__**/keys/secret_onion_key_ntor**:: + A relay's Curve25519 short-term onion key. Used to handle modern ("ntor") + circuit extension requests. + __DataDirectory__**/fingerprint**:: Only used by servers. Holds the fingerprint of the server's identity key. @@ -2352,20 +2764,9 @@ __DataDirectory__**/hashed-fingerprint**:: Only used by bridges. Holds the hashed fingerprint of the bridge's identity key. (That is, the hash of the hash of the identity key.) -__DataDirectory__**/approved-routers**:: - Only for naming authoritative directory servers (see - **NamingAuthoritativeDirectory**). This file lists nickname to identity - bindings. Each line lists a nickname and a fingerprint separated by - whitespace. See your **fingerprint** file in the __DataDirectory__ for an - example line. If the nickname is **!reject** then descriptors from the - given identity (fingerprint) are rejected by this server. If it is - **!invalid** then descriptors are accepted but marked in the directory as - not valid, that is, not recommended. - __DataDirectory__**/v3-status-votes**:: - Only for authoritative directory servers. This file contains status votes - from all the authoritative directory servers and is used to generate the - network consensus document. + Only for v3 authoritative directory servers. This file contains + status votes from all the authoritative directory servers. __DataDirectory__**/unverified-consensus**:: This file contains a network consensus document that has been downloaded, @@ -2377,7 +2778,7 @@ __DataDirectory__**/unverified-microdesc-consensus**:: to check yet. __DataDirectory__**/unparseable-desc**:: - Onion router descriptors that Tor was unable to parse are dumped to this + Onion server descriptors that Tor was unable to parse are dumped to this file. Only used for debugging. __DataDirectory__**/router-stability**:: @@ -2409,6 +2810,11 @@ __DataDirectory__**/stats/conn-stats**:: Only used by servers. This file is used to collect approximate connection history (number of active connections over time). +__DataDirectory__**/networkstatus-bridges**:: + Only used by authoritative bridge directories. Contains information + about bridges that have self-reported themselves to the bridge + authority. + __HiddenServiceDirectory__**/hostname**:: The <base32-encoded-fingerprint>.onion domain name for this hidden service. If the hidden service is restricted to authorized clients only, this file @@ -2427,11 +2833,12 @@ SEE ALSO **https://www.torproject.org/** +**torspec: https://spec.torproject.org ** BUGS ---- -Plenty, probably. Tor is still in development. Please report them. +Plenty, probably. Tor is still in development. Please report them at https://trac.torproject.org/. AUTHORS ------- |