Merge remote-tracking branch 'tor-github/pr/1728/head' into maint-0.4.3

1 files changed, 319 insertions, 307 deletions

diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index a9b9852b7d..db4dd2755a 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -794,6 +794,11 @@ forward slash (/) in the configuration file and on the command line.
     fetches by the relay (from authority or other relays), because that is considered
     "client" activity.  (Default: 0)
 
+[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
+    Tells an authority, or other node tracking node reliability and history,
+    that fine-grained information about nodes can be discarded when it hasn't
+    changed for a given amount of time.  (Default: 24 hours)
+
 [[RunAsDaemon]] **RunAsDaemon** **0**|**1**::
     If 1, Tor forks and daemonizes to the background. This option has no effect
     on Windows; instead you should use the --service command-line option.
@@ -2060,9 +2065,58 @@ different from other Tor clients:
 
 == SERVER OPTIONS
 
+// These options are in alphabetical order, with exceptions as noted.
+// Please keep them that way!
+
 The following options are useful only for servers (that is, if ORPort
 is non-zero):
 
+[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**::
+    Limits the max number of bytes sent and received within a set time period
+    using a given calculation rule (see: AccountingStart, AccountingRule).
+    Useful if you need to stay under a specific bandwidth. By default, the
+    number used for calculation is the max of either the bytes sent or
+    received. For example, with AccountingMax set to 1 TByte, a server
+    could send 900 GBytes and receive 800 GBytes and continue running.
+    It will only hibernate once one of the two reaches 1 TByte. This can
+    be changed to use the sum of the both bytes received and sent by setting
+    the AccountingRule option to "sum" (total bandwidth in/out). When the
+    number of bytes remaining gets low, Tor will stop accepting new connections
+    and circuits. When the number of bytes is exhausted, Tor will hibernate
+    until some time in the next accounting period. To prevent all servers
+    from waking at the same time, Tor will also wait until a random point
+    in each period before waking up. If you have bandwidth cost issues,
+    enabling hibernation is preferable to setting a low bandwidth, since
+    it provides users with a collection of fast servers that are up some
+    of the time, which is more useful than a set of slow servers that are
+    always "available". +
+     +
+    Note that (as also described in the Bandwidth section) Tor uses
+    powers of two, not powers of ten: 1 GByte is 1024*1024*1024, not
+    one billion. Be careful: some internet service providers might count
+    GBytes differently.
+
+[[AccountingRule]] **AccountingRule** **sum**|**max**|**in**|**out**::
+    How we determine when our AccountingMax has been reached (when we
+    should hibernate) during a time interval. Set to "max" to calculate
+    using the higher of either the sent or received bytes (this is the
+    default functionality). Set to "sum" to calculate using the sent
+    plus received bytes. Set to "in" to calculate using only the
+    received bytes. Set to "out" to calculate using only the sent bytes.
+    (Default: max)
+
+[[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__::
+    Specify how long accounting periods last. If **month** is given,
+    each accounting period runs from the time __HH:MM__ on the __dayth__ day of one
+    month to the same day and time of the next. The relay will go at full speed,
+    use all the quota you specify, then hibernate for the rest of the period. (The
+    day must be between 1 and 28.) If **week** is given, each accounting period
+    runs from the time __HH:MM__ of the __dayth__ day of one week to the same day
+    and time of the next week, with Monday as day 1 and Sunday as day 7. If **day**
+    is given, each accounting period runs from the time __HH:MM__ each day to the
+    same time on the next day. All times are local, and given in 24-hour time.
+    (Default: "month 1 0:00")
+
 [[Address]] **Address** __address__::
     The IPv4 address of this server, or a fully qualified domain name of
     this server that resolves to an IPv4 address.  You can leave this
@@ -2088,6 +2142,15 @@ is non-zero):
     Note: make sure that no MyFamily lines are present in your torrc when
     relay is configured in bridge mode.
 
+//Out of order because it logically belongs after BridgeRelay.
+[[BridgeRecordUsageByCountry]] **BridgeRecordUsageByCountry** **0**|**1**::
+    When this option is enabled and BridgeRelay is also enabled, and we have
+    GeoIP data, Tor keeps a per-country count of how many client
+    addresses have contacted it so that it can help the bridge authority guess
+    which countries have blocked access to it. If ExtraInfoStatistics is
+    enabled, it will be published as part of extra-info document. (Default: 1)
+
+//Out of order because it logically belongs after BridgeRelay.
 [[BridgeDistribution]] **BridgeDistribution** __string__::
     If set along with BridgeRelay, Tor will include a new line in its
     bridge descriptor which indicates to the BridgeDB service how it
@@ -2108,21 +2171,11 @@ is non-zero):
     relay or bridge.  (Really, everybody running a relay or bridge should set
     it.)
 
-
-[[ExitRelay]] **ExitRelay** **0**|**1**|**auto**::
-    Tells Tor whether to run as an exit relay.  If Tor is running as a
-    non-bridge server, and ExitRelay is set to 1, then Tor allows traffic to
-    exit according to the ExitPolicy option, the ReducedExitPolicy option,
-    or the default ExitPolicy (if no other exit policy option is specified). +
-     +
-    If ExitRelay is set to 0, no traffic is allowed to exit, and the
-    ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored. +
-     +
-    If ExitRelay is set to "auto", then Tor checks the ExitPolicy,
-    ReducedExitPolicy, and IPv6Exit options. If at least one of these options
-    is set, Tor behaves as if ExitRelay were set to 1. If none of these exit
-    policy options are set, Tor behaves as if ExitRelay were set to 0.
-    (Default: auto)
+[[DisableOOSCheck]] **DisableOOSCheck** **0**|**1**::
+    This option disables the code that closes connections when Tor notices
+    that it is running low on sockets. Right now, it is on by default,
+    since the existing out-of-sockets mechanism tends to kill OR connections
+    more than it should. (Default: 1)
 
 [[ExitPolicy]] **ExitPolicy** __policy__,__policy__,__...__::
     Set an exit policy for this server. Each policy is of the form
@@ -2205,12 +2258,6 @@ is non-zero):
     Since the default exit policy uses accept/reject *, it applies to both
     IPv4 and IPv6 addresses.
 
-[[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**::
-    Reject all private (local) networks, along with the relay's advertised
-    public IPv4 and IPv6 addresses, at the beginning of your exit policy.
-    See above entry on ExitPolicy.
-    (Default: 1)
-
 [[ExitPolicyRejectLocalInterfaces]] **ExitPolicyRejectLocalInterfaces** **0**|**1**::
     Reject all IPv4 and IPv6 addresses that the relay knows about, at the
     beginning of your exit policy. This includes any OutboundBindAddress, the
@@ -2223,104 +2270,81 @@ is non-zero):
     to disclose.
     (Default: 0)
 
-[[ReducedExitPolicy]] **ReducedExitPolicy** **0**|**1**::
-    If set, use a reduced exit policy rather than the default one. +
+[[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**::
+    Reject all private (local) networks, along with the relay's advertised
+    public IPv4 and IPv6 addresses, at the beginning of your exit policy.
+    See above entry on ExitPolicy.
+    (Default: 1)
+
+[[ExitRelay]] **ExitRelay** **0**|**1**|**auto**::
+    Tells Tor whether to run as an exit relay.  If Tor is running as a
+    non-bridge server, and ExitRelay is set to 1, then Tor allows traffic to
+    exit according to the ExitPolicy option, the ReducedExitPolicy option,
+    or the default ExitPolicy (if no other exit policy option is specified). +
      +
-    The reduced exit policy is an alternative to the default exit policy. It
-    allows as many Internet services as possible while still blocking the
-    majority of TCP ports. Currently, the policy allows approximately 65 ports.
-    This reduces the odds that your node will be used for peer-to-peer
-    applications. +
+    If ExitRelay is set to 0, no traffic is allowed to exit, and the
+    ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored. +
      +
-    The reduced exit policy is:
-
-        accept *:20-21
-        accept *:22
-        accept *:23
-        accept *:43
-        accept *:53
-        accept *:79
-        accept *:80-81
-        accept *:88
-        accept *:110
-        accept *:143
-        accept *:194
-        accept *:220
-        accept *:389
-        accept *:443
-        accept *:464
-        accept *:465
-        accept *:531
-        accept *:543-544
-        accept *:554
-        accept *:563
-        accept *:587
-        accept *:636
-        accept *:706
-        accept *:749
-        accept *:873
-        accept *:902-904
-        accept *:981
-        accept *:989-990
-        accept *:991
-        accept *:992
-        accept *:993
-        accept *:994
-        accept *:995
-        accept *:1194
-        accept *:1220
-        accept *:1293
-        accept *:1500
-        accept *:1533
-        accept *:1677
-        accept *:1723
-        accept *:1755
-        accept *:1863
-        accept *:2082
-        accept *:2083
-        accept *:2086-2087
-        accept *:2095-2096
-        accept *:2102-2104
-        accept *:3128
-        accept *:3389
-        accept *:3690
-        accept *:4321
-        accept *:4643
-        accept *:5050
-        accept *:5190
-        accept *:5222-5223
-        accept *:5228
-        accept *:5900
-        accept *:6660-6669
-        accept *:6679
-        accept *:6697
-        accept *:8000
-        accept *:8008
-        accept *:8074
-        accept *:8080
-        accept *:8082
-        accept *:8087-8088
-        accept *:8232-8233
-        accept *:8332-8333
-        accept *:8443
-        accept *:8888
-        accept *:9418
-        accept *:9999
-        accept *:10000
-        accept *:11371
-        accept *:19294
-        accept *:19638
-        accept *:50002
-        accept *:64738
-        reject *:*
+    If ExitRelay is set to "auto", then Tor checks the ExitPolicy,
+    ReducedExitPolicy, and IPv6Exit options. If at least one of these options
+    is set, Tor behaves as if ExitRelay were set to 1. If none of these exit
+    policy options are set, Tor behaves as if ExitRelay were set to 0.
+    (Default: auto)
 
+[[ExtendAllowPrivateAddresses]] **ExtendAllowPrivateAddresses** **0**|**1**::
+    When this option is enabled, Tor will connect to relays on localhost,
+    RFC1918 addresses, and so on. In particular, Tor will make direct OR
+    connections, and Tor routers allow EXTEND requests, to these private
+    addresses. (Tor will always allow connections to bridges, proxies, and
+    pluggable transports configured on private addresses.) Enabling this
+    option can create security issues; you should probably leave it off.
     (Default: 0)
 
+[[GeoIPFile]] **GeoIPFile** __filename__::
+    A filename containing IPv4 GeoIP data, for use with by-country statistics.
+
+[[GeoIPv6File]] **GeoIPv6File** __filename__::
+    A filename containing IPv6 GeoIP data, for use with by-country statistics.
+
+[[HeartbeatPeriod]] **HeartbeatPeriod**  __N__ **minutes**|**hours**|**days**|**weeks**::
+    Log a heartbeat message every **HeartbeatPeriod** seconds. This is
+    a log level __notice__ message, designed to let you know your Tor
+    server is still alive and doing useful things. Settings this
+    to 0 will disable the heartbeat. Otherwise, it must be at least 30
+    minutes. (Default: 6 hours)
+
 [[IPv6Exit]] **IPv6Exit** **0**|**1**::
     If set, and we are an exit node, allow clients to use us for IPv6 traffic.
     When this option is set and ExitRelay is auto, we act as if ExitRelay
     is 1. (Default: 0)
 
+[[KeyDirectory]] **KeyDirectory** __DIR__::
+    Store secret keys in DIR. Can not be changed while tor is
+    running.
+    (Default: the "keys" subdirectory of DataDirectory.)
+
+[[KeyDirectoryGroupReadable]] **KeyDirectoryGroupReadable** **0**|**1**|**auto**::
+    If this option is set to 0, don't allow the filesystem group to read the
+    KeyDirectory. If the option is set to 1, make the KeyDirectory readable
+    by the default GID. If the option is "auto", then we use the
+    setting for DataDirectoryGroupReadable when the KeyDirectory is the
+    same as the DataDirectory, and 0 otherwise. (Default: auto)
+
+[[MainloopStats]] **MainloopStats** **0**|**1**::
+    Log main loop statistics every **HeartbeatPeriod** seconds. This is a log
+    level __notice__ message designed to help developers instrumenting Tor's
+    main event loop. (Default: 0)
+
+[[MaxMemInQueues]] **MaxMemInQueues**  __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**::
+    This option configures a threshold above which Tor will assume that it
+    needs to stop queueing or buffering data because it's about to run out of
+    memory.  If it hits this threshold, it will begin killing circuits until
+    it has recovered at least 10% of this memory.  Do not set this option too
+    low, or your relay may be unreliable under load.  This option only
+    affects some queues, so the actual process size will be larger than
+    this.  If this option is set to 0, Tor will try to pick a reasonable
+    default based on your system's physical memory.  (Default: 0)
+
 [[MaxOnionQueueDelay]] **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)
@@ -2358,6 +2382,12 @@ is non-zero):
     parallelizable operations.  If this is set to 0, Tor will try to detect
     how many CPUs you have, defaulting to 1 if it can't tell.  (Default: 0)
 
+[[OfflineMasterKey]] **OfflineMasterKey** **0**|**1**::
+    If non-zero, the Tor relay will never generate or load its master secret
+    key.  Instead, you'll have to use "tor --keygen" to manage the permanent
+    ed25519 master identity key, as well as the corresponding temporary
+    signing keys and certificates. (Default: 0)
+
 [[ORPort]] **ORPort** ['address'**:**]{empty}__PORT__|**auto** [_flags_]::
     Advertise this port to listen for connections from Tor clients and
     servers.  This option is required to be a Tor server.
@@ -2402,74 +2432,98 @@ is non-zero):
     "publish as if you're a relay", and "bridge", meaning "publish as
     if you're a bridge".
 
-[[ShutdownWaitLength]] **ShutdownWaitLength** __NUM__::
-    When we get a SIGINT and we're a server, we begin shutting down:
-    we close listeners and start refusing new circuits. After **NUM**
-    seconds, we exit. If we get a second SIGINT, we exit immediately.
-    (Default: 30 seconds)
-
-[[SSLKeyLifetime]] **SSLKeyLifetime** __N__ **minutes**|**hours**|**days**|**weeks**::
-    When creating a link certificate for our outermost SSL handshake,
-    set its lifetime to this amount of time. If set to 0, Tor will choose
-    some reasonable random defaults. (Default: 0)
-
-[[HeartbeatPeriod]] **HeartbeatPeriod**  __N__ **minutes**|**hours**|**days**|**weeks**::
-    Log a heartbeat message every **HeartbeatPeriod** seconds. This is
-    a log level __notice__ message, designed to let you know your Tor
-    server is still alive and doing useful things. Settings this
-    to 0 will disable the heartbeat. Otherwise, it must be at least 30
-    minutes. (Default: 6 hours)
-
-[[MainloopStats]] **MainloopStats** **0**|**1**::
-    Log main loop statistics every **HeartbeatPeriod** seconds. This is a log
-    level __notice__ message designed to help developers instrumenting Tor's
-    main event loop. (Default: 0)
-
-[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**::
-    Limits the max number of bytes sent and received within a set time period
-    using a given calculation rule (see: AccountingStart, AccountingRule).
-    Useful if you need to stay under a specific bandwidth. By default, the
-    number used for calculation is the max of either the bytes sent or
-    received. For example, with AccountingMax set to 1 TByte, a server
-    could send 900 GBytes and receive 800 GBytes and continue running.
-    It will only hibernate once one of the two reaches 1 TByte. This can
-    be changed to use the sum of the both bytes received and sent by setting
-    the AccountingRule option to "sum" (total bandwidth in/out). When the
-    number of bytes remaining gets low, Tor will stop accepting new connections
-    and circuits. When the number of bytes is exhausted, Tor will hibernate
-    until some time in the next accounting period. To prevent all servers
-    from waking at the same time, Tor will also wait until a random point
-    in each period before waking up. If you have bandwidth cost issues,
-    enabling hibernation is preferable to setting a low bandwidth, since
-    it provides users with a collection of fast servers that are up some
-    of the time, which is more useful than a set of slow servers that are
-    always "available". +
+[[ReducedExitPolicy]] **ReducedExitPolicy** **0**|**1**::
+    If set, use a reduced exit policy rather than the default one. +
      +
-    Note that (as also described in the Bandwidth section) Tor uses
-    powers of two, not powers of ten: 1 GByte is 1024*1024*1024, not
-    one billion. Be careful: some internet service providers might count
-    GBytes differently.
+    The reduced exit policy is an alternative to the default exit policy. It
+    allows as many Internet services as possible while still blocking the
+    majority of TCP ports. Currently, the policy allows approximately 65 ports.
+    This reduces the odds that your node will be used for peer-to-peer
+    applications. +
+     +
+    The reduced exit policy is:
 
-[[AccountingRule]] **AccountingRule** **sum**|**max**|**in**|**out**::
-    How we determine when our AccountingMax has been reached (when we
-    should hibernate) during a time interval. Set to "max" to calculate
-    using the higher of either the sent or received bytes (this is the
-    default functionality). Set to "sum" to calculate using the sent
-    plus received bytes. Set to "in" to calculate using only the
-    received bytes. Set to "out" to calculate using only the sent bytes.
-    (Default: max)
+        accept *:20-21
+        accept *:22
+        accept *:23
+        accept *:43
+        accept *:53
+        accept *:79
+        accept *:80-81
+        accept *:88
+        accept *:110
+        accept *:143
+        accept *:194
+        accept *:220
+        accept *:389
+        accept *:443
+        accept *:464
+        accept *:465
+        accept *:531
+        accept *:543-544
+        accept *:554
+        accept *:563
+        accept *:587
+        accept *:636
+        accept *:706
+        accept *:749
+        accept *:873
+        accept *:902-904
+        accept *:981
+        accept *:989-990
+        accept *:991
+        accept *:992
+        accept *:993
+        accept *:994
+        accept *:995
+        accept *:1194
+        accept *:1220
+        accept *:1293
+        accept *:1500
+        accept *:1533
+        accept *:1677
+        accept *:1723
+        accept *:1755
+        accept *:1863
+        accept *:2082
+        accept *:2083
+        accept *:2086-2087
+        accept *:2095-2096
+        accept *:2102-2104
+        accept *:3128
+        accept *:3389
+        accept *:3690
+        accept *:4321
+        accept *:4643
+        accept *:5050
+        accept *:5190
+        accept *:5222-5223
+        accept *:5228
+        accept *:5900
+        accept *:6660-6669
+        accept *:6679
+        accept *:6697
+        accept *:8000
+        accept *:8008
+        accept *:8074
+        accept *:8080
+        accept *:8082
+        accept *:8087-8088
+        accept *:8232-8233
+        accept *:8332-8333
+        accept *:8443
+        accept *:8888
+        accept *:9418
+        accept *:9999
+        accept *:10000
+        accept *:11371
+        accept *:19294
+        accept *:19638
+        accept *:50002
+        accept *:64738
+        reject *:*
 
-[[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__::
-    Specify how long accounting periods last. If **month** is given,
-    each accounting period runs from the time __HH:MM__ on the __dayth__ day of one
-    month to the same day and time of the next. The relay will go at full speed,
-    use all the quota you specify, then hibernate for the rest of the period. (The
-    day must be between 1 and 28.) If **week** is given, each accounting period
-    runs from the time __HH:MM__ of the __dayth__ day of one week to the same day
-    and time of the next week, with Monday as day 1 and Sunday as day 7. If **day**
-    is given, each accounting period runs from the time __HH:MM__ each day to the
-    same time on the next day. All times are local, and given in 24-hour time.
-    (Default: "month 1 0:00")
+    (Default: 0)
 
 [[RefuseUnknownExits]] **RefuseUnknownExits** **0**|**1**|**auto**::
     Prevent nodes that don't appear in the consensus from exiting using this
@@ -2478,6 +2532,34 @@ is non-zero):
     whatever the authorities suggest in the consensus (and block if the consensus
     is quiet on the issue). (Default: auto)
 
+[[ServerDNSAllowBrokenConfig]] **ServerDNSAllowBrokenConfig** **0**|**1**::
+    If this option is false, Tor exits immediately if there are problems
+    parsing the system DNS configuration or connecting to nameservers.
+    Otherwise, Tor continues to periodically retry the system nameservers until
+    it eventually succeeds. (Default: 1)
+
+[[ServerDNSAllowNonRFC953Hostnames]] **ServerDNSAllowNonRFC953Hostnames** **0**|**1**::
+    When this option is disabled, Tor does not try to resolve 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. This option only affects name lookups that your server does
+    on behalf of clients. (Default: 0)
+
+[[ServerDNSDetectHijacking]] **ServerDNSDetectHijacking** **0**|**1**::
+    When this option is set to 1, we will test periodically to determine
+    whether our local nameservers have been configured to hijack failing DNS
+    requests (usually to an advertising site). If they are, we will attempt to
+    correct this. This option only affects name lookups that your server does
+    on behalf of clients. (Default: 1)
+
+[[ServerDNSRandomizeCase]] **ServerDNSRandomizeCase** **0**|**1**::
+    When this option is set, Tor sets the case of each character randomly in
+    outgoing DNS requests, and makes sure that the case matches in DNS replies.
+    This so-called "0x20 hack" helps resist some types of DNS poisoning attack.
+    For more information, see "Increased DNS Forgery Resistance through
+    0x20-Bit Encoding". This option only affects name lookups that your server
+    does on behalf of clients. (Default: 1)
+
 [[ServerDNSResolvConfFile]] **ServerDNSResolvConfFile** __filename__::
     Overrides the default DNS configuration with the configuration in
     __filename__. The file format is the same as the standard Unix
@@ -2486,12 +2568,6 @@ is non-zero):
     (Defaults to use the system DNS configuration or a localhost DNS service
     in case no nameservers are found in a given configuration.)
 
-[[ServerDNSAllowBrokenConfig]] **ServerDNSAllowBrokenConfig** **0**|**1**::
-    If this option is false, Tor exits immediately if there are problems
-    parsing the system DNS configuration or connecting to nameservers.
-    Otherwise, Tor continues to periodically retry the system nameservers until
-    it eventually succeeds. (Default: 1)
-
 [[ServerDNSSearchDomains]] **ServerDNSSearchDomains** **0**|**1**::
     If set to 1, then we will search for addresses in the local search domain.
     For example, if this system is configured to believe it is in
@@ -2499,13 +2575,6 @@ is non-zero):
     connected to "www.example.com". This option only affects name lookups that
     your server does on behalf of clients. (Default: 0)
 
-[[ServerDNSDetectHijacking]] **ServerDNSDetectHijacking** **0**|**1**::
-    When this option is set to 1, we will test periodically to determine
-    whether our local nameservers have been configured to hijack failing DNS
-    requests (usually to an advertising site). If they are, we will attempt to
-    correct this. This option only affects name lookups that your server does
-    on behalf of clients. (Default: 1)
-
 [[ServerDNSTestAddresses]] **ServerDNSTestAddresses** __hostname__,__hostname__,__...__::
     When we're detecting DNS hijacking, make sure that these __valid__ addresses
     aren't getting redirected. If they are, then our DNS is completely useless,
@@ -2513,33 +2582,32 @@ is non-zero):
     name lookups that your server does on behalf of clients. (Default:
     "www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org")
 
-[[ServerDNSAllowNonRFC953Hostnames]] **ServerDNSAllowNonRFC953Hostnames** **0**|**1**::
-    When this option is disabled, Tor does not try to resolve 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. This option only affects name lookups that your server does
-    on behalf of clients. (Default: 0)
+[[ShutdownWaitLength]] **ShutdownWaitLength** __NUM__::
+    When we get a SIGINT and we're a server, we begin shutting down:
+    we close listeners and start refusing new circuits. After **NUM**
+    seconds, we exit. If we get a second SIGINT, we exit immediately.
+    (Default: 30 seconds)
 
-[[BridgeRecordUsageByCountry]] **BridgeRecordUsageByCountry** **0**|**1**::
-    When this option is enabled and BridgeRelay is also enabled, and we have
-    GeoIP data, Tor keeps a per-country count of how many client
-    addresses have contacted it so that it can help the bridge authority guess
-    which countries have blocked access to it. If ExtraInfoStatistics is
-    enabled, it will be published as part of extra-info document. (Default: 1)
+[[SigningKeyLifetime]] **SigningKeyLifetime** __N__ **days**|**weeks**|**months**::
+    For how long should each Ed25519 signing key be valid?  Tor uses a
+    permanent master identity key that can be kept offline, and periodically
+    generates new "signing" keys that it uses online.  This option
+    configures their lifetime.
+    (Default: 30 days)
 
-[[ServerDNSRandomizeCase]] **ServerDNSRandomizeCase** **0**|**1**::
-    When this option is set, Tor sets the case of each character randomly in
-    outgoing DNS requests, and makes sure that the case matches in DNS replies.
-    This so-called "0x20 hack" helps resist some types of DNS poisoning attack.
-    For more information, see "Increased DNS Forgery Resistance through
-    0x20-Bit Encoding". This option only affects name lookups that your server
-    does on behalf of clients. (Default: 1)
+[[SSLKeyLifetime]] **SSLKeyLifetime** __N__ **minutes**|**hours**|**days**|**weeks**::
+    When creating a link certificate for our outermost SSL handshake,
+    set its lifetime to this amount of time. If set to 0, Tor will choose
+    some reasonable random defaults. (Default: 0)
 
-[[GeoIPFile]] **GeoIPFile** __filename__::
-    A filename containing IPv4 GeoIP data, for use with by-country statistics.
+== STATISTICS OPTIONS
 
-[[GeoIPv6File]] **GeoIPv6File** __filename__::
-    A filename containing IPv6 GeoIP data, for use with by-country statistics.
+// These options are in alphabetical order, with exceptions as noted.
+// Please keep them that way!
+
+Relays publish most statistics in a document called the
+extra-info document. The following options affect the different
+types of statistics that Tor relays collect and publish:
 
 [[CellStatistics]] **CellStatistics** **0**|**1**::
     Relays only.
@@ -2551,14 +2619,14 @@ is non-zero):
     If ExtraInfoStatistics is enabled, it will published as part of
     extra-info document. (Default: 0)
 
-[[PaddingStatistics]] **PaddingStatistics** **0**|**1**::
-    Relays and bridges only.
-    When this option is enabled, Tor collects statistics for padding cells
-    sent and received by this relay, in addition to total cell counts.
-    These statistics are rounded, and omitted if traffic is low. This
-    information is important for load balancing decisions related to padding.
-    If ExtraInfoStatistics is enabled, it will be published
-    as a part of extra-info document. (Default: 1)
+[[ConnDirectionStatistics]] **ConnDirectionStatistics** **0**|**1**::
+    Relays only.
+    When this option is enabled, Tor writes statistics on the amounts of
+    traffic it passes between itself and other relays to disk every 24
+    hours. Enables relay operators to monitor how much their relay is
+    being used as middle node in the circuit. If ExtraInfoStatistics is
+    enabled, it will be published as part of extra-info document.
+    (Default: 0)
 
 [[DirReqStatistics]] **DirReqStatistics** **0**|**1**::
     Relays and bridges only.
@@ -2587,23 +2655,6 @@ is non-zero):
     is enabled, it will be published as part of extra-info document.
     (Default: 0)
 
-[[ConnDirectionStatistics]] **ConnDirectionStatistics** **0**|**1**::
-    Relays only.
-    When this option is enabled, Tor writes statistics on the amounts of
-    traffic it passes between itself and other relays to disk every 24
-    hours. Enables relay operators to monitor how much their relay is
-    being used as middle node in the circuit. If ExtraInfoStatistics is
-    enabled, it will be published as part of extra-info document.
-    (Default: 0)
-
-[[HiddenServiceStatistics]] **HiddenServiceStatistics** **0**|**1**::
-    Relays only.
-    When this option is enabled, a Tor relay writes obfuscated
-    statistics on its role as hidden-service directory, introduction
-    point, or rendezvous point to disk every 24 hours. If
-    ExtraInfoStatistics is also enabled, these statistics are further
-    published to the directory authorities. (Default: 1)
-
 [[ExtraInfoStatistics]] **ExtraInfoStatistics** **0**|**1**::
     When this option is enabled, Tor includes previously gathered statistics in
     its extra-info documents that it uploads to the directory authorities.
@@ -2613,61 +2664,22 @@ is non-zero):
     because they are required by BridgeDB.
     (Default: 1)
 
-[[ExtendAllowPrivateAddresses]] **ExtendAllowPrivateAddresses** **0**|**1**::
-    When this option is enabled, Tor will connect to relays on localhost,
-    RFC1918 addresses, and so on. In particular, Tor will make direct OR
-    connections, and Tor routers allow EXTEND requests, to these private
-    addresses. (Tor will always allow connections to bridges, proxies, and
-    pluggable transports configured on private addresses.) Enabling this
-    option can create security issues; you should probably leave it off.
-    (Default: 0)
-
-[[MaxMemInQueues]] **MaxMemInQueues**  __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**::
-    This option configures a threshold above which Tor will assume that it
-    needs to stop queueing or buffering data because it's about to run out of
-    memory.  If it hits this threshold, it will begin killing circuits until
-    it has recovered at least 10% of this memory.  Do not set this option too
-    low, or your relay may be unreliable under load.  This option only
-    affects some queues, so the actual process size will be larger than
-    this.  If this option is set to 0, Tor will try to pick a reasonable
-    default based on your system's physical memory.  (Default: 0)
-
-[[DisableOOSCheck]] **DisableOOSCheck** **0**|**1**::
-    This option disables the code that closes connections when Tor notices
-    that it is running low on sockets. Right now, it is on by default,
-    since the existing out-of-sockets mechanism tends to kill OR connections
-    more than it should. (Default: 1)
-
-[[SigningKeyLifetime]] **SigningKeyLifetime** __N__ **days**|**weeks**|**months**::
-    For how long should each Ed25519 signing key be valid?  Tor uses a
-    permanent master identity key that can be kept offline, and periodically
-    generates new "signing" keys that it uses online.  This option
-    configures their lifetime.
-    (Default: 30 days)
-
-[[OfflineMasterKey]] **OfflineMasterKey** **0**|**1**::
-    If non-zero, the Tor relay will never generate or load its master secret
-    key.  Instead, you'll have to use "tor --keygen" to manage the permanent
-    ed25519 master identity key, as well as the corresponding temporary
-    signing keys and certificates. (Default: 0)
-
-[[KeyDirectory]] **KeyDirectory** __DIR__::
-    Store secret keys in DIR. Can not be changed while tor is
-    running.
-    (Default: the "keys" subdirectory of DataDirectory.)
-
-[[KeyDirectoryGroupReadable]] **KeyDirectoryGroupReadable** **0**|**1**|**auto**::
-    If this option is set to 0, don't allow the filesystem group to read the
-    KeyDirectory. If the option is set to 1, make the KeyDirectory readable
-    by the default GID. If the option is "auto", then we use the
-    setting for DataDirectoryGroupReadable when the KeyDirectory is the
-    same as the DataDirectory, and 0 otherwise. (Default: auto)
-
-[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
-    Tells an authority, or other node tracking node reliability and history,
-    that fine-grained information about nodes can be discarded when it hasn't
-    changed for a given amount of time.  (Default: 24 hours)
+[[HiddenServiceStatistics]] **HiddenServiceStatistics** **0**|**1**::
+    Relays only.
+    When this option is enabled, a Tor relay writes obfuscated
+    statistics on its role as hidden-service directory, introduction
+    point, or rendezvous point to disk every 24 hours. If
+    ExtraInfoStatistics is also enabled, these statistics are further
+    published to the directory authorities. (Default: 1)
 
+[[PaddingStatistics]] **PaddingStatistics** **0**|**1**::
+    Relays and bridges only.
+    When this option is enabled, Tor collects statistics for padding cells
+    sent and received by this relay, in addition to total cell counts.
+    These statistics are rounded, and omitted if traffic is low. This
+    information is important for load balancing decisions related to padding.
+    If ExtraInfoStatistics is enabled, it will be published
+    as a part of extra-info document. (Default: 1)
 
 == DIRECTORY SERVER OPTIONS
 
@@ -2675,11 +2687,19 @@ The following options are useful only for directory servers. (Relays with
 enough bandwidth automatically become directory servers; see DirCache for
 details.)
 
-[[DirPortFrontPage]] **DirPortFrontPage** __FILENAME__::
-    When this option is set, it takes an HTML file and publishes it as "/" on
-    the DirPort. Now relay operators can provide a disclaimer without needing
-    to set up a separate webserver. There's a sample disclaimer in
-    contrib/operator-tools/tor-exit-notice.html.
+[[DirCache]] **DirCache** **0**|**1**::
+    When this option is set, Tor caches all current directory documents except
+    extra info documents, and accepts client requests for them. If
+    **DownloadExtraInfo** is set, cached extra info documents are also cached.
+    Setting **DirPort** is not required for **DirCache**, because clients
+    connect via the ORPort by default. Setting either DirPort or BridgeRelay
+    and setting DirCache to 0 is not supported.  (Default: 1)
+
+[[DirPolicy]] **DirPolicy** __policy__,__policy__,__...__::
+    Set an entrance policy for this server, to limit who can connect to the
+    directory ports. The policies have the same form as exit policies above,
+    except that port specifiers are ignored. Any address not matched by
+    some entry in the policy is accepted.
 
 [[DirPort]] **DirPort** ['address'**:**]{empty}__PORT__|**auto** [_flags_]::
     If this option is nonzero, advertise the directory service on this port.
@@ -2689,19 +2709,11 @@ details.)
      +
     The same flags are supported here as are supported by ORPort.
 
-[[DirPolicy]] **DirPolicy** __policy__,__policy__,__...__::
-    Set an entrance policy for this server, to limit who can connect to the
-    directory ports. The policies have the same form as exit policies above,
-    except that port specifiers are ignored. Any address not matched by
-    some entry in the policy is accepted.
-
-[[DirCache]] **DirCache** **0**|**1**::
-    When this option is set, Tor caches all current directory documents except
-    extra info documents, and accepts client requests for them. If
-    **DownloadExtraInfo** is set, cached extra info documents are also cached.
-    Setting **DirPort** is not required for **DirCache**, because clients
-    connect via the ORPort by default. Setting either DirPort or BridgeRelay
-    and setting DirCache to 0 is not supported.  (Default: 1)
+[[DirPortFrontPage]] **DirPortFrontPage** __FILENAME__::
+    When this option is set, it takes an HTML file and publishes it as "/" on
+    the DirPort. Now relay operators can provide a disclaimer without needing
+    to set up a separate webserver. There's a sample disclaimer in
+    contrib/operator-tools/tor-exit-notice.html.
 
 [[MaxConsensusAgeForDiffs]] **MaxConsensusAgeForDiffs**  __N__ **minutes**|**hours**|**days**|**weeks**::
     When this option is nonzero, Tor caches will not try to generate