Merge branch 'tor-github/pr/1129'

This commit is contained in:
David Goulet 2019-06-27 10:19:45 -04:00
commit c34a6b922f
2 changed files with 28 additions and 20 deletions

3
changes/ticket30955 Normal file
View File

@ -0,0 +1,3 @@
o Documentation (hard-coded directories):
- Improve the documentation for the DirAuthority and FallbackDir torrc
options. Closes ticket 30955.

View File

@ -447,13 +447,18 @@ GENERAL OPTIONS
setting for DataDirectoryGroupReadable when the CacheDirectory is the setting for DataDirectoryGroupReadable when the CacheDirectory is the
same as the DataDirectory, and 0 otherwise. (Default: auto) same as the DataDirectory, and 0 otherwise. (Default: auto)
[[FallbackDir]] **FallbackDir** __ipv4address__:__port__ orport=__port__ id=__fingerprint__ [weight=__num__] [ipv6=**[**__ipv6address__**]**:__orport__]:: [[FallbackDir]] **FallbackDir** __ipv4address__:__dirport__ orport=__orport__ id=__fingerprint__ [weight=__num__] [ipv6=**[**__ipv6address__**]**:__orport__]::
When we're unable to connect to any directory cache for directory info When tor is unable to connect to any directory cache for directory info
(usually because we don't know about any yet) we try a directory authority. (usually because it doesn't know about any yet) it tries a hard-coded
Clients also simultaneously try a FallbackDir, to avoid hangs on client directory. Relays try one directory authority at a time. Clients try
startup if a directory authority is down. Clients retry FallbackDirs more multiple directory authorities and FallbackDirs, to avoid hangs on
often than directory authorities, to reduce the load on the directory startup if a hard-coded directory is down. Clients wait for a few seconds
authorities. between each attempt, and retry FallbackDirs more often than directory
authorities, to reduce the load on the directory authorities. +
+
FallbackDirs should be stable relays with stable IP addresses, ports,
and identity keys. They must have a DirPort. +
+
By default, the directory authorities are also FallbackDirs. Specifying a By default, the directory authorities are also FallbackDirs. Specifying a
FallbackDir replaces Tor's default hard-coded FallbackDirs (if any). FallbackDir replaces Tor's default hard-coded FallbackDirs (if any).
(See the **DirAuthority** entry for an explanation of each flag.) (See the **DirAuthority** entry for an explanation of each flag.)
@ -463,30 +468,30 @@ GENERAL OPTIONS
FallbackDir line is present, it replaces the hard-coded FallbackDirs, FallbackDir line is present, it replaces the hard-coded FallbackDirs,
regardless of the value of UseDefaultFallbackDirs.) (Default: 1) regardless of the value of UseDefaultFallbackDirs.) (Default: 1)
[[DirAuthority]] **DirAuthority** [__nickname__] [**flags**] __ipv4address__:__port__ __fingerprint__:: [[DirAuthority]] **DirAuthority** [__nickname__] [**flags**] __ipv4address__:__dirport__ __fingerprint__::
Use a nonstandard authoritative directory server at the provided address Use a nonstandard authoritative directory server at the provided address
and port, with the specified key fingerprint. This option can be repeated and port, with the specified key fingerprint. This option can be repeated
many times, for multiple authoritative directory servers. Flags are many times, for multiple authoritative directory servers. Flags are
separated by spaces, and determine what kind of an authority this directory separated by spaces, and determine what kind of an authority this directory
is. By default, an authority is not authoritative for any directory style is. By default, an authority is not authoritative for any directory style
or version unless an appropriate flag is given. or version unless an appropriate flag is given. +
+
Tor will use this authority as a bridge authoritative directory if the 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 "bridge" flag is set. If a flag "orport=**orport**" is given, Tor will
given port when opening encrypted tunnels to the dirserver. If a flag use the given port when opening encrypted tunnels to the dirserver. If a
"weight=**num**" is given, then the directory server is chosen randomly flag "weight=**num**" is given, then the directory server is chosen
with probability proportional to that weight (default 1.0). If a randomly with probability proportional to that weight (default 1.0). If a
flag "v3ident=**fp**" is given, the dirserver is a v3 directory authority flag "v3ident=**fp**" is given, the dirserver is a v3 directory authority
whose v3 long-term signing key has the fingerprint **fp**. Lastly, whose v3 long-term signing key has the fingerprint **fp**. Lastly,
if an "ipv6=**[**__ipv6address__**]**:__orport__" flag is present, then if an "ipv6=**[**__ipv6address__**]**:__orport__" flag is present, then
the directory the directory authority is listening for IPv6 connections on the
authority is listening for IPv6 connections on the indicated IPv6 address indicated IPv6 address and OR Port. +
and OR Port. +
+ +
Tor will contact the authority at __ipv4address__ to Tor will contact the authority at __ipv4address__ to
download directory documents. The provided __port__ value is a dirport; download directory documents. Clients always use the ORPort. Relays
clients ignore this in favor of the specified "orport=" value. If an usually use the DirPort, but will use the ORPort in some circumstances.
IPv6 ORPort is supplied, Tor will If an IPv6 ORPort is supplied, clients will also download directory
also download directory documents at the IPv6 ORPort. + documents at the IPv6 ORPort, if they are configured to use IPv6. +
+ +
If no **DirAuthority** line is given, Tor will use the default directory If no **DirAuthority** line is given, Tor will use the default directory
authorities. NOTE: this option is intended for setting up a private Tor authorities. NOTE: this option is intended for setting up a private Tor