diff options
Diffstat (limited to 'doc/tor.1.txt')
| -rw-r--r-- | doc/tor.1.txt | 222 |
1 files changed, 184 insertions, 38 deletions
diff --git a/doc/tor.1.txt b/doc/tor.1.txt index fe78fc3b7c..b1e758f552 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -181,6 +181,11 @@ GENERAL OPTIONS using __options__ as its command-line options, and expects to receive proxied client traffic from it. +**ServerTransportListenAddr** __transport__ __IP__:__PORT__:: + When this option is set, Tor will suggest __IP__:__PORT__ as the + listening address of any pluggable transport proxy that tries to + launch __transport__. + **ConnLimit** __NUM__:: The minimum number of file descriptors that must be available to the Tor process before it will start. Tor will ask the OS for as many file @@ -287,7 +292,12 @@ GENERAL OPTIONS **DataDirectory** __DIR__:: Store working data in DIR (Default: @LOCALSTATEDIR@/lib/tor) -**DirServer** [__nickname__] [**flags**] __address__:__port__ __fingerprint__:: +**FallbackDir** __address__:__port__ orport=__port__ id=__fingerprint__ [weight=__num__]:: + When we're unable to connect to any directory cache for directory info + (usually because we don't know about any yet) we try a FallbackDir. + By default, the directory authorities are also FallbackDirs. + +**DirAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__:: Use a nonstandard authoritative directory server at the provided address and port, with the specified key fingerprint. This option can be repeated many times, for multiple authoritative directory servers. Flags are @@ -300,16 +310,24 @@ GENERAL OPTIONS flag is set, or if the "v1" flag is set and the "no-hs" flag is **not** set. Tor will use this authority as a bridge authoritative directory if the "bridge" flag is set. If a flag "orport=**port**" is given, Tor will use the - given port when opening encrypted tunnels to the dirserver. Lastly, if a + given port when opening encrypted tunnels to the dirserver. If a flag + "weight=**num**" is given, then the directory server is chosen randomly + with probability proportional to that weight (default 1.0). Lastly, if a flag "v3ident=**fp**" is given, the dirserver is a v3 directory authority whose v3 long-term signing key has the fingerprint **fp**. + + - If no **dirserver** line is given, Tor will use the default directory - servers. NOTE: this option is intended for setting up a private Tor + If no **DirAuthority** line is given, Tor will use the default directory + authorities. NOTE: this option is intended for setting up a private Tor network with its own directory authorities. If you use it, you will be distinguishable from other users, because you won't believe the same authorities they do. +**DirAuthorityFallbackRate** __NUM__:: + When configured to use both directory authorities and fallback + directories, the directory authorities also work as fallbacks. They are + chosen with their regular weights, multiplied by this number, which + should be 1.0 or less. (Default: 1.0) + **DynamicDHGroups** **0**|**1**:: If this option is set to 1, when running as a server, generate our own Diffie-Hellman group instead of using the one from Apache's mod_ssl. @@ -321,7 +339,7 @@ GENERAL OPTIONS **AlternateHSAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__ + **AlternateBridgeAuthority** [__nickname__] [**flags**] __address__:__port__ __ fingerprint__:: - These options behave as DirServer, but they replace fewer of the + These options behave as DirAuthority, but they replace fewer of the default directory authorities. Using AlternateDirAuthority replaces the default Tor directory authorities, but leaves the default hidden service authorities and bridge authorities in @@ -661,7 +679,11 @@ The following options are useful only for clients (that is, if Note also that if you are a relay, this (and the other node selection options below) only affects your own circuits that Tor builds for you. Clients can still build circuits through you to any node. Controllers - can tell Tor to build circuits through any node. + can tell Tor to build circuits through any node. + + + + Country codes are case-insensitive. The code "\{??}" refers to nodes whose + country can't be identified. No country code, including \{??}, works if + no GeoIPFile can be loaded. See also the GeoIPExcludeUnknown option below. **ExcludeExitNodes** __node__,__node__,__...__:: @@ -671,6 +693,14 @@ The following options are useful only for clients (that is, if node listed in ExcludeNodes is automatically considered to be part of this list too. See also the caveats on the "ExitNodes" option below. +**GeoIPExcludeUnknown** **0**|**1**|**auto**:: + If this option is set to 'auto', then whenever any country code is set in + ExcludeNodes or ExcludeEntryNodes, 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 ExcludeEntryNodes. This option has no effect when a GeoIP file isn't + configured or can't be found. (Default: auto) + **ExitNodes** __node__,__node__,__...__:: A list of identity fingerprints, nicknames, country codes and address patterns of nodes to use as exit node---that is, a @@ -864,7 +894,7 @@ The following options are useful only for clients (that is, if the same circuit. Currently, two addresses are "too close" if they lie in the same /16 range. (Default: 1) -**SOCKSPort** \['address':]__port__|**auto** [_isolation flags_]:: +**SOCKSPort** \['address':]__port__|**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 @@ -897,7 +927,51 @@ The following options are useful only for clients (that is, if on this port to share circuits with streams from every other port with the same session group. (By default, streams received on different SOCKSPorts, TransPorts, etc are always isolated from one - another. This option overrides that behavior.) + another. This option overrides that behavior.) + ++ + Other recognized _flags_ for a SOCKSPort are: + **NoIPv4Traffic**;; + Tell exits to not connect to IPv4 addresses in response to SOCKS + requests on this connection. + **IPv6Traffic**;; + Tell exits to allow IPv6 addresses in response to SOCKS requests on + this connection, so long as SOCKS5 is in use. (SOCKS4 can't handle + IPv6.) + **PreferIPv6**;; + Tells exits that, if a host has both an IPv4 and an IPv6 address, + we would prefer to connect to it via IPv6. (IPv4 is the default.) + ++ + NOTE: Although this option allows you to specify an IP address + other than localhost, you should do so only with extreme caution. + The SOCKS protocol is unencrypted and (as we use it) + unauthenticated, so exposing it in this way could leak your + information to anybody watching your network, and allow anybody + to use your computer as an open proxy. + **CacheIPv4DNS**;; + Tells the client to remember IPv4 DNS answers we receive from exit + nodes via this connection. (On by default.) + **CacheIPv6DNS**;; + Tells the client to remember IPv6 DNS answers we receive from exit + nodes via this connection. + **CacheDNS**;; + Tells the client to remember all DNS answers we receive from exit + nodes via this connection. + **UseIPv4Cache**;; + Tells the client to use any cached IPv4 DNS answers we have when making + requests via this connection. (NOTE: This option, along UseIPv6Cache + and UseDNSCache, can harm your anonymity, and probably + won't help performance as much as you might expect. Use with care!) + **UseIPv6Cache**;; + Tells the client to use any cached IPv6 DNS answers we have when making + requests via this connection. + **UseDNSCache**;; + Tells the client to use any cached DNS answers we have when making + requests via this connection. + **PreferIPv6Automap**;; + When serving a hostname lookup request on this port that + should get automapped (according to AutomapHostsOnResove), + if we could return either an IPv4 or an IPv6 answer, prefer + an IPv6 answer. (On by default.) **SOCKSListenAddress** __IP__[:__PORT__]:: Bind to this address to listen for connections from Socks-speaking @@ -959,10 +1033,22 @@ The following options are useful only for clients (that is, if increases the odds that an adversary who owns some servers will observe a fraction of your paths. (Default: 1) +**UseEntryGuardsAsDirectoryGuards** **0**|**1**:: + If this option is set to 1, we try to use our entry guards as directory + guards, and failing that, pick more nodes to act as our directory guards. + This helps prevent an adversary from enumerating clients. It's only + available for clients (non-relay, non-bridge) that aren't configured to + download any non-default directory material. It doesn't currently + do anything when we lack a live consensus. (Default: 1) + **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. (Default: 3) +**NumDirectoryGuards** __NUM__:: + If UseEntryGuardsAsDirectoryGuards is enabled, we try to make sure we + have at least NUM routers to use as directory guards. (Default: 3) + **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 @@ -983,16 +1069,20 @@ The following options are useful only for clients (that is, if applications to do DNS resolves themselves is usually a bad idea and can leak your location to attackers. (Default: 1) -**VirtualAddrNetwork** __Address__/__bits__:: +**VirtualAddrNetworkIPv4** __Address__/__bits__ + + +**VirtualAddrNetworkIPv6** [__Address__]/__bits__:: When Tor needs to assign a virtual (unused) address because of a MAPADDRESS command from the controller or the AutomapHostsOnResolve feature, Tor - picks an unassigned address from this range. (Default: - 127.192.0.0/10) + + picks an unassigned address from this range. (Defaults: + 127.192.0.0/10 and [FE80::]/10 respectively.) + + When providing proxy server service to a network of computers using a tool - like dns-proxy-tor, change this address to "10.192.0.0/10" or - "172.16.0.0/12". The default **VirtualAddrNetwork** address range on a - properly configured machine will route to the loopback interface. For + like dns-proxy-tor, change the IPv4 network to "10.192.0.0/10" or + "172.16.0.0/12" and change the IPv6 network to "[FC00]/7". + The default **VirtualAddrNetwork** address ranges on a + properly configured machine will route to the loopback or link-local + interface. For local use, no change to the default VirtualAddrNetwork setting is needed. **AllowNonRFC953Hostnames** **0**|**1**:: @@ -1099,12 +1189,6 @@ The following options are useful only for clients (that is, if regular router descriptors. Tor does not use this information for anything itself; to save bandwidth, leave this option turned off. (Default: 0) -**FallbackNetworkstatusFile** __FILENAME__:: - If Tor doesn't have a cached networkstatus file, it starts out using this - one instead. Even if this file is out of date, Tor can still use it to - learn about directory mirrors, so it doesn't need to put load on the - authorities. (Default: None) - **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 @@ -1146,32 +1230,69 @@ The following options are useful only for clients (that is, if "auto" (recommended) then it is on for all clients that do not set FetchUselessDescriptors. (Default: auto) +**UseNTorHandshake** **0**|**1**|**auto**:: + The "ntor" circuit-creation handshake is faster and (we think) more + secure than the original ("TAP") circuit handshake, but starting to use + it too early might make your client stand out. If this option is 0, your + Tor client won't use the ntor handshake. If it's 1, your Tor client + will use the ntor handshake to extend circuits through servers that + support it. If this option is "auto" (recommended), then your client + will use the ntor handshake once enough directory authorities recommend + it. (Default: auto) + **PathBiasCircThreshold** __NUM__ + **PathBiasNoticeRate** __NUM__ + -**PathBiasDisableRate** __NUM__ + +**PathBiasWarnRate** __NUM__ + + +**PathBiasExtremeRate** __NUM__ + -**PathBiasScaleThreshold** __NUM__ + +**PathBiasDropGuards** __NUM__ + -**PathBiasScaleFactor** __NUM__:: +**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 node fail after the first hop. The - PathBiasCircThreshold option controls how many circuits we need to build - through a guard before we make these checks. The PathBiasNoticeRate and - PathBiasDisableRate options control what fraction of circuits must - succeed through a guard so we won't warn about it or disable it, - respectively. When we have seen more than PathBiasScaleThreshold - circuits through a guard, we divide our observations by - PathBiasScaleFactor, so that new observations don't get swamped by old - ones. + + 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 20, .70, - 0.0, 200, and 4 respectively. + If no defaults are available there, these options default to 150, .70, + .50, .30, 0, and 300 respectively. + +**PathBiasUseThreshold** __NUM__ + + +**PathBiasNoticeUseRate** __NUM__ + + +**PathBiasExtremeUseRate** __NUM__ + + +**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. **ClientUseIPv6** **0**|**1**:: If this option is set to 1, Tor might connect to entry nodes over @@ -1185,6 +1306,18 @@ The following options are useful only for clients (that is, if things may influence the choice. This option breaks a tie to the favor of IPv6. (Default: 0) +**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. (Default: -1.) + SERVER OPTIONS -------------- @@ -1275,9 +1408,13 @@ is non-zero): at the beginning of your exit policy. See above entry on ExitPolicy. (Default: 1) -**MaxOnionsPending** __NUM__:: - If you have more than this number of onionskins queued for decrypt, reject - new ones. (Default: 100) +**IPv6Exit** **0**|**1**:: + If set, and we are an exit node, allow clients to use us for IPv6 + traffic. (Default: 0) + +**MaxOnionQueueDelay** __NUM__ [**msec**|**second**]:: + If we have more onionskins queued for processing than we can process in + this amount of time, reject new ones. (Default: 1750 msec) **MyFamily** __node__,__node__,__...__:: Declare that this Tor server is controlled or administered by a group or @@ -1458,7 +1595,16 @@ is non-zero): does on behalf of clients. (Default: 1) **GeoIPFile** __filename__:: - A filename containing GeoIP data, for use with BridgeRecordUsageByCountry. + A filename containing IPv4 GeoIP data, for use with by-country statistics. + +**GeoIPv6File** __filename__:: + A filename containing IPv6 GeoIP data, for use with by-country statistics. + +**TLSECGroup** **P224**|**P256**:: + What EC group should we try to use for incoming TLS connections? + P224 is faster, but makes us stand out more. Has no effect if + we're a client, or if our OpenSSL version lacks support for ECDHE. + (Default: P224 for public servers; P256 for bridges.) **CellStatistics** **0**|**1**:: When this option is enabled, Tor writes statistics on the mean time that |