[tor-commits] [stem/master] Updating with latest torrc options

[atagar at torproject.org]

commit 4b49f5d1a616acfd7b1e5b9c7c82b3f8bed836d7
Author: Damian Johnson <atagar at torproject.org>
Date:   Sun Dec 20 14:03:25 2015 -0800

    Updating with latest torrc options
    
    Recent merges brought in quite a few updates. Getting back in sync.
---
 stem/cached_tor_manual.cfg |   55 +++++++++++++++++++++++++++++++++++++++-----
 stem/settings.cfg          |    7 ++++++
 test/unit/manual.py        |    8 +++----
 3 files changed, 60 insertions(+), 10 deletions(-)

diff --git a/stem/cached_tor_manual.cfg b/stem/cached_tor_manual.cfg
index aa6d7d0..9a6fed0 100644
--- a/stem/cached_tor_manual.cfg
+++ b/stem/cached_tor_manual.cfg
@@ -6,8 +6,8 @@ description
 |Basically, Tor provides a distributed network of servers or relays ("onion routers"). Users bounce their TCP streams -- web traffic, ftp, ssh, etc. -- around the network, and recipients, observers, and even the relays themselves have difficulty tracking the source of the stream.
 |
 |By default, tor will only act as a client only. To help the network by providing bandwidth as a relay, change the ORPort configuration option -- see below. Please also consult the documentation on the Tor Project's website.
-man_commit ec4ef68271ab65b4ec643088153211e861cdc7b3
-stem_commit ef9894dca36e18076815362e44ebf639f0c34fcf
+man_commit aa4be914f06baa92857de201a212b9fc9856bdb1
+stem_commit d4fac7f81c180cf8e83ea81d4f3f2e8d0d2ce491
 commandline_options -f FILE => Specify a new configuration file to contain further Tor configuration options OR pass - to make Tor read its configuration from standard input. (Default: @CONFDIR@/torrc, or $HOME/.torrc if that file is not found)
 commandline_options --ignore-missing-torrc => Specifies that Tor should treat a missing torrc file as though it were empty. Ordinarily, Tor does this for missing default torrc files, but not for those specified on the command line.
 commandline_options --list-fingerprint => Generate your keys and output your nickname and fingerprint.
@@ -851,15 +851,20 @@ config_options.DataDirectoryGroupReadable.summary Group read permissions for the
 config_options.DataDirectoryGroupReadable.description If this option is set to 0, don't allow the filesystem group to read the DataDirectory. If the option is set to 1, make the DataDirectory readable by the default GID. (Default: 0)
 config_options.FallbackDir.category General
 config_options.FallbackDir.name FallbackDir
-config_options.FallbackDir.usage address:port orport=port id=fingerprint [weight=num]
+config_options.FallbackDir.usage address:port orport=port id=fingerprint [weight=num] [ipv6=address:orport]
 config_options.FallbackDir.summary Fallback when unable to retrieve descriptor information
-config_options.FallbackDir.description 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.
+config_options.FallbackDir.description 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 directory authority. Clients also simultaneously try a FallbackDir, to avoid hangs on client startup if a directory authority is down. Clients retry FallbackDirs more often than directory authorities, to reduce the load on the directory authorities. By default, the directory authorities are also FallbackDirs. Specifying a FallbackDir replaces Tor's default hard-coded FallbackDirs (if any).
+config_options.UseDefaultFallbackDirs.category General
+config_options.UseDefaultFallbackDirs.name UseDefaultFallbackDirs
+config_options.UseDefaultFallbackDirs.usage 0|1
+config_options.UseDefaultFallbackDirs.summary Use hard-coded fallback directory authorities when needed
+config_options.UseDefaultFallbackDirs.description Use Tor's default hard-coded FallbackDirs (if any). (When a FallbackDir line is present, it replaces the hard-coded FallbackDirs, regardless of the value of UseDefaultFallbackDirs.) (Default: 1)
 config_options.DirAuthority.category General
 config_options.DirAuthority.name DirAuthority
 config_options.DirAuthority.usage [nickname] [flags] address:port fingerprint
 config_options.DirAuthority.summary Alternative directory authorities
 config_options.DirAuthority.description 
-|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 separated by spaces, and determine what kind of an authority this directory is. By default, an authority is not authoritative for any directory style or version unless an appropriate flag is given. 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. 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.
+|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 separated by spaces, and determine what kind of an authority this directory is. By default, an authority is not authoritative for any directory style or version unless an appropriate flag is given. 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. If a flag "weight=num" is given, then the directory server is chosen randomly with probability proportional to that weight (default 1.0). If a flag "v3ident=fp" is given, the dirserver is a v3 directory authority whose v3 long-term signing key has the fingerprint fp. Lastly, if an "ipv6=address:orport" flag is present, then the directory authority is listening for IPv6 connect
 ions on the indicated IPv6 address and OR Port.
 |
 |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.
 config_options.DirAuthorityFallbackRate.category General
@@ -1037,6 +1042,11 @@ config_options.User.name User
 config_options.User.usage UID
 config_options.User.summary UID for the process when started
 config_options.User.description On startup, setuid to this user and setgid to their primary group.
+config_options.KeepBindCapabilities.category General
+config_options.KeepBindCapabilities.name KeepBindCapabilities
+config_options.KeepBindCapabilities.usage 0|1|auto
+config_options.KeepBindCapabilities.summary Retain permission for binding to low valued ports
+config_options.KeepBindCapabilities.description On Linux, when we are started as root and we switch our identity using the User option, the KeepBindCapabilities option tells us whether to try to retain our ability to bind to low ports. If this value is 1, we try to keep the capability; if it is 0 we do not; and if it is auto, we keep the capability only if we are configured to listen on a low port. (Default: auto.)
 config_options.HardwareAccel.category General
 config_options.HardwareAccel.name HardwareAccel
 config_options.HardwareAccel.usage 0|1
@@ -1470,10 +1480,18 @@ config_options.TestingTorNetwork.description
 |    TestingClientDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60
 |    TestingServerConsensusDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60
 |    TestingClientConsensusDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60
+|    TestingClientBootstrapConsensusAuthorityDownloadSchedule 0, 2,
+|        4 (for 40 seconds), 8, 16, 32, 60
+|    TestingClientBootstrapConsensusFallbackDownloadSchedule 0, 1,
+|        4 (for 40 seconds), 8, 16, 32, 60
+|    TestingClientBootstrapConsensusAuthorityOnlyDownloadSchedule 0, 1,
+|        4 (for 40 seconds), 8, 16, 32, 60
 |    TestingBridgeDownloadSchedule 60, 30, 30, 60
 |    TestingClientMaxIntervalWithoutRequest 5 seconds
 |    TestingDirConnectionMaxStall 30 seconds
 |    TestingConsensusMaxDownloadTries 80
+|    TestingClientBootstrapConsensusMaxDownloadTries 80
+|    TestingClientBootstrapConsensusAuthorityOnlyMaxDownloadTries 80
 |    TestingDescriptorMaxDownloadTries 80
 |    TestingMicrodescMaxDownloadTries 80
 |    TestingCertMaxDownloadTries 80
@@ -1535,6 +1553,21 @@ config_options.TestingClientConsensusDownloadSchedule.name TestingClientConsensu
 config_options.TestingClientConsensusDownloadSchedule.usage N,N,...
 config_options.TestingClientConsensusDownloadSchedule.summary Schedule for when we should download the consensus as a client
 config_options.TestingClientConsensusDownloadSchedule.description Schedule for when clients should download consensuses. Changing this requires that TestingTorNetwork is set. (Default: 0, 0, 60, 300, 600, 1800, 3600, 3600, 3600, 10800, 21600, 43200)
+config_options.TestingClientBootstrapConsensusAuthorityDownloadSchedule.category Testing
+config_options.TestingClientBootstrapConsensusAuthorityDownloadSchedule.name TestingClientBootstrapConsensusAuthorityDownloadSchedule
+config_options.TestingClientBootstrapConsensusAuthorityDownloadSchedule.usage N,N,...
+config_options.TestingClientBootstrapConsensusAuthorityDownloadSchedule.summary Schedule when bootstrapping for when to download resources from authorities
+config_options.TestingClientBootstrapConsensusAuthorityDownloadSchedule.description Schedule for when clients should download consensuses from authorities if they are bootstrapping (that is, they don't have a usable, reasonably live consensus). Only used by clients fetching from a list of fallback directory mirrors. This schedule is advanced by (potentially concurrent) connection attempts, unlike other schedules, which are advanced by connection failures. Changing this schedule requires that TestingTorNetwork is set. (Default: 10, 11, 3600, 10800, 25200, 54000, 111600, 262800)
+config_options.TestingClientBootstrapConsensusFallbackDownloadSchedule.category Testing
+config_options.TestingClientBootstrapConsensusFallbackDownloadSchedule.name TestingClientBootstrapConsensusFallbackDownloadSchedule
+config_options.TestingClientBootstrapConsensusFallbackDownloadSchedule.usage N,N,...
+config_options.TestingClientBootstrapConsensusFallbackDownloadSchedule.summary Schedule when bootstrapping for when to download resources from fallback authorities
+config_options.TestingClientBootstrapConsensusFallbackDownloadSchedule.description Schedule for when clients should download consensuses from fallback directory mirrors if they are bootstrapping (that is, they don't have a usable, reasonably live consensus). Only used by clients fetching from a list of fallback directory mirrors. This schedule is advanced by (potentially concurrent) connection attempts, unlike other schedules, which are advanced by connection failures. Changing this schedule requires that TestingTorNetwork is set. (Default: 0, 1, 4, 11, 3600, 10800, 25200, 54000, 111600, 262800)
+config_options.TestingClientBootstrapConsensusAuthorityOnlyDownloadSchedule.category Testing
+config_options.TestingClientBootstrapConsensusAuthorityOnlyDownloadSchedule.name TestingClientBootstrapConsensusAuthorityOnlyDownloadSchedule
+config_options.TestingClientBootstrapConsensusAuthorityOnlyDownloadSchedule.usage N,N,...
+config_options.TestingClientBootstrapConsensusAuthorityOnlyDownloadSchedule.summary Schedule when bootstrapping for when to download resources from authorities when fallbacks unavailable
+config_options.TestingClientBootstrapConsensusAuthorityOnlyDownloadSchedule.description Schedule for when clients should download consensuses from authorities if they are bootstrapping (that is, they don't have a usable, reasonably live consensus). Only used by clients which don't have or won't fetch from a list of fallback directory mirrors. This schedule is advanced by (potentially concurrent) connection attempts, unlike other schedules, which are advanced by connection failures. Changing this schedule requires that TestingTorNetwork is set. (Default: 0, 3, 7, 3600, 10800, 25200, 54000, 111600, 262800)
 config_options.TestingBridgeDownloadSchedule.category Testing
 config_options.TestingBridgeDownloadSchedule.name TestingBridgeDownloadSchedule
 config_options.TestingBridgeDownloadSchedule.usage N,N,...
@@ -1554,7 +1587,17 @@ config_options.TestingConsensusMaxDownloadTries.category Testing
 config_options.TestingConsensusMaxDownloadTries.name TestingConsensusMaxDownloadTries
 config_options.TestingConsensusMaxDownloadTries.usage NUM
 config_options.TestingConsensusMaxDownloadTries.summary Retries for downloading the consensus
-config_options.TestingConsensusMaxDownloadTries.description Try this often to download a consensus before giving up. Changing this requires that TestingTorNetwork is set. (Default: 8)
+config_options.TestingConsensusMaxDownloadTries.description Try this many times to download a consensus before giving up. Changing this requires that TestingTorNetwork is set. (Default: 8)
+config_options.TestingClientBootstrapConsensusMaxDownloadTries.category Testing
+config_options.TestingClientBootstrapConsensusMaxDownloadTries.name TestingClientBootstrapConsensusMaxDownloadTries
+config_options.TestingClientBootstrapConsensusMaxDownloadTries.usage NUM
+config_options.TestingClientBootstrapConsensusMaxDownloadTries.summary Number of times to attempt downloading consensus
+config_options.TestingClientBootstrapConsensusMaxDownloadTries.description Try this many times to download a consensus while bootstrapping using fallback directory mirrors before giving up. Changing this requires that TestingTorNetwork is set. (Default: 7)
+config_options.TestingClientBootstrapConsensusMaxInProgressTries.category Testing
+config_options.TestingClientBootstrapConsensusMaxInProgressTries.name TestingClientBootstrapConsensusMaxInProgressTries
+config_options.TestingClientBootstrapConsensusMaxInProgressTries.usage NUM
+config_options.TestingClientBootstrapConsensusMaxInProgressTries.summary Number of consensus download requests to allow in-flight at once
+config_options.TestingClientBootstrapConsensusMaxInProgressTries.description Try this many simultaneous connections to download a consensus before waiting for one to complete, timeout, or error out. Changing this requires that TestingTorNetwork is set. (Default: 4)
 config_options.TestingDescriptorMaxDownloadTries.category Testing
 config_options.TestingDescriptorMaxDownloadTries.name TestingDescriptorMaxDownloadTries
 config_options.TestingDescriptorMaxDownloadTries.usage NUM
diff --git a/stem/settings.cfg b/stem/settings.cfg
index dcedc44..b590afe 100644
--- a/stem/settings.cfg
+++ b/stem/settings.cfg
@@ -74,6 +74,7 @@ manual.summary.ControlPortFileGroupReadable Group read permissions for the contr
 manual.summary.DataDirectory Location for storing runtime data (state, keys, etc)
 manual.summary.DataDirectoryGroupReadable Group read permissions for the data directory
 manual.summary.FallbackDir Fallback when unable to retrieve descriptor information
+manual.summary.UseDefaultFallbackDirs Use hard-coded fallback directory authorities when needed
 manual.summary.DirAuthority Alternative directory authorities
 manual.summary.DirAuthorityFallbackRate Rate at which to use fallback directory
 manual.summary.AlternateDirAuthority Alternative directory authorities (consensus only)
@@ -108,6 +109,7 @@ manual.summary.TruncateLogFile Overwrites log file rather than appending when re
 manual.summary.SyslogIdentityTag Tag logs appended to the syslog as being from tor
 manual.summary.SafeLogging Toggles if logs are scrubbed of sensitive information
 manual.summary.User UID for the process when started
+manual.summary.KeepBindCapabilities Retain permission for binding to low valued ports
 manual.summary.HardwareAccel Toggles if tor attempts to use hardware acceleration
 manual.summary.AccelName OpenSSL engine name for crypto acceleration
 manual.summary.AccelDir Crypto acceleration library path
@@ -328,10 +330,15 @@ manual.summary.TestingServerDownloadSchedule Schedule for when we should downloa
 manual.summary.TestingClientDownloadSchedule Schedule for when we should download resources as a client
 manual.summary.TestingServerConsensusDownloadSchedule Schedule for when we should download the consensus as a relay
 manual.summary.TestingClientConsensusDownloadSchedule Schedule for when we should download the consensus as a client
+manual.summary.TestingClientBootstrapConsensusAuthorityDownloadSchedule Schedule when bootstrapping for when to download resources from authorities
+manual.summary.TestingClientBootstrapConsensusFallbackDownloadSchedule Schedule when bootstrapping for when to download resources from fallback authorities
+manual.summary.TestingClientBootstrapConsensusAuthorityOnlyDownloadSchedule Schedule when bootstrapping for when to download resources from authorities when fallbacks unavailable
 manual.summary.TestingBridgeDownloadSchedule Schedule for when we should download bridge descriptors
 manual.summary.TestingClientMaxIntervalWithoutRequest Maximum time to wait to batch requests for missing descriptors
 manual.summary.TestingDirConnectionMaxStall Duration to let directory connections stall before timing out
 manual.summary.TestingConsensusMaxDownloadTries Retries for downloading the consensus
+manual.summary.TestingClientBootstrapConsensusMaxDownloadTries Number of times to attempt downloading consensus
+manual.summary.TestingClientBootstrapConsensusMaxInProgressTries Number of consensus download requests to allow in-flight at once
 manual.summary.TestingDescriptorMaxDownloadTries Retries for downloading server descriptors
 manual.summary.TestingMicrodescMaxDownloadTries Retries for downloading microdescriptors
 manual.summary.TestingCertMaxDownloadTries Retries for downloading authority certificates
diff --git a/test/unit/manual.py b/test/unit/manual.py
index ab8219e..90655d5 100644
--- a/test/unit/manual.py
+++ b/test/unit/manual.py
@@ -183,10 +183,10 @@ class TestManual(unittest.TestCase):
     self.assertEqual('tor - The second-generation onion router', manual.name)
     self.assertEqual('tor [OPTION value]...', manual.synopsis)
     self.assertTrue(manual.description.startswith(EXPECTED_DESCRIPTION))
-    self.assertEqual(14, len(manual.commandline_options))
-    self.assertEqual(8, len(manual.signals))
-    self.assertEqual(31, len(manual.files))
-    self.assertEqual(289, len(manual.config_options))
+    self.assertTrue(len(manual.commandline_options) > 10)
+    self.assertTrue(len(manual.signals) > 5)
+    self.assertTrue(len(manual.files) > 20)
+    self.assertTrue(len(manual.config_options) > 200)
 
   def test_download_man_page_without_arguments(self):
     try: