commit 2ac768e89f16230d9af1ea5dd84856568d4ceeef
Author: Nick Mathewson <nickm(a)torproject.org>
Date: Thu Mar 10 18:25:51 2011 -0500
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.
---
doc/tor.1.txt | 74 ++++++++++++++++++++++++++++++++++++++++++++------------
1 files changed, 58 insertions(+), 16 deletions(-)
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index f1734d2..866a702 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