Revise the manpage to contain the actual intended *Nodes behavior

This is a squashed version of my former desired_nodes_behavior branch
that we used to specify the intended results wrt bug 1090.

1 files changed, 58 insertions, 16 deletions

diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index f1734d2016..866a702e51 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -489,32 +489,74 @@ The following options are useful only for clients (that is, if
 
 **ExcludeNodes** __node__,__node__,__...__::
     A list of identity fingerprints, nicknames, country codes and address
-    patterns of nodes to never use when building a circuit. (Example:
-    ExcludeNodes SlowServer, $    EFFFFFFFFFFFFFFF, \{cc}, 255.254.0.0/8)
+    patterns of nodes to avoid when building a circuit.
+    (Example:
+    ExcludeNodes SlowServer, $    EFFFFFFFFFFFFFFF, \{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.
+
 
 **ExcludeExitNodes** __node__,__node__,__...__::
     A list of identity fingerprints, nicknames, country codes and address
-    patterns of nodes to never use when picking an exit node. Note that any
+    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.
+    list too.  See also the caveats on the "ExitNodes" option below
 
-**EntryNodes** __node__,__node__,__...__::
-    A list of identity fingerprints, nicknames and address
-    patterns of nodes to use for the first hop in normal circuits. These are
-    treated only as preferences unless StrictNodes (see below) is also set.
 
 **ExitNodes** __node__,__node__,__...__::
     A list of identity fingerprints, nicknames, country codes and address
-    patterns of nodes to use for the last hop in normal exit circuits. These
-    are treated only as preferences unless StrictNodes (see below) is also set.
+    patterns of nodes to use as exit node---that is, a
+    node that delivers traffic for you outside the Tor network. +
++
+    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 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, overrides this option.
+
+**EntryNodes** __node__,__node__,__...__::
+    A list of identity fingerprints and nicknames of nodes
+    to use for the first hop in your normal circuits.  (Country codes and
+    address patterns are not yet supported.)  This includes 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.
 
 **StrictNodes** **0**|**1**::
-    If 1 and EntryNodes config option is set, Tor will never use any nodes
-    besides those listed in EntryNodes for the first hop of a normal circuit.
-    If 1 and ExitNodes config option is set, Tor will never use any nodes
-    besides those listed in ExitNodes for the last hop of a normal exit
-    circuit. Note that Tor might still use these nodes for non-exit circuits
-    such as one-hop directory fetches or hidden service support circuits.
+    If StrictNodes is set to 1, Tor will treat the ExcludeNodes option as a
+    requirement to follow for all the circuits you generate, even if doing so
+    will break functionality for you.  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 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)
 
 **FascistFirewall** **0**|**1**::
     If 1, Tor will only create outgoing connections to ORs running on ports