[or-cvs] r13154: explain a bit about router descriptor purposes (tor/trunk/doc/spec)

[arma@xxxxxxxx]

Author: arma
Date: 2008-01-17 00:47:44 -0500 (Thu, 17 Jan 2008)
New Revision: 13154

Modified:
   tor/trunk/doc/spec/control-spec.txt
   tor/trunk/doc/spec/path-spec.txt
Log:
explain a bit about router descriptor purposes


Modified: tor/trunk/doc/spec/control-spec.txt
===================================================================
--- tor/trunk/doc/spec/control-spec.txt	2008-01-17 05:25:21 UTC (rev 13153)
+++ tor/trunk/doc/spec/control-spec.txt	2008-01-17 05:47:44 UTC (rev 13154)
@@ -654,8 +654,8 @@
                       CRLF Descriptor CRLF "." CRLF
 
   This message informs the server about a new descriptor. If Purpose is
-  specified, it must be either "general" or "controller", else we
-  return a 552 error.
+  specified, it must be either "general", "controller", or "bridge",
+  else we return a 552 error.
 
   If Cache is specified, it must be either "no" or "yes", else we
   return a 552 error. If Cache is not specified, Tor will decide for

Modified: tor/trunk/doc/spec/path-spec.txt
===================================================================
--- tor/trunk/doc/spec/path-spec.txt	2008-01-17 05:25:21 UTC (rev 13153)
+++ tor/trunk/doc/spec/path-spec.txt	2008-01-17 05:47:44 UTC (rev 13154)
@@ -182,7 +182,7 @@
    proportional to its advertised bandwidth [the smaller of the 'rate' and
    'observed' arguments to the "bandwidth" element in its descriptor].  If a
    router's advertised bandwidth is greater than MAX_BELIEVABLE_BANDWIDTH
-   (10 MB/s), we clip to that value.
+   (currently 10 MB/s), we clip to that value.
 
    For non-exit positions on "fast" circuits, we pick routers as above, but
    we weight the clipped advertised bandwidth of Exit-flagged nodes depending
@@ -351,10 +351,25 @@
   Tor does not add a guard persistently to the list until the first time we
   have connected to it successfully.
 
+6. Router descriptor purposes
 
+  There are currently three "purposes" supported for router descriptors:
+  general, controller, and bridge. Most descriptors are of type general
+  -- these are the ones listed in the consensus, and the ones fetched
+  and used in normal cases.
 
+  Controller-purpose descriptors are those delivered by the controller
+  and labelled as such: they will be kept around (and expire like
+  normal descriptors), and they can be used by the controller in its
+  CIRCUITEXTEND commands. Otherwise they are ignored by Tor when it
+  chooses paths.
 
+  Bridge-purpose descriptors are for routers that are used as bridges. See
+  doc/design-paper/blocking.pdf for more design explanation, or proposal
+  125 for specific details. Currently bridge descriptors are used in place
+  of normal entry guards, for Tor clients that have UseBridges enabled.
 
+
 X. Old notes
 
 X.1. Do we actually do this?