Merge remote-tracking branch 'tor-github/pr/1711'

2 files changed, 333 insertions, 302 deletions

diff --git a/changes/ticket32928 b/changes/ticket32928
new file mode 100644
index 0000000000..f7739e928d
--- /dev/null
+++ b/changes/ticket32928
@@ -0,0 +1,7 @@
+  o Documentation (manpage):
+    - Split Circuit Timeout options into their own section of the tor
+      manpage.  Closes ticket 32928.  Work by Swati Thacker as part of
+      Google Season of Docs.
+    - Split Node selection options into their own section of the tor
+      manpage.  Closes ticket 32929.  Work by Swati Thacker as part of
+      Google Season of Docs.
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index a5108df805..a9b9852b7d 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -998,18 +998,6 @@ 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)
-
-[[CircuitBuildTimeout]] **CircuitBuildTimeout** __NUM__::
-
-    Try for at most NUM seconds when building circuits. If the circuit isn't
-    open in that time, give up on it. If LearnCircuitBuildTimeout is 1, this
-    value serves as the initial value to use before a timeout is learned. 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
@@ -1025,22 +1013,6 @@ The following options are useful only for clients (that is, if
     via the UI to mobile users for use where bandwidth may be expensive.
     (Default: 0)
 
-[[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
-    open, as well as the amount of time Tor will keep a circuit open to each
-    of the recently used ports. This way when the Tor client is entirely
-    idle, it can expire all of its circuits, and then expire its TLS
-    connections. Note that the actual timeout value is uniformly randomized
-    from the specified value to twice that amount. (Default: 30 minutes;
-    Max: 24 hours)
-
-[[CircuitStreamTimeout]] **CircuitStreamTimeout** __NUM__::
-    If non-zero, this option overrides our internal timeout schedule for how
-    many seconds until we detach a stream from a circuit and try a new circuit.
-    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
@@ -1166,43 +1138,6 @@ The following options are useful only for clients (that is, if
     addresses/ports. See SocksPort for an explanation of isolation
     flags. (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.)
-
-[[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
@@ -1214,76 +1149,6 @@ 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)
 
-[[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
-    patterns of nodes to avoid when building a circuit. Country codes are
-    2-letter ISO3166 codes, and must
-    be wrapped in braces; fingerprints may be preceded by a dollar sign.
-    (Example:
-    ExcludeNodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) +
-     +
-    By default, this option is treated as a preference that Tor is allowed
-    to override in order to keep working.
-    For example, if you try to connect to a hidden service,
-    but you have excluded all of the hidden service's introduction points,
-    Tor will connect to one of them anyway.  If you do not want this
-    behavior, set the StrictNodes option (documented below).  +
-     +
-    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. +
-     +
-    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.
-
-// 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
-    node that delivers traffic for you *outside* the Tor network.   Note that any
-    node listed in ExcludeNodes is automatically considered to be part of this
-    list too.  See
-    the **ExcludeNodes** option for more information on how to specify
-    nodes. See also the caveats on the "ExitNodes" option below.
-
-[[ExitNodes]] **ExitNodes** __node__,__node__,__...__::
-    A list of identity fingerprints, country codes, and address
-    patterns of nodes to use as exit node---that is, a
-    node that delivers traffic for you *outside* the Tor network.  See
-    the **ExcludeNodes** option for more information on how to specify nodes. +
-     +
-    Note that if you list too few nodes here, or if you exclude too many exit
-    nodes with ExcludeExitNodes, you can degrade functionality.  For example,
-    if none of the exits you list allows traffic on port 80 or 443, you won't
-    be able to browse the web. +
-     +
-    Note also that not every circuit is used to deliver traffic *outside* of
-    the Tor network.  It is normal to see non-exit circuits (such as those
-    used to connect to hidden services, those that do directory fetches,
-    those used for relay reachability self-tests, and so on) that end
-    at a non-exit node.  To
-    keep a node from being used entirely, see ExcludeNodes and StrictNodes. +
-     +
-    The ExcludeNodes option overrides this option: any node listed in both
-    ExitNodes and ExcludeNodes is treated as excluded. +
-     +
-    The .exit address notation, if enabled via MapAddress, overrides
-    this option.
-
 [[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**).
@@ -1297,14 +1162,6 @@ The following options are useful only for clients (that is, if
     **FascistFirewall** is set. This option is deprecated; use ReachableAddresses
     instead. (Default: 80, 443)
 
-[[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
     characters in a-z2-7 plus ".onion", and valid auth cookies contain 22
@@ -1315,116 +1172,6 @@ The following options are useful only for clients (that is, if
     services can be configured to require authorization using the
     **HiddenServiceAuthorizeClient** option.
 
-[[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.
-
 [[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
@@ -1510,26 +1257,6 @@ 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.
@@ -1546,16 +1273,6 @@ The following options are useful only for clients (that is, if
     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
-    any two of them in the same circuit. Defining a NodeFamily is only needed
-    when a server doesn't list the family itself (with MyFamily). This option
-    can be used multiple times; each instance defines a separate family.  In
-    addition to nodes, you can also list IP address and ranges and country
-    codes in {curly braces}. See the **ExcludeNodes** option for more
-    information on how to specify nodes.
-
 [[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
@@ -1871,24 +1588,6 @@ 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.
 
-[[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)
-
 [[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,
@@ -2033,6 +1732,331 @@ 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.
 
+== CIRCUIT TIMEOUT OPTIONS
+
+// These options are in alphabetical order, with exceptions as noted.
+// Please keep them that way!
+
+The following options are useful for configuring timeouts related
+to building Tor circuits and using them:
+
+[[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
+    open, as well as the amount of time Tor will keep a circuit open to each
+    of the recently used ports. This way when the Tor client is entirely
+    idle, it can expire all of its circuits, and then expire its TLS
+    connections. Note that the actual timeout value is uniformly randomized
+    from the specified value to twice that amount. (Default: 30 minutes;
+    Max: 24 hours)
+
+// Out of order because it logically belongs before the CircuitBuildTimeout option
+[[LearnCircuitBuildTimeout]] **LearnCircuitBuildTimeout** **0**|**1**::
+    If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1)
+
+[[CircuitBuildTimeout]] **CircuitBuildTimeout** __NUM__::
+    Try for at most NUM seconds when building circuits. If the circuit isn't
+    open in that time, give up on it. If LearnCircuitBuildTimeout is 1, this
+    value serves as the initial value to use before a timeout is learned. If
+    LearnCircuitBuildTimeout is 0, this value is the only value used.
+    (Default: 60 seconds)
+
+[[CircuitStreamTimeout]] **CircuitStreamTimeout** __NUM__::
+    If non-zero, this option overrides our internal timeout schedule for how
+    many seconds until we detach a stream from a circuit and try a new circuit.
+    If your network is particularly slow, you might want to set this to a
+    number like 60. (Default: 0)
+
+[[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)
+
+== DORMANT MODE OPTIONS
+
+// These options are in alphabetical order, with exceptions as noted.
+// Please keep them that way!
+
+Tor can enter dormant mode to conserve power and network bandwidth.
+The following options control when Tor enters and leaves dormant mode:
+
+[[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.)
+
+[[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)
+
+== NODE SELECTION OPTIONS
+
+// These options are in alphabetical order, with exceptions as noted.
+// Please keep them that way!
+
+The following options restrict the nodes that a tor client
+(or onion service) can use while building a circuit.
+These options can weaken your anonymity by making your client behavior
+different from other Tor clients:
+
+[[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
+    patterns of nodes to avoid when building a circuit. Country codes are
+    2-letter ISO3166 codes, and must
+    be wrapped in braces; fingerprints may be preceded by a dollar sign.
+    (Example:
+    ExcludeNodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) +
+     +
+    By default, this option is treated as a preference that Tor is allowed
+    to override in order to keep working.
+    For example, if you try to connect to a hidden service,
+    but you have excluded all of the hidden service's introduction points,
+    Tor will connect to one of them anyway.  If you do not want this
+    behavior, set the StrictNodes option (documented below).  +
+     +
+    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. +
+     +
+    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.
+
+// 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
+    node that delivers traffic for you *outside* the Tor network.   Note that any
+    node listed in ExcludeNodes is automatically considered to be part of this
+    list too.  See
+    the **ExcludeNodes** option for more information on how to specify
+    nodes. See also the caveats on the "ExitNodes" option below.
+
+[[ExitNodes]] **ExitNodes** __node__,__node__,__...__::
+    A list of identity fingerprints, country codes, and address
+    patterns of nodes to use as exit node---that is, a
+    node that delivers traffic for you *outside* the Tor network.  See
+    the **ExcludeNodes** option for more information on how to specify nodes. +
+     +
+    Note that if you list too few nodes here, or if you exclude too many exit
+    nodes with ExcludeExitNodes, you can degrade functionality.  For example,
+    if none of the exits you list allows traffic on port 80 or 443, you won't
+    be able to browse the web. +
+     +
+    Note also that not every circuit is used to deliver traffic *outside* of
+    the Tor network.  It is normal to see non-exit circuits (such as those
+    used to connect to hidden services, those that do directory fetches,
+    those used for relay reachability self-tests, and so on) that end
+    at a non-exit node.  To
+    keep a node from being used entirely, see ExcludeNodes and StrictNodes. +
+     +
+    The ExcludeNodes option overrides this option: any node listed in both
+    ExitNodes and ExcludeNodes is treated as excluded. +
+     +
+    The .exit address notation, if enabled via MapAddress, overrides
+    this option.
+
+[[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)
+
+[[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.
+
+[[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.
+
+[[NodeFamily]] **NodeFamily** __node__,__node__,__...__::
+    The Tor servers, defined by their identity fingerprints,
+    constitute a "family" of similar or co-administered servers, so never use
+    any two of them in the same circuit. Defining a NodeFamily is only needed
+    when a server doesn't list the family itself (with MyFamily). This option
+    can be used multiple times; each instance defines a separate family.  In
+    addition to nodes, you can also list IP address and ranges and country
+    codes in {curly braces}. 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)
 
 == SERVER OPTIONS
 
@@ -3652,7 +3676,7 @@ __DataDirectory__/**`approved-routers`**::
     __DataDirectory__ for an example fingerprint line. If the status is
     **!reject** then descriptors from the given identity (fingerprint/pubkey)
     are rejected by this server. If it is **!invalid** then descriptors are
-    accepted but marked in the directory as not valid, that is, not 
+    accepted but marked in the directory as not valid, that is, not
     recommended.
 
 __DataDirectory__/**`v3-status-votes`**::