[tor-commits] [tor/master] manpage: alphabetize client options
nickm at torproject.org
nickm at torproject.org
Mon Jan 13 18:26:30 UTC 2020
commit ec52c8ed69da64a105f7f9dc7abfa59a3943ec64
Author: Swati Thacker <swati.kgp13 at gmail.com>
Date: Fri Dec 27 00:22:54 2019 +0530
manpage: alphabetize client options
Alphabetize client options in tor.1.txt. Closes ticket32846.
---
changes/ticket32846 | 3 +
doc/tor.1.txt | 1168 ++++++++++++++++++++++++++-------------------------
2 files changed, 593 insertions(+), 578 deletions(-)
diff --git a/changes/ticket32846 b/changes/ticket32846
new file mode 100644
index 000000000..5022c6145
--- /dev/null
+++ b/changes/ticket32846
@@ -0,0 +1,3 @@
+ o Documentation (manpage):
+ - Alphabetize the Client Options section of the tor manpage.
+ Closes ticket 32846.
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index e1738c9ba..c843112d0 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -954,10 +954,30 @@ forward slash (/) in the configuration file and on the command line.
== CLIENT OPTIONS
+// These options are in alphabetical order, with exceptions as noted.
+// Please keep them that way!
+
The following options are useful only for clients (that is, if
**SocksPort**, **HTTPTunnelPort**, **TransPort**, **DNSPort**, or
**NATDPort** is non-zero):
+[[AllowNonRFC953Hostnames]] **AllowNonRFC953Hostnames** **0**|**1**::
+ When this option is disabled, Tor blocks hostnames containing illegal
+ characters (like @ and :) rather than sending them to an exit node to be
+ resolved. This helps trap accidental attempts to resolve URLs and so on.
+ (Default: 0)
+
+[[AutomapHostsOnResolve]] **AutomapHostsOnResolve** **0**|**1**::
+ When this option is enabled, and we get a request to resolve an address
+ that ends with one of the suffixes in **AutomapHostsSuffixes**, we map an
+ unused virtual address to that address, and return the new virtual address.
+ This is handy for making ".onion" addresses work with applications that
+ resolve an address and then connect to it. (Default: 0)
+
+[[AutomapHostsSuffixes]] **AutomapHostsSuffixes** __SUFFIX__,__SUFFIX__,__...__::
+ A comma-separated list of suffixes to use with **AutomapHostsOnResolve**.
+ The "." suffix is equivalent to "all addresses." (Default: .exit,.onion).
+
[[Bridge]] **Bridge** [__transport__] __IP__:__ORPort__ [__fingerprint__]::
When set along with UseBridges, instructs Tor to use the relay at
"IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint"
@@ -978,6 +998,7 @@ The following options are useful only for clients (that is, if
the documentation of the pluggable transport for details of what
arguments it supports.
+// Out of order because it logically belongs before the CircuitBuildTimeout option
[[LearnCircuitBuildTimeout]] **LearnCircuitBuildTimeout** **0**|**1**::
If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1)
@@ -989,6 +1010,14 @@ The following options are useful only for clients (that is, if
LearnCircuitBuildTimeout is 0, this value is the only value used.
(Default: 60 seconds)
+[[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)
+
[[CircuitsAvailableTimeout]] **CircuitsAvailableTimeout** __NUM__::
Tor will attempt to keep at least one open, unused circuit available for
this amount of time. This option governs how long idle circuits are kept
@@ -1005,6 +1034,58 @@ The following options are useful only for clients (that is, if
If your network is particularly slow, you might want to set this to a
number like 60. (Default: 0)
+[[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)
+
+[[ClientBootstrapConsensusAuthorityDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityDownloadInitialDelay** __N__::
+ Initial delay in seconds 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: 6)
+
+[[ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay** __N__::
+ Initial delay in seconds 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)
+
+[[ClientBootstrapConsensusFallbackDownloadInitialDelay]] **ClientBootstrapConsensusFallbackDownloadInitialDelay** __N__::
+ Initial delay in seconds 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)
+
+[[ClientBootstrapConsensusMaxInProgressTries]] **ClientBootstrapConsensusMaxInProgressTries** __NUM__::
+ Try this many simultaneous connections to download a consensus before
+ waiting for one to complete, timeout, or error out. (Default: 3)
+
+[[ClientDNSRejectInternalAddresses]] **ClientDNSRejectInternalAddresses** **0**|**1**::
+ If true, Tor does not believe any anonymously retrieved DNS answer that
+ tells it that an address resolves to an internal address (like 127.0.0.1 or
+ 192.168.0.1). This option prevents certain browser-based attacks; it
+ is not allowed to be set on the default network. (Default: 1)
+
+[[ClientOnionAuthDir]] **ClientOnionAuthDir** __path__::
+ Path to the directory containing v3 hidden service authorization files.
+ Each file is for a single onion address, and the files MUST have the suffix
+ ".auth_private" (i.e. "bob_onion.auth_private"). The content format MUST be:
+ +
+ <onion-address>:descriptor:x25519:<base32-encoded-privkey>
+ +
+ The <onion-address> MUST NOT have the ".onion" suffix. The
+ <base32-encoded-privkey> is the base32 representation of the raw key bytes
+ only (32 bytes for x25519). See Appendix G in the rend-spec-v3.txt file of
+ https://spec.torproject.org/[torspec] for more information.
+
[[ClientOnly]] **ClientOnly** **0**|**1**::
If set to 1, Tor will not run as a relay or serve
directory requests, even if the ORPort, ExtORPort, or DirPort options are
@@ -1014,6 +1095,43 @@ The following options are useful only for clients (that is, if
and fast enough. The current behavior is simply that Tor is a client
unless ORPort, ExtORPort, or DirPort are configured.) (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) (DEPRECATED: This option has had no effect for some
+ time.)
+
+[[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. (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)
+
+[[ClientRejectInternalAddresses]] **ClientRejectInternalAddresses** **0**|**1**::
+ If true, Tor does not try to fulfill requests to connect to an internal
+ address (like 127.0.0.1 or 192.168.0.1) __unless an exit node is
+ specifically requested__ (for example, via a .exit hostname, or a
+ controller request). If true, multicast DNS hostnames for machines on the
+ local network (of the form *.local) are also rejected. (Default: 1)
+
+[[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 directory servers or
+ entry nodes over IPv6. For IPv6 only hosts, you need to also set
+ **ClientUseIPv4** to 0 to disable IPv4. Note that clients configured with
+ an IPv6 address in a **Bridge**, proxy, or pluggable transportline will
+ try connecting over IPv6 even if **ClientUseIPv6** is set to 0. (Default: 0)
+
[[ConnectionPadding]] **ConnectionPadding** **0**|**1**|**auto**::
This option governs Tor's use of padding to defend against some forms of
traffic analysis. If it is set to 'auto', Tor will send padding only
@@ -1024,25 +1142,74 @@ The following options are useful only for clients (that is, if
for use where bandwidth may be expensive.
(Default: auto)
-[[ReducedConnectionPadding]] **ReducedConnectionPadding** **0**|**1**::
- If set to 1, Tor will not not hold OR connections open for very long,
- and will send less padding on these connections. 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)
+[[DNSPort]] **DNSPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]::
+ If non-zero, open this port to listen for UDP DNS requests, and resolve
+ them anonymously. This port only handles A, AAAA, and PTR requests---it
+ 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
+ flags. (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)
+[[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.)
-[[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)
+[[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)
+
+[[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)
+
+[[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)
+
+[[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 server descriptors. Tor does not use this information for anything
+ itself; to save bandwidth, leave this option turned off. (Default: 0)
+
+[[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)
+
+[[EntryNodes]] **EntryNodes** __node__,__node__,__...__::
+ 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
+ option overrides this option; if you have configured bridges and
+ 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. See
+ the **ExcludeNodes** option for more information on how to specify nodes.
[[ExcludeNodes]] **ExcludeNodes** __node__,__node__,__...__::
A list of identity fingerprints, country codes, and address
@@ -1068,7 +1235,7 @@ The following options are useful only for clients (that is, if
country can't be identified. No country code, including \{??}, works if
no GeoIPFile can be loaded. See also the GeoIPExcludeUnknown option below.
-
+// Out of order because it logically belongs after the ExcludeNodes option
[[ExcludeExitNodes]] **ExcludeExitNodes** __node__,__node__,__...__::
A list of identity fingerprints, country codes, and address
patterns of nodes to never use when picking an exit node---that is, a
@@ -1078,14 +1245,6 @@ The following options are useful only for clients (that is, if
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
- ExcludeNodes or ExcludeExitNodes, all nodes with unknown country (\{??} and
- possibly \{A1}) are treated as excluded as well. If this option is set to
- '1', then all unknown countries are treated as excluded in ExcludeNodes
- and ExcludeExitNodes. This option has no effect when a GeoIP file isn't
- configured or can't be found. (Default: auto)
-
[[ExitNodes]] **ExitNodes** __node__,__node__,__...__::
A list of identity fingerprints, country codes, and address
patterns of nodes to use as exit node---that is, a
@@ -1110,51 +1269,6 @@ 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.
- Normal circuits include all
- circuits except for direct connections to directory servers. The Bridge
- option overrides this option; if you have configured bridges and
- 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. 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 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 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
that your firewall allows (defaults to 80 and 443; see **FirewallPorts**).
@@ -1168,35 +1282,13 @@ The following options are useful only for clients (that is, if
**FascistFirewall** is set. This option is deprecated; use ReachableAddresses
instead. (Default: 80, 443)
-[[ReachableAddresses]] **ReachableAddresses** __IP__[/__MASK__][:__PORT__]...::
- A comma-separated list of IP addresses and ports that your firewall allows
- you to connect to. The format is as for the addresses in ExitPolicy, except
- that "accept" is understood unless "reject" is explicitly provided. For
- example, \'ReachableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept
- \*:80' means that your firewall allows connections to everything inside net
- 99, rejects port 80 connections to net 18, and accepts connections to port
- 80 otherwise. (Default: \'accept \*:*'.)
-
-[[ReachableDirAddresses]] **ReachableDirAddresses** __IP__[/__MASK__][:__PORT__]...::
- Like **ReachableAddresses**, a list of addresses and ports. Tor will obey
- these restrictions when fetching directory information, using standard HTTP
- GET requests. If not set explicitly then the value of
- **ReachableAddresses** is used. If **HTTPProxy** is set then these
- connections will go through that proxy. (DEPRECATED: This option has
- had no effect for some time.)
-
-[[ReachableORAddresses]] **ReachableORAddresses** __IP__[/__MASK__][:__PORT__]...::
- Like **ReachableAddresses**, a list of addresses and ports. Tor will obey
- these restrictions when connecting to Onion Routers, using TLS/SSL. If not
- set explicitly then the value of **ReachableAddresses** is used. If
- **HTTPSProxy** is set then these connections will go through that proxy. +
- +
- The separation between **ReachableORAddresses** and
- **ReachableDirAddresses** is only interesting when you are connecting
- through proxies (see **HTTPProxy** and **HTTPSProxy**). Most proxies limit
- TLS connections (which Tor uses to connect to Onion Routers) to port 443,
- and some limit HTTP GET requests (which Tor uses for fetching directory
- information) to port 80.
+[[GeoIPExcludeUnknown]] **GeoIPExcludeUnknown** **0**|**1**|**auto**::
+ If this option is set to 'auto', then whenever any country code is set in
+ ExcludeNodes or ExcludeExitNodes, all nodes with unknown country (\{??} and
+ possibly \{A1}) are treated as excluded as well. If this option is set to
+ '1', then all unknown countries are treated as excluded in ExcludeNodes
+ and ExcludeExitNodes. This option has no effect when a GeoIP file isn't
+ configured or can't be found. (Default: auto)
[[HidServAuth]] **HidServAuth** __onion-address__ __auth-cookie__ [__service-name__]::
Client authorization for a v2 hidden service. Valid onion addresses contain 16
@@ -1208,17 +1300,125 @@ The following options are useful only for clients (that is, if
services can be configured to require authorization using the
**HiddenServiceAuthorizeClient** option.
-[[ClientOnionAuthDir]] **ClientOnionAuthDir** __path__::
- Path to the directory containing v3 hidden service authorization files.
- Each file is for a single onion address, and the files MUST have the suffix
- ".auth_private" (i.e. "bob_onion.auth_private"). The content format MUST be:
+[[HSLayer2Nodes]] **HSLayer2Nodes** __node__,__node__,__...__::
+ A list of identity fingerprints, nicknames, country codes, and
+ address patterns of nodes that are allowed to be used as the
+ second hop in all client or service-side Onion Service circuits.
+ This option mitigates attacks where the adversary runs middle nodes
+ and induces your client or service to create many circuits, in order
+ to discover your primary guard node.
+ (Default: Any node in the network may be used in the second hop.)
+
- <onion-address>:descriptor:x25519:<base32-encoded-privkey>
+ (Example:
+ HSLayer2Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) +
+
- The <onion-address> MUST NOT have the ".onion" suffix. The
- <base32-encoded-privkey> is the base32 representation of the raw key bytes
- only (32 bytes for x25519). See Appendix G in the rend-spec-v3.txt file of
- https://spec.torproject.org/[torspec] for more information.
+ When this is set, the resulting hidden service paths will
+ look like:
+ +
+ C - G - L2 - M - Rend +
+ C - G - L2 - M - HSDir +
+ C - G - L2 - M - Intro +
+ S - G - L2 - M - Rend +
+ S - G - L2 - M - HSDir +
+ S - G - L2 - M - Intro +
+ +
+ where C is this client, S is the service, G is the Guard node,
+ L2 is a node from this option, and M is a random middle node.
+ Rend, HSDir, and Intro point selection is not affected by this
+ option.
+ +
+ This option may be combined with HSLayer3Nodes to create
+ paths of the form:
+ +
+ C - G - L2 - L3 - Rend +
+ C - G - L2 - L3 - M - HSDir +
+ C - G - L2 - L3 - M - Intro +
+ S - G - L2 - L3 - M - Rend +
+ S - G - L2 - L3 - HSDir +
+ S - G - L2 - L3 - Intro +
+ +
+ ExcludeNodes have higher priority than HSLayer2Nodes,
+ which means that nodes specified in ExcludeNodes will not be
+ picked.
+ +
+ When either this option or HSLayer3Nodes are set, the /16 subnet
+ and node family restrictions are removed for hidden service
+ circuits. Additionally, we allow the guard node to be present
+ as the Rend, HSDir, and IP node, and as the hop before it. This
+ is done to prevent the adversary from inferring information
+ about our guard, layer2, and layer3 node choices at later points
+ in the path.
+ +
+ This option is meant to be managed by a Tor controller such as
+ https://github.com/mikeperry-tor/vanguards that selects and
+ updates this set of nodes for you. Hence it does not do load
+ balancing if fewer than 20 nodes are selected, and if no nodes in
+ HSLayer2Nodes are currently available for use, Tor will not work.
+ Please use extreme care if you are setting this option manually.
+
+[[HSLayer3Nodes]] **HSLayer3Nodes** __node__,__node__,__...__::
+ A list of identity fingerprints, nicknames, country codes, and
+ address patterns of nodes that are allowed to be used as the
+ third hop in all client and service-side Onion Service circuits.
+ This option mitigates attacks where the adversary runs middle nodes
+ and induces your client or service to create many circuits, in order
+ to discover your primary or Layer2 guard nodes.
+ (Default: Any node in the network may be used in the third hop.)
+ +
+ (Example:
+ HSLayer3Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) +
+ +
+ When this is set by itself, the resulting hidden service paths
+ will look like: +
+ C - G - M - L3 - Rend +
+ C - G - M - L3 - M - HSDir +
+ C - G - M - L3 - M - Intro +
+ S - G - M - L3 - M - Rend +
+ S - G - M - L3 - HSDir +
+ S - G - M - L3 - Intro +
+ where C is this client, S is the service, G is the Guard node,
+ L2 is a node from this option, and M is a random middle node.
+ Rend, HSDir, and Intro point selection is not affected by this
+ option.
+ +
+ While it is possible to use this option by itself, it should be
+ combined with HSLayer2Nodes to create paths of the form:
+ +
+ C - G - L2 - L3 - Rend +
+ C - G - L2 - L3 - M - HSDir +
+ C - G - L2 - L3 - M - Intro +
+ S - G - L2 - L3 - M - Rend +
+ S - G - L2 - L3 - HSDir +
+ S - G - L2 - L3 - Intro +
+ +
+ ExcludeNodes have higher priority than HSLayer3Nodes,
+ which means that nodes specified in ExcludeNodes will not be
+ picked.
+ +
+ When either this option or HSLayer2Nodes are set, the /16 subnet
+ and node family restrictions are removed for hidden service
+ circuits. Additionally, we allow the guard node to be present
+ as the Rend, HSDir, and IP node, and as the hop before it. This
+ is done to prevent the adversary from inferring information
+ about our guard, layer2, and layer3 node choices at later points
+ in the path.
+ +
+ This option is meant to be managed by a Tor controller such as
+ https://github.com/mikeperry-tor/vanguards that selects and
+ updates this set of nodes for you. Hence it does not do load
+ balancing if fewer than 20 nodes are selected, and if no nodes in
+ HSLayer3Nodes are currently available for use, Tor will not work.
+ Please use extreme care if you are setting this option manually.
+
+[[HTTPTunnelPort]] **HTTPTunnelPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]::
+ Open this port to listen for proxy connections using the "HTTP CONNECT"
+ 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. 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)
[[LongLivedPorts]] **LongLivedPorts** __PORTS__::
A list of ports for services that tend to have long-running connections
@@ -1281,10 +1481,6 @@ The following options are useful only for clients (that is, if
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)
-
[[MaxCircuitDirtiness]] **MaxCircuitDirtiness** __NUM__::
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
@@ -1299,6 +1495,42 @@ The following options are useful only for clients (that is, if
client streams. A circuit is pending if we have begun constructing it,
but it has not yet been completely constructed. (Default: 32)
+[[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.
+
+[[NATDPort]] **NATDPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]::
+ Open this port to listen for connections from old versions of ipfw (as
+ 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. 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)
+
+[[NewCircuitPeriod]] **NewCircuitPeriod** __NUM__::
+ Every NUM seconds consider whether to build a new circuit. (Default: 30
+ seconds)
+
[[NodeFamily]] **NodeFamily** __node__,__node__,__...__::
The Tor servers, defined by their identity fingerprints,
constitute a "family" of similar or co-administered servers, so never use
@@ -1309,36 +1541,168 @@ The following options are useful only for clients (that is, if
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)
+[[OptimisticData]] **OptimisticData** **0**|**1**|**auto**::
+ When this option is set, and Tor is using an exit node that supports
+ the feature, it will try optimistically to send data to the exit node
+ without waiting for the exit node to report whether the connection
+ succeeded. This can save a round-trip time for protocols like HTTP
+ where the client talks first. If OptimisticData is set to **auto**,
+ Tor will look at the UseOptimisticData parameter in the networkstatus.
+ (Default: auto)
-[[SocksPort]] **SocksPort** ['address'**:**]{empty}__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. If a unix domain socket is used, you may
- quote the path using standard C escape sequences.
- (Default: 9050) +
+// These are out of order because they logically belong together
+[[PathBiasCircThreshold]] **PathBiasCircThreshold** __NUM__ +
+
+[[PathBiasDropGuards]] **PathBiasDropGuards** __NUM__ +
+
+[[PathBiasExtremeRate]] **PathBiasExtremeRate** __NUM__ +
+
+[[PathBiasNoticeRate]] **PathBiasNoticeRate** __NUM__ +
+
+[[PathBiasWarnRate]] **PathBiasWarnRate** __NUM__ +
+
+[[PathBiasScaleThreshold]] **PathBiasScaleThreshold** __NUM__::
+ These options override the default behavior of Tor's (**currently
+ experimental**) path bias detection algorithm. To try to find broken or
+ misbehaving guard nodes, Tor looks for nodes where more than a certain
+ fraction of circuits through that guard fail to get built. +
+
- 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 PathBiasCircThreshold option controls how many circuits we need to build
+ through a guard before we make these checks. The PathBiasNoticeRate,
+ PathBiasWarnRate and PathBiasExtremeRate options control what fraction of
+ circuits must succeed through a guard so we won't write log messages.
+ If less than PathBiasExtremeRate circuits succeed *and* PathBiasDropGuards
+ is set to 1, we disable use of that guard. +
+
- 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:
- **IsolateClientAddr**;;
- Don't share circuits with streams from a different
- client address. (On by default and strongly recommended when
- supported; you can disable it with **NoIsolateClientAddr**.
+ When we have seen more than PathBiasScaleThreshold
+ circuits through a guard, we scale our observations by 0.5 (governed by
+ the consensus) so that new observations don't get swamped by old ones. +
+ +
+ By default, or if a negative value is provided for one of these options,
+ Tor uses reasonable defaults from the networkstatus consensus document.
+ If no defaults are available there, these options default to 150, .70,
+ .50, .30, 0, and 300 respectively.
+
+// These are out of order because they logically belong together
+[[PathBiasUseThreshold]] **PathBiasUseThreshold** __NUM__ +
+
+[[PathBiasNoticeUseRate]] **PathBiasNoticeUseRate** __NUM__ +
+
+[[PathBiasExtremeUseRate]] **PathBiasExtremeUseRate** __NUM__ +
+
+[[PathBiasScaleUseThreshold]] **PathBiasScaleUseThreshold** __NUM__::
+ Similar to the above options, these options override the default behavior
+ of Tor's (**currently experimental**) path use bias detection algorithm. +
+ +
+ Where as the path bias parameters govern thresholds for successfully
+ building circuits, these four path use bias parameters govern thresholds
+ only for circuit usage. Circuits which receive no stream usage
+ are not counted by this detection algorithm. A used circuit is considered
+ successful if it is capable of carrying streams or otherwise receiving
+ well-formed responses to RELAY cells. +
+ +
+ By default, or if a negative value is provided for one of these options,
+ Tor uses reasonable defaults from the networkstatus consensus document.
+ If no defaults are available there, these options default to 20, .80,
+ .60, and 100, respectively.
+
+[[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
+ enough of the possible paths through the network. If this option
+ is set to a fraction between 0.25 and 0.95, Tor won't build circuits
+ until it has enough descriptors or microdescriptors to construct
+ that fraction of possible paths. Note that setting this option too low
+ can make your Tor client less anonymous, and setting it too high can
+ prevent your Tor client from bootstrapping. If this option is negative,
+ Tor will use a default value chosen by the directory authorities. If the
+ directory authorities do not choose a value, Tor will default to 0.6.
+ (Default: -1)
+
+[[ReachableAddresses]] **ReachableAddresses** __IP__[/__MASK__][:__PORT__]...::
+ A comma-separated list of IP addresses and ports that your firewall allows
+ you to connect to. The format is as for the addresses in ExitPolicy, except
+ that "accept" is understood unless "reject" is explicitly provided. For
+ example, \'ReachableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept
+ \*:80' means that your firewall allows connections to everything inside net
+ 99, rejects port 80 connections to net 18, and accepts connections to port
+ 80 otherwise. (Default: \'accept \*:*'.)
+
+[[ReachableDirAddresses]] **ReachableDirAddresses** __IP__[/__MASK__][:__PORT__]...::
+ Like **ReachableAddresses**, a list of addresses and ports. Tor will obey
+ these restrictions when fetching directory information, using standard HTTP
+ GET requests. If not set explicitly then the value of
+ **ReachableAddresses** is used. If **HTTPProxy** is set then these
+ connections will go through that proxy. (DEPRECATED: This option has
+ had no effect for some time.)
+
+[[ReachableORAddresses]] **ReachableORAddresses** __IP__[/__MASK__][:__PORT__]...::
+ Like **ReachableAddresses**, a list of addresses and ports. Tor will obey
+ these restrictions when connecting to Onion Routers, using TLS/SSL. If not
+ set explicitly then the value of **ReachableAddresses** is used. If
+ **HTTPSProxy** is set then these connections will go through that proxy. +
+ +
+ The separation between **ReachableORAddresses** and
+ **ReachableDirAddresses** is only interesting when you are connecting
+ through proxies (see **HTTPProxy** and **HTTPSProxy**). Most proxies limit
+ TLS connections (which Tor uses to connect to Onion Routers) to port 443,
+ and some limit HTTP GET requests (which Tor uses for fetching directory
+ information) to port 80.
+
+[[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)
+
+[[ReducedConnectionPadding]] **ReducedConnectionPadding** **0**|**1**::
+ If set to 1, Tor will not not hold OR connections open for very long,
+ and will send less padding on these connections. 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)
+
+[[RejectPlaintextPorts]] **RejectPlaintextPorts** __port__,__port__,__...__::
+ Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor
+ will instead refuse to make the connection. (Default: None)
+
+[[SafeSocks]] **SafeSocks** **0**|**1**::
+ When this option is enabled, Tor will reject application connections that
+ use unsafe variants of the socks protocol -- ones that only provide an IP
+ address, meaning the application is doing a DNS resolve first.
+ Specifically, these are socks4 and socks5 when not doing remote DNS.
+ (Default: 0)
+
+[[SocksPolicy]] **SocksPolicy** __policy__,__policy__,__...__::
+ Set an entrance policy for this server, to limit who can connect to the
+ SocksPort and DNSPort ports. The policies have the same form as exit
+ policies below, except that port specifiers are ignored. Any address
+ not matched by some entry in the policy is accepted.
+
+[[SocksPort]] **SocksPort** ['address'**:**]{empty}__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. If a unix domain socket is used, you may
+ quote the path using standard C escape sequences.
+ (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. +
+ +
+ 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:
+ **IsolateClientAddr**;;
+ Don't share circuits with streams from a different
+ client address. (On by default and strongly recommended when
+ supported; you can disable it with **NoIsolateClientAddr**.
Unsupported and force-disabled when using Unix domain sockets.)
**IsolateSOCKSAuth**;;
Don't share circuits with streams for which different
@@ -1482,17 +1846,31 @@ The following options are useful only for clients (that is, if
line is used, and all earlier flags are ignored. No error is issued for
conflicting flags.
-[[SocksPolicy]] **SocksPolicy** __policy__,__policy__,__...__::
- Set an entrance policy for this server, to limit who can connect to the
- SocksPort and DNSPort ports. The policies have the same form as exit
- policies below, except that port specifiers are ignored. Any address
- not matched by some entry in the policy is accepted.
-
[[SocksTimeout]] **SocksTimeout** __NUM__::
Let a socks connection wait NUM seconds handshaking, and NUM seconds
unattached waiting for an appropriate circuit, before we fail it. (Default:
2 minutes)
+[[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 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)
+
+[[TestSocks]] **TestSocks** **0**|**1**::
+ When this option is enabled, Tor will make a notice-level log entry for
+ each connection to the Socks port indicating whether the request used a
+ safe socks protocol or an unsafe one (see above entry on SafeSocks). This
+ helps to determine whether an application using Tor is possibly leaking
+ DNS requests. (Default: 0)
+
[[TokenBucketRefillInterval]] **TokenBucketRefillInterval** __NUM__ [**msec**|**second**]::
Set the refill delay interval of Tor's token bucket to NUM milliseconds.
NUM must be between 1 and 1000, inclusive. When Tor is out of bandwidth,
@@ -1520,6 +1898,44 @@ The following options are useful only for clients (that is, if
association between host and exit server after NUM seconds. The default is
1800 seconds (30 minutes).
+[[TransPort]] **TransPort** ['address'**:**]{empty}__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. 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
+ Linux's IPTables. If you're planning to use Tor as a transparent proxy for
+ a network, you'll want to examine and change VirtualAddrNetwork from the
+ default setting. (Default: 0)
+
+[[TransProxyType]] **TransProxyType** **default**|**TPROXY**|**ipfw**|**pf-divert**::
+ TransProxyType may only be enabled when there is transparent proxy listener
+ enabled. +
+ +
+ Set this to "TPROXY" if you wish to be able to use the TPROXY Linux module
+ to transparently proxy connections that are configured using the TransPort
+ option. Detailed information on how to configure the TPROXY
+ feature can be found in the Linux kernel source tree in the file
+ Documentation/networking/tproxy.txt. +
+ +
+ Set this option to "ipfw" to use the FreeBSD ipfw interface. +
+ +
+ On *BSD operating systems when using pf, set this to "pf-divert" to take
+ advantage of +divert-to+ rules, which do not modify the packets like
+ +rdr-to+ rules do. Detailed information on how to configure pf to use
+ +divert-to+ rules can be found in the pf.conf(5) manual page. On OpenBSD,
+ +divert-to+ is available to use on versions greater than or equal to
+ OpenBSD 4.4. +
+ +
+ Set this to "default", or leave it unconfigured, to use regular IPTables
+ on Linux, or to use pf +rdr-to+ rules on *BSD systems. +
+ +
+ (Default: "default")
+
[[UpdateBridgesFromAuthority]] **UpdateBridgesFromAuthority** **0**|**1**::
When set (along with UseBridges), Tor will try to fetch bridge descriptors
from the configured bridge authorities when feasible. It will fall back to
@@ -1538,6 +1954,7 @@ The following options are useful only for clients (that is, if
Authorities or Single Onion Services. In these cases,
this option is ignored. (Default: 1)
+//Out of order because it logically belongs with the UseGuardFraction option
[[GuardfractionFile]] **GuardfractionFile** __FILENAME__::
V3 authoritative directories only. Configures the location of the
guardfraction file which contains information about how long relays
@@ -1549,12 +1966,27 @@ The following options are useful only for clients (that is, if
selection. If it's set to 'auto', clients will do what the
UseGuardFraction consensus parameter tells them to do. (Default: auto)
+//Out of order because it logically belongs after the UseEntryGuards option
+[[GuardLifetime]] **GuardLifetime** __N__ **days**|**weeks**|**months**::
+ If UseEntryGuards is set, minimum time to keep a guard on our guard list
+ before picking a new one. If less than one day, we use defaults from the
+ consensus directory. (Default: 0)
+
+//Out of order because it logically belongs after the UseEntryGuards option
+[[NumDirectoryGuards]] **NumDirectoryGuards** __NUM__::
+ If UseEntryGuards is set to 1, we try to make sure we have at least NUM
+ routers to use as directory guards. If this option is set to 0, use the
+ value from the guard-n-primary-dir-guards-to-use consensus parameter, and
+ default to 3 if the consensus parameter isn't set. (Default: 0)
+
+//Out of order because it logically belongs after the UseEntryGuards option
[[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 the
number from the guard-n-primary-guards-to-use consensus parameter, and
default to 1 if the consensus parameter isn't set. (Default: 0)
+//Out of order because it logically belongs after the UseEntryGuards option
[[NumPrimaryGuards]] **NumPrimaryGuards** __NUM__::
If UseEntryGuards is set to 1, we will try to pick NUM routers for our
primary guard list, which is the set of routers we strongly prefer when
@@ -1562,30 +1994,13 @@ The following options are useful only for clients (that is, if
the guard-n-primary-guards consensus parameter, and default to 3 if the
consensus parameter isn't set. (Default: 0)
-[[NumDirectoryGuards]] **NumDirectoryGuards** __NUM__::
- If UseEntryGuards is set to 1, we try to make sure we have at least NUM
- routers to use as directory guards. If this option is set to 0, use the
- value from the guard-n-primary-dir-guards-to-use consensus parameter, and
- default to 3 if the consensus parameter isn't set. (Default: 0)
-
-[[GuardLifetime]] **GuardLifetime** __N__ **days**|**weeks**|**months**::
- If UseEntryGuards is set, minimum time to keep a guard on our guard list
- before picking a new one. If less than one day, we use defaults from the
- consensus directory. (Default: 0)
-
-[[SafeSocks]] **SafeSocks** **0**|**1**::
- When this option is enabled, Tor will reject application connections that
- use unsafe variants of the socks protocol -- ones that only provide an IP
- address, meaning the application is doing a DNS resolve first.
- Specifically, these are socks4 and socks5 when not doing remote DNS.
- (Default: 0)
-
-[[TestSocks]] **TestSocks** **0**|**1**::
- When this option is enabled, Tor will make a notice-level log entry for
- each connection to the Socks port indicating whether the request used a
- safe socks protocol or an unsafe one (see above entry on SafeSocks). This
- helps to determine whether an application using Tor is possibly leaking
- DNS requests. (Default: 0)
+[[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
+ download less directory information, thus saving bandwidth. Directory
+ caches need to fetch regular descriptors and microdescriptors, so this
+ option doesn't save any bandwidth for them. For legacy reasons, auto is
+ accepted, but it has the same effect as 1. (Default: auto)
[[VirtualAddrNetworkIPv4]] **VirtualAddrNetworkIPv4** __IPv4Address__/__bits__ +
@@ -1606,415 +2021,12 @@ The following options are useful only for clients (that is, if
used IP. For local use, no change to the default VirtualAddrNetwork setting
is needed.
-[[AllowNonRFC953Hostnames]] **AllowNonRFC953Hostnames** **0**|**1**::
- When this option is disabled, Tor blocks hostnames containing illegal
- characters (like @ and :) rather than sending them to an exit node to be
- resolved. This helps trap accidental attempts to resolve URLs and so on.
- (Default: 0)
-
-[[HTTPTunnelPort]] **HTTPTunnelPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]::
- Open this port to listen for proxy connections using the "HTTP CONNECT"
- 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. 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)
+[[WarnPlaintextPorts]] **WarnPlaintextPorts** __port__,__port__,__...__::
+ Tells Tor to issue a warnings whenever the user tries to make an anonymous
+ connection to one of these ports. This option is designed to alert users
+ to services that risk sending passwords in the clear. (Default:
+ 23,109,110,143)
-[[TransPort]] **TransPort** ['address'**:**]{empty}__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. 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
- Linux's IPTables. If you're planning to use Tor as a transparent proxy for
- a network, you'll want to examine and change VirtualAddrNetwork from the
- default setting. (Default: 0)
-
-[[TransProxyType]] **TransProxyType** **default**|**TPROXY**|**ipfw**|**pf-divert**::
- TransProxyType may only be enabled when there is transparent proxy listener
- enabled. +
- +
- Set this to "TPROXY" if you wish to be able to use the TPROXY Linux module
- to transparently proxy connections that are configured using the TransPort
- option. Detailed information on how to configure the TPROXY
- feature can be found in the Linux kernel source tree in the file
- Documentation/networking/tproxy.txt. +
- +
- Set this option to "ipfw" to use the FreeBSD ipfw interface. +
- +
- On *BSD operating systems when using pf, set this to "pf-divert" to take
- advantage of +divert-to+ rules, which do not modify the packets like
- +rdr-to+ rules do. Detailed information on how to configure pf to use
- +divert-to+ rules can be found in the pf.conf(5) manual page. On OpenBSD,
- +divert-to+ is available to use on versions greater than or equal to
- OpenBSD 4.4. +
- +
- Set this to "default", or leave it unconfigured, to use regular IPTables
- on Linux, or to use pf +rdr-to+ rules on *BSD systems. +
- +
- (Default: "default")
-
-[[NATDPort]] **NATDPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]::
- Open this port to listen for connections from old versions of ipfw (as
- 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. 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)
-
-[[AutomapHostsOnResolve]] **AutomapHostsOnResolve** **0**|**1**::
- When this option is enabled, and we get a request to resolve an address
- that ends with one of the suffixes in **AutomapHostsSuffixes**, we map an
- unused virtual address to that address, and return the new virtual address.
- This is handy for making ".onion" addresses work with applications that
- resolve an address and then connect to it. (Default: 0)
-
-[[AutomapHostsSuffixes]] **AutomapHostsSuffixes** __SUFFIX__,__SUFFIX__,__...__::
- A comma-separated list of suffixes to use with **AutomapHostsOnResolve**.
- The "." suffix is equivalent to "all addresses." (Default: .exit,.onion).
-
-[[DNSPort]] **DNSPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]::
- If non-zero, open this port to listen for UDP DNS requests, and resolve
- them anonymously. This port only handles A, AAAA, and PTR requests---it
- 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
- flags. (Default: 0)
-
-[[ClientDNSRejectInternalAddresses]] **ClientDNSRejectInternalAddresses** **0**|**1**::
- If true, Tor does not believe any anonymously retrieved DNS answer that
- tells it that an address resolves to an internal address (like 127.0.0.1 or
- 192.168.0.1). This option prevents certain browser-based attacks; it
- is not allowed to be set on the default network. (Default: 1)
-
-[[ClientRejectInternalAddresses]] **ClientRejectInternalAddresses** **0**|**1**::
- If true, Tor does not try to fulfill requests to connect to an internal
- address (like 127.0.0.1 or 192.168.0.1) __unless an exit node is
- specifically requested__ (for example, via a .exit hostname, or a
- controller request). If true, multicast DNS hostnames for machines on the
- local network (of the form *.local) are also rejected. (Default: 1)
-
-[[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 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__,__...__::
- Tells Tor to issue a warnings whenever the user tries to make an anonymous
- connection to one of these ports. This option is designed to alert users
- to services that risk sending passwords in the clear. (Default:
- 23,109,110,143)
-
-[[RejectPlaintextPorts]] **RejectPlaintextPorts** __port__,__port__,__...__::
- Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor
- will instead refuse to make the connection. (Default: None)
-
-[[OptimisticData]] **OptimisticData** **0**|**1**|**auto**::
- When this option is set, and Tor is using an exit node that supports
- the feature, it will try optimistically to send data to the exit node
- without waiting for the exit node to report whether the connection
- succeeded. This can save a round-trip time for protocols like HTTP
- where the client talks first. If OptimisticData is set to **auto**,
- Tor will look at the UseOptimisticData parameter in the networkstatus.
- (Default: auto)
-
-[[HSLayer2Nodes]] **HSLayer2Nodes** __node__,__node__,__...__::
- A list of identity fingerprints, nicknames, country codes, and
- address patterns of nodes that are allowed to be used as the
- second hop in all client or service-side Onion Service circuits.
- This option mitigates attacks where the adversary runs middle nodes
- and induces your client or service to create many circuits, in order
- to discover your primary guard node.
- (Default: Any node in the network may be used in the second hop.)
- +
- (Example:
- HSLayer2Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) +
- +
- When this is set, the resulting hidden service paths will
- look like:
- +
- C - G - L2 - M - Rend +
- C - G - L2 - M - HSDir +
- C - G - L2 - M - Intro +
- S - G - L2 - M - Rend +
- S - G - L2 - M - HSDir +
- S - G - L2 - M - Intro +
- +
- where C is this client, S is the service, G is the Guard node,
- L2 is a node from this option, and M is a random middle node.
- Rend, HSDir, and Intro point selection is not affected by this
- option.
- +
- This option may be combined with HSLayer3Nodes to create
- paths of the form:
- +
- C - G - L2 - L3 - Rend +
- C - G - L2 - L3 - M - HSDir +
- C - G - L2 - L3 - M - Intro +
- S - G - L2 - L3 - M - Rend +
- S - G - L2 - L3 - HSDir +
- S - G - L2 - L3 - Intro +
- +
- ExcludeNodes have higher priority than HSLayer2Nodes,
- which means that nodes specified in ExcludeNodes will not be
- picked.
- +
- When either this option or HSLayer3Nodes are set, the /16 subnet
- and node family restrictions are removed for hidden service
- circuits. Additionally, we allow the guard node to be present
- as the Rend, HSDir, and IP node, and as the hop before it. This
- is done to prevent the adversary from inferring information
- about our guard, layer2, and layer3 node choices at later points
- in the path.
- +
- This option is meant to be managed by a Tor controller such as
- https://github.com/mikeperry-tor/vanguards that selects and
- updates this set of nodes for you. Hence it does not do load
- balancing if fewer than 20 nodes are selected, and if no nodes in
- HSLayer2Nodes are currently available for use, Tor will not work.
- Please use extreme care if you are setting this option manually.
-
-[[HSLayer3Nodes]] **HSLayer3Nodes** __node__,__node__,__...__::
- A list of identity fingerprints, nicknames, country codes, and
- address patterns of nodes that are allowed to be used as the
- third hop in all client and service-side Onion Service circuits.
- This option mitigates attacks where the adversary runs middle nodes
- and induces your client or service to create many circuits, in order
- to discover your primary or Layer2 guard nodes.
- (Default: Any node in the network may be used in the third hop.)
- +
- (Example:
- HSLayer3Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) +
- +
- When this is set by itself, the resulting hidden service paths
- will look like: +
- C - G - M - L3 - Rend +
- C - G - M - L3 - M - HSDir +
- C - G - M - L3 - M - Intro +
- S - G - M - L3 - M - Rend +
- S - G - M - L3 - HSDir +
- S - G - M - L3 - Intro +
- where C is this client, S is the service, G is the Guard node,
- L2 is a node from this option, and M is a random middle node.
- Rend, HSDir, and Intro point selection is not affected by this
- option.
- +
- While it is possible to use this option by itself, it should be
- combined with HSLayer2Nodes to create paths of the form:
- +
- C - G - L2 - L3 - Rend +
- C - G - L2 - L3 - M - HSDir +
- C - G - L2 - L3 - M - Intro +
- S - G - L2 - L3 - M - Rend +
- S - G - L2 - L3 - HSDir +
- S - G - L2 - L3 - Intro +
- +
- ExcludeNodes have higher priority than HSLayer3Nodes,
- which means that nodes specified in ExcludeNodes will not be
- picked.
- +
- When either this option or HSLayer2Nodes are set, the /16 subnet
- and node family restrictions are removed for hidden service
- circuits. Additionally, we allow the guard node to be present
- as the Rend, HSDir, and IP node, and as the hop before it. This
- is done to prevent the adversary from inferring information
- about our guard, layer2, and layer3 node choices at later points
- in the path.
- +
- This option is meant to be managed by a Tor controller such as
- https://github.com/mikeperry-tor/vanguards that selects and
- updates this set of nodes for you. Hence it does not do load
- balancing if fewer than 20 nodes are selected, and if no nodes in
- HSLayer3Nodes are currently available for use, Tor will not work.
- Please use extreme care if you are setting this option manually.
-
-[[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
- download less directory information, thus saving bandwidth. Directory
- caches need to fetch regular descriptors and microdescriptors, so this
- option doesn't save any bandwidth for them. For legacy reasons, auto is
- accepted, but it has the same effect as 1. (Default: auto)
-
-[[PathBiasCircThreshold]] **PathBiasCircThreshold** __NUM__ +
-
-[[PathBiasNoticeRate]] **PathBiasNoticeRate** __NUM__ +
-
-[[PathBiasWarnRate]] **PathBiasWarnRate** __NUM__ +
-
-[[PathBiasExtremeRate]] **PathBiasExtremeRate** __NUM__ +
-
-[[PathBiasDropGuards]] **PathBiasDropGuards** __NUM__ +
-
-[[PathBiasScaleThreshold]] **PathBiasScaleThreshold** __NUM__::
- These options override the default behavior of Tor's (**currently
- experimental**) path bias detection algorithm. To try to find broken or
- misbehaving guard nodes, Tor looks for nodes where more than a certain
- fraction of circuits through that guard fail to get built. +
- +
- The PathBiasCircThreshold option controls how many circuits we need to build
- through a guard before we make these checks. The PathBiasNoticeRate,
- PathBiasWarnRate and PathBiasExtremeRate options control what fraction of
- circuits must succeed through a guard so we won't write log messages.
- If less than PathBiasExtremeRate circuits succeed *and* PathBiasDropGuards
- is set to 1, we disable use of that guard. +
- +
- When we have seen more than PathBiasScaleThreshold
- circuits through a guard, we scale our observations by 0.5 (governed by
- the consensus) so that new observations don't get swamped by old ones. +
- +
- By default, or if a negative value is provided for one of these options,
- Tor uses reasonable defaults from the networkstatus consensus document.
- If no defaults are available there, these options default to 150, .70,
- .50, .30, 0, and 300 respectively.
-
-[[PathBiasUseThreshold]] **PathBiasUseThreshold** __NUM__ +
-
-[[PathBiasNoticeUseRate]] **PathBiasNoticeUseRate** __NUM__ +
-
-[[PathBiasExtremeUseRate]] **PathBiasExtremeUseRate** __NUM__ +
-
-[[PathBiasScaleUseThreshold]] **PathBiasScaleUseThreshold** __NUM__::
- Similar to the above options, these options override the default behavior
- of Tor's (**currently experimental**) path use bias detection algorithm. +
- +
- Where as the path bias parameters govern thresholds for successfully
- building circuits, these four path use bias parameters govern thresholds
- only for circuit usage. Circuits which receive no stream usage
- are not counted by this detection algorithm. A used circuit is considered
- successful if it is capable of carrying streams or otherwise receiving
- well-formed responses to RELAY cells. +
- +
- By default, or if a negative value is provided for one of these options,
- Tor uses reasonable defaults from the networkstatus consensus document.
- 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 directory servers or
- entry nodes over IPv6. For IPv6 only hosts, you need to also set
- **ClientUseIPv4** to 0 to disable IPv4. Note that clients configured with
- an IPv6 address in a **Bridge**, proxy, or pluggable transportline 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) (DEPRECATED: This option has had no effect for some
- time.)
-
-[[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. (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)
-
-[[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
- enough of the possible paths through the network. If this option
- is set to a fraction between 0.25 and 0.95, Tor won't build circuits
- until it has enough descriptors or microdescriptors to construct
- that fraction of possible paths. Note that setting this option too low
- can make your Tor client less anonymous, and setting it too high can
- prevent your Tor client from bootstrapping. If this option is negative,
- Tor will use a default value chosen by the directory authorities. If the
- directory authorities do not choose a value, Tor will default to 0.6.
- (Default: -1)
-
-[[ClientBootstrapConsensusAuthorityDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityDownloadInitialDelay** __N__::
- Initial delay in seconds 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: 6)
-
-[[ClientBootstrapConsensusFallbackDownloadInitialDelay]] **ClientBootstrapConsensusFallbackDownloadInitialDelay** __N__::
- Initial delay in seconds 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)
-
-[[ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay** __N__::
- Initial delay in seconds 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)
-
-[[ClientBootstrapConsensusMaxInProgressTries]] **ClientBootstrapConsensusMaxInProgressTries** __NUM__::
- 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
More information about the tor-commits
mailing list