diff options
Diffstat (limited to 'doc/tor.1.txt')
| -rw-r--r-- | doc/tor.1.txt | 214 |
1 files changed, 164 insertions, 50 deletions
diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 21b482802e..95d56c6dbd 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -93,7 +93,9 @@ COMMAND-LINE OPTIONS into Tor. (Any module not listed is not optional in this version of Tor.) [[opt-version]] **--version**:: - Display Tor version and exit. + Display Tor version and exit. The output is a single line of the format + "Tor version [version number]." (The version number format + is as specified in version-spec.txt.) [[opt-quiet]] **--quiet**|**--hush**:: Override the default console log. By default, Tor starts out logging @@ -149,8 +151,8 @@ 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 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'. +messages to debug.log, you will probably need to say **--Log** `"debug file +debug.log"`. Options on the command line override those in configuration files. See the next section for more information. @@ -352,7 +354,7 @@ 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__|**unix:**__path__|**auto** [__flags__]:: +[[ControlPort]] **ControlPort** \['address':]__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 in @@ -363,7 +365,8 @@ GENERAL OPTIONS methods means either method is sufficient to authenticate to Tor.) This option is required for many Tor controllers; most use the value of 9051. If a unix domain socket is used, you may quote the path using standard - C escape sequences. + C escape sequences. You can specify this directive multiple times, to + bind to multiple address/port pairs. Set it to "auto" to have Tor pick a port for you. (Default: 0) + + Recognized flags are... @@ -602,20 +605,26 @@ GENERAL OPTIONS Otherwise the sandbox will be disabled. The option is currently an experimental feature. It only works on Linux-based operating systems, and only when Tor has been built with the libseccomp library. This option - can not be changed while tor is running. + can not be changed while tor is running. + + - When the Sandbox is 1, the following options can not be changed when tor + When the **Sandbox** is 1, the following options can not be changed when tor is running: - Address - ConnLimit - CookieAuthFile - DirPortFrontPage - ExtORPortCookieAuthFile - Logs - ServerDNSResolvConfFile - Tor must remain in client or server mode (some changes to ClientOnly and - ORPort are not allowed). - ClientOnionAuthDir and any files in it won't reload on HUP signal. + **Address**, + **ConnLimit**, + **CookieAuthFile**, + **DirPortFrontPage**, + **ExtORPortCookieAuthFile**, + **Logs**, + **ServerDNSResolvConfFile**, + **ClientOnionAuthDir** (and any files in it won't reload on HUP signal). + + + Launching new Onion Services through the control port is not supported + with current syscall sandboxing implementation. + + + Tor must remain in client or server mode (some changes to **ClientOnly** + and **ORPort** are not allowed). Currently, if **Sandbox** is 1, + **ControlPort** command "GETINFO address" will not work. + + (Default: 0) [[Socks4Proxy]] **Socks4Proxy** __host__[:__port__]:: @@ -673,7 +682,8 @@ GENERAL OPTIONS + The currently recognized domains are: general, crypto, net, config, fs, protocol, mm, http, app, control, circ, rend, bug, dir, dirserv, or, edge, - acct, hist, handshake, heartbeat, channel, sched, guard, consdiff, and dos. + acct, hist, handshake, heartbeat, channel, sched, guard, consdiff, dos, + process, pt, btrack, and mesg. Domain names are case-insensitive. + + For example, "`Log [handshake]debug [~net,~mm]info notice stdout`" sends @@ -949,6 +959,20 @@ The following options are useful only for clients (that is, if this option. This option should be offered via the UI to mobile users for use where bandwidth may be expensive. (Default: 0) +[[CircuitPadding]] **CircuitPadding** **0**|**1**:: + If set to 0, Tor will not pad client circuits with additional cover + traffic. Only clients may set this option. This option should be offered + via the UI to mobile users for use where bandwidth may be expensive. If + set to 1, padding will be negotiated as per the consensus and relay + support (unlike ConnectionPadding, CircuitPadding cannot be force-enabled). + (Default: 1) + +[[ReducedCircuitPadding]] **ReducedCircuitPadding** **0**|**1**:: + If set to 1, Tor will only use circuit padding algorithms that have low + overhead. Only clients may set this option. This option should be offered + via the UI to mobile users for use where bandwidth may be expensive. + (Default: 0) + [[ExcludeNodes]] **ExcludeNodes** __node__,__node__,__...__:: A list of identity fingerprints, country codes, and address patterns of nodes to avoid when building a circuit. Country codes are @@ -1015,6 +1039,26 @@ The following options are useful only for clients (that is, if The .exit address notation, if enabled via MapAddress, overrides this option. +[[MiddleNodes]] **MiddleNodes** __node__,__node__,__...__:: + A list of identity fingerprints and country codes of nodes + to use for "middle" hops in your normal circuits. + Normal circuits include all circuits except for direct connections + to directory servers. Middle hops are all hops other than exit and entry. + ++ + This is an **experimental** feature that is meant to be used by researchers + and developers to test new features in the Tor network safely. Using it + without care will strongly influence your anonymity. This feature might get + removed in the future. ++ + The HSLayer2Node and HSLayer3Node options override this option for onion + service circuits, if they are set. The vanguards addon will read this + option, and if set, it will set HSLayer2Nodes and HSLayer3Nodes to nodes + from this set. ++ + The ExcludeNodes option overrides this option: any node listed in both + MiddleNodes and ExcludeNodes is treated as excluded. See + the **ExcludeNodes** option for more information on how to specify nodes. + [[EntryNodes]] **EntryNodes** __node__,__node__,__...__:: A list of identity fingerprints and country codes of nodes to use for the first hop in your normal circuits. @@ -1030,14 +1074,15 @@ The following options are useful only for clients (that is, if [[StrictNodes]] **StrictNodes** **0**|**1**:: If StrictNodes is set to 1, Tor will treat solely the ExcludeNodes option as a requirement to follow for all the circuits you generate, even if - doing so will break functionality for you (StrictNodes applies to neither - ExcludeExitNodes nor to ExitNodes). If StrictNodes is set to 0, Tor will - still try to avoid nodes in the ExcludeNodes list, but it will err on the - side of avoiding unexpected errors. Specifically, StrictNodes 0 tells Tor - that it is okay to use an excluded node when it is *necessary* to perform - relay reachability self-tests, connect to a hidden service, provide a - hidden service to a client, fulfill a .exit request, upload directory - information, or download directory information. (Default: 0) + doing so will break functionality for you (StrictNodes does not apply to + ExcludeExitNodes, ExitNodes, MiddleNodes, or MapAddress). If StrictNodes + is set to 0, Tor will still try to avoid nodes in the ExcludeNodes list, + but it will err on the side of avoiding unexpected errors. + Specifically, StrictNodes 0 tells Tor that it is okay to use an excluded + node when it is *necessary* to perform relay reachability self-tests, + connect to a hidden service, provide a hidden service to a client, + fulfill a .exit request, upload directory information, or download + directory information. (Default: 0) [[FascistFirewall]] **FascistFirewall** **0**|**1**:: If 1, Tor will only create outgoing connections to ORs running on ports @@ -1126,23 +1171,26 @@ The following options are useful only for clients (that is, if "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 - *.example.com www.example.com". + + *.example.com www.example.com". If the specified exit is not available, + or the exit can not connect to the site, Tor will fail any connections + to the mapped address.+ + NOTES: 1. When evaluating MapAddress expressions Tor stops when it hits the most recently added expression that matches the requested address. So if you - have the following in your torrc, www.torproject.org will map to 1.1.1.1: + have the following in your torrc, www.torproject.org will map to + 198.51.100.1: - MapAddress www.torproject.org 2.2.2.2 - MapAddress www.torproject.org 1.1.1.1 + MapAddress www.torproject.org 192.0.2.1 + MapAddress www.torproject.org 198.51.100.1 2. Tor evaluates the MapAddress configuration until it finds no matches. So if you have the following in your torrc, www.torproject.org will map to - 2.2.2.2: + 203.0.113.1: - MapAddress 1.1.1.1 2.2.2.2 - MapAddress www.torproject.org 1.1.1.1 + MapAddress 198.51.100.1 203.0.113.1 + MapAddress www.torproject.org 198.51.100.1 3. The following MapAddress expression is invalid (and will be ignored) because you cannot map from a specific address to a wildcard @@ -1153,6 +1201,15 @@ The following options are useful only for clients (that is, if 4. Using a wildcard to match only part of a string (as in *ample.com) is also invalid. + 5. Tor maps hostnames and IP addresses separately. If you MapAddress + a DNS name, but use an IP address to connect, then Tor will ignore the + DNS name mapping. + + 6. MapAddress does not apply to redirects in the application protocol. + For example, HTTP redirects and alt-svc headers will ignore mappings + for the original address. You can use a wildcard mapping to handle + redirects within the same site. + [[NewCircuitPeriod]] **NewCircuitPeriod** __NUM__:: Every NUM seconds consider whether to build a new circuit. (Default: 30 seconds) @@ -1202,6 +1259,8 @@ The following options are useful only for clients (that is, if information to anybody watching your network, and allow anybody to use your computer as an open proxy. + + + If multiple entries of this option are present in your configuration + file, Tor will perform stream isolation between listeners by default. The _isolation flags_ arguments give Tor rules for which streams received on this SocksPort are allowed to share circuits with one another. Recognized isolation flags are: @@ -1444,14 +1503,18 @@ The following options are useful only for clients (that is, if protocol instead of SOCKS. Set this to 0 if you don't want to allow "HTTP CONNECT" 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 + specified multiple times to bind to multiple addresses/ports. If multiple + entries of this option are present in your configuration file, Tor will + perform stream isolation between listeners by default. See SOCKSPort for an explanation of isolation flags. (Default: 0) [[TransPort]] **TransPort** \['address':]__port__|**auto** [_isolation flags_]:: Open this port to listen for transparent proxy connections. Set this to 0 if you don't want to allow transparent proxy 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 + specified multiple times to bind to multiple addresses/ports. If multiple + entries of this option are present in your configuration file, Tor will + perform stream isolation between listeners by default. See SOCKSPort for an explanation of isolation flags. + + TransPort requires OS support for transparent proxies, such as BSDs' pf or @@ -1488,7 +1551,9 @@ The following options are useful only for clients (that is, if included in old versions of FreeBSD, etc) using the NATD protocol. 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 + specified multiple times to bind to multiple addresses/ports. If multiple + entries of this option are present in your configuration file, Tor will + perform stream isolation between listeners by default. See SocksPort for an explanation of isolation flags. + + This option is only for people who cannot use TransPort. (Default: 0) @@ -1753,6 +1818,12 @@ The following options are useful only for clients (that is, if other clients prefer IPv4. Other things may influence the choice. This option breaks a tie to the favor of IPv6. (Default: auto) +[[ClientAutoIPv6ORPort]] **ClientAutoIPv6ORPort** **0**|**1**:: + If this option is set to 1, Tor clients randomly prefer a node's IPv4 or + IPv6 ORPort. The random preference is set every time a node is loaded + from a new consensus or bridge config. When this option is set to 1, + **ClientPreferIPv6ORPort** is ignored. (Default: 0) + [[PathsNeededToBuildCircuits]] **PathsNeededToBuildCircuits** __NUM__:: Tor clients don't build circuits for user traffic until they know about enough of the network so that they could potentially construct @@ -1794,6 +1865,43 @@ The following options are useful only for clients (that is, if Try this many simultaneous connections to download a consensus before waiting for one to complete, timeout, or error out. (Default: 3) +[[DormantClientTimeout]] **DormantClientTimeout** __N__ **minutes**|**hours**|**days**|**weeks**:: + If Tor spends this much time without any client activity, + enter a dormant state where automatic circuits are not built, and + directory information is not fetched. + Does not affect servers or onion services. Must be at least 10 minutes. + (Default: 24 hours) + +[[DormantTimeoutDisabledByIdleStreams]] **DormantTimeoutDisabledByIdleStreams** **0**|**1**:: + If true, then any open client stream (even one not reading or writing) + counts as client activity for the purpose of DormantClientTimeout. + If false, then only network activity counts. (Default: 1) + +[[DormantOnFirstStartup]] **DormantOnFirstStartup** **0**|**1**:: + If true, then the first time Tor starts up with a fresh DataDirectory, + it starts in dormant mode, and takes no actions until the user has made + a request. (This mode is recommended if installing a Tor client for a + user who might not actually use it.) If false, Tor bootstraps the first + time it is started, whether it sees a user request or not. + + + After the first time Tor starts, it begins in dormant mode if it was + dormant before, and not otherwise. (Default: 0) + +[[DormantCanceledByStartup]] **DormantCanceledByStartup** **0**|**1**:: + By default, Tor starts in active mode if it was active the last time + it was shut down, and in dormant mode if it was dormant. But if + this option is true, Tor treats every startup event as user + activity, and Tor will never start in Dormant mode, even if it has + been unused for a long time on previous runs. (Default: 0) + + + Note: Packagers and application developers should change the value of + this option only with great caution: it has the potential to + create spurious traffic on the network. This option should only + be used if Tor is started by an affirmative user activity (like + clicking on an applcation or running a command), and not if Tor + is launched for some other reason (for example, by a startup + process, or by an application that launches itself on every login.) + SERVER OPTIONS -------------- @@ -1856,13 +1964,14 @@ is non-zero): exit according to the ExitPolicy option, the ReducedExitPolicy option, or the default ExitPolicy (if no other exit policy option is specified). + + - If ExitRelay is set to 0, no traffic is allowed to - exit, and the ExitPolicy and ReducedExitPolicy options are ignored. + + If ExitRelay is set to 0, no traffic is allowed to exit, and the + ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored. + + - If ExitRelay is set to "auto", then Tor checks the ExitPolicy and - ReducedExitPolicy options. If either is set, Tor behaves as if ExitRelay - were set to 1. If neither exit policy option is set, Tor behaves as if - ExitRelay were set to 0. (Default: auto) + If ExitRelay is set to "auto", then Tor checks the ExitPolicy, + ReducedExitPolicy, and IPv6Exit options. If at least one of these options + is set, Tor behaves as if ExitRelay were set to 1. If none of these exit + policy options are set, Tor behaves as if ExitRelay were set to 0. + (Default: auto) [[ExitPolicy]] **ExitPolicy** __policy__,__policy__,__...__:: Set an exit policy for this server. Each policy is of the form @@ -2057,8 +2166,9 @@ is non-zero): (Default: 0) [[IPv6Exit]] **IPv6Exit** **0**|**1**:: - If set, and we are an exit node, allow clients to use us for IPv6 - traffic. (Default: 0) + If set, and we are an exit node, allow clients to use us for IPv6 traffic. + When this option is set and ExitRelay is auto, we act as if ExitRelay + is 1. (Default: 0) [[MaxOnionQueueDelay]] **MaxOnionQueueDelay** __NUM__ [**msec**|**second**]:: If we have more onionskins queued for processing than we can process in @@ -2217,7 +2327,8 @@ is non-zero): __filename__. The file format is the same as the standard Unix "**resolv.conf**" file (7). This option, like all other ServerDNS options, only affects name lookups that your server does on behalf of clients. - (Defaults to use the system DNS configuration.) + (Defaults to use the system DNS configuration or a localhost DNS service + in case no nameservers are found in a given configuration.) [[ServerDNSAllowBrokenConfig]] **ServerDNSAllowBrokenConfig** **0**|**1**:: If this option is false, Tor exits immediately if there are problems @@ -2257,7 +2368,8 @@ is non-zero): When this option is enabled and BridgeRelay is also enabled, and we have GeoIP data, Tor keeps a per-country count of how many client addresses have contacted it so that it can help the bridge authority guess - which countries have blocked access to it. (Default: 1) + which countries have blocked access to it. If ExtraInfoStatistics is + enabled, it will be published as part of extra-info document. (Default: 1) [[ServerDNSRandomizeCase]] **ServerDNSRandomizeCase** **0**|**1**:: When this option is set, Tor sets the case of each character randomly in @@ -2339,6 +2451,10 @@ is non-zero): [[ExtraInfoStatistics]] **ExtraInfoStatistics** **0**|**1**:: When this option is enabled, Tor includes previously gathered statistics in its extra-info documents that it uploads to the directory authorities. + Disabling this option also removes bandwidth usage statistics, and + GeoIPFile and GeoIPv6File hashes from the extra-info file. Bridge + ServerTransportPlugin lines are always includes in the extra-info file, + because they are required by BridgeDB. (Default: 1) [[ExtendAllowPrivateAddresses]] **ExtendAllowPrivateAddresses** **0**|**1**:: @@ -2806,6 +2922,8 @@ 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. If DIRECTORY does not exist, Tor will create it. + Please note that you cannot add new Onion Service to already running Tor + instance if **Sandbox** is enabled. (Note: in current versions of Tor, if DIRECTORY is a relative path, it will be relative to the current working directory of Tor instance, not to its DataDirectory. Do not @@ -3260,10 +3378,6 @@ __CacheDirectory__**/cached-microdescs** and **cached-microdescs.new**:: router. The ".new" file is an append-only journal; when it gets too large, all entries are merged into a new cached-microdescs file. -__CacheDirectory__**/cached-routers** and **cached-routers.new**:: - Obsolete versions of cached-descriptors and cached-descriptors.new. When - Tor can't find the newer files, it looks here instead. - __DataDirectory__**/state**:: A set of persistent key-value mappings. These are documented in the file. These include: |