[tor-commits] [tor/master] Throw identify-node-by-nickname down the memory hole

Thu Nov 6 16:15:30 UTC 2014

commit 68af1e7e9be8bef82b4574ac0934310af71a764b
Author: Nick Mathewson <nickm at torproject.org>
Date:   Thu Nov 6 11:10:58 2014 -0500

    Throw identify-node-by-nickname down the memory hole
    
    Authorities are no longer voting on Named, so specifying nodes by
    nickname isn't a clever thing to do.  (Not that it ever was!)  So
    remove the documentation that suggests that you should do it.
    
    Additionally, add proper cross-references to our __node__ lists, and
    explain about the optional $ before identity digests.
    
    Also, the oxford comma: endorsed by Steven Pinker, my spouse, and my
    11th grade English teacher.
    
    Closes 13381.
---
 changes/doc13381 |    5 +++++
 doc/tor.1.txt    |   40 ++++++++++++++++++++++++----------------
 2 files changed, 29 insertions(+), 16 deletions(-)

diff --git a/changes/doc13381 b/changes/doc13381
new file mode 100644
index 0000000..acc4bb8
--- /dev/null
+++ b/changes/doc13381
@@ -0,0 +1,5 @@
+  o Documentation:
+    - Stop suggesting that users specify nodes by nickname: it isn't a
+      good idea. Also, properly cross-reference how to specify nodes
+      in all parts of the manual for options that take a list of
+      nodes. Closes ticket 13381.
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index 84070da..1c3be8c 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -711,10 +711,11 @@ The following options are useful only for clients (that is, if
     unless ORPort, ExtORPort, or DirPort are configured.) (Default: 0)
 
 [[ExcludeNodes]] **ExcludeNodes** __node__,__node__,__...__::
-    A list of identity fingerprints, nicknames, country codes and address
-    patterns of nodes to avoid when building a circuit.
+    A list of identity fingerprints, country codes, and address
+    patterns of nodes to avoid when building a circuit. Country codes must
+    be wrapped in braces; fingerprints may be preceded by a dollar sign.
     (Example:
-    ExcludeNodes SlowServer, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) +
+    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.
@@ -734,11 +735,13 @@ The following options are useful only for clients (that is, if
 
 
 [[ExcludeExitNodes]] **ExcludeExitNodes** __node__,__node__,__...__::
-    A list of identity fingerprints, nicknames, country codes and address
+    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 also the caveats on the "ExitNodes" option below.
+    list too.  See
+    the **ExcludeNodes** option for more information on how to specify
+    nodes. See also the caveats on the "ExitNodes" option below.
 
 [[GeoIPExcludeUnknown]] **GeoIPExcludeUnknown** **0**|**1**|**auto**::
     If this option is set to 'auto', then whenever any country code is set in
@@ -749,9 +752,10 @@ The following options are useful only for clients (that is, if
     configured or can't be found.  (Default: auto)
 
 [[ExitNodes]] **ExitNodes** __node__,__node__,__...__::
-    A list of identity fingerprints, nicknames, country codes and address
+    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. +
+    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,
@@ -772,7 +776,7 @@ The following options are useful only for clients (that is, if
     this option.
 
 [[EntryNodes]] **EntryNodes** __node__,__node__,__...__::
-    A list of identity fingerprints, nicknames, and country codes of nodes
+    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
@@ -780,7 +784,8 @@ The following options are useful only for clients (that is, if
     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.
+    EntryNodes and ExcludeNodes is treated as excluded. 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 the ExcludeNodes option as a
@@ -929,12 +934,14 @@ The following options are useful only for clients (that is, if
     but it has not yet been completely constructed.  (Default: 32)
 
 [[NodeFamily]] **NodeFamily** __node__,__node__,__...__::
-    The Tor servers, defined by their identity fingerprints or nicknames,
+    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.  In addition to nodes, you can also list
-    IP address and ranges and country codes in {curly braces}.
+    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.
 
 [[EnforceDistinctSubnets]] **EnforceDistinctSubnets** **0**|**1**::
     If 1, Tor will not put two servers whose IP addresses are "too close" on
@@ -1538,7 +1545,7 @@ is non-zero):
 [[MyFamily]] **MyFamily** __node__,__node__,__...__::
     Declare that this Tor server is controlled or administered by a group or
     organization identical or similar to that of the other servers, defined by
-    their identity fingerprints or nicknames. When two servers both declare
+    their identity fingerprints. When two servers both declare
     that they are in the same \'family', Tor clients will not use them in the
     same circuit. (Each server only needs to list the other servers in its
     family; it doesn't need to list itself, but it won't hurt.) Do not list
@@ -2204,16 +2211,17 @@ The following options are used for running a testing Tor network.
     Changing this requires that **TestingTorNetwork** is set. (Default: 8)
 
 [[TestingDirAuthVoteExit]] **TestingDirAuthVoteExit** __node__,__node__,__...__::
-    A list of identity fingerprints, nicknames, country codes and
+    A list of identity fingerprints, country codes, and
     address patterns of nodes to vote Exit for regardless of their
     uptime, bandwidth, or exit policy. See the **ExcludeNodes**
     option for more information on how to specify nodes.
  +
     In order for this option to have any effect, **TestingTorNetwork**
-    has to be set.
+    has to be set. See the **ExcludeNodes** option for more
+    information on how to specify nodes.
 
 [[TestingDirAuthVoteGuard]] **TestingDirAuthVoteGuard** __node__,__node__,__...__::
-    A list of identity fingerprints, nicknames, country codes and
+    A list of identity fingerprints and country codes and
     address patterns of nodes to vote Guard for regardless of their
     uptime and bandwidth. See the **ExcludeNodes** option for more
     information on how to specify nodes.

