[or-cvs] r9155: Add address-spec.txt document to describe .exit, .onion, and (in tor/trunk: . doc)

[nickm@xxxxxxxx]

Author: nickm
Date: 2006-12-19 14:48:54 -0500 (Tue, 19 Dec 2006)
New Revision: 9155

Added:
   tor/trunk/doc/address-spec.txt
Modified:
   tor/trunk/
   tor/trunk/doc/Makefile.am
   tor/trunk/doc/TODO
Log:
 r11644@Kushana:  nickm | 2006-12-19 14:07:17 -0500
 Add address-spec.txt document to describe .exit, .onion, and .noconnnect.  Hopefully, we will not add too many of these just because we have a file for them now...



Property changes on: tor/trunk
___________________________________________________________________
 svk:merge ticket from /tor/trunk [r11644] on c95137ef-5f19-0410-b913-86e773d04f59

Modified: tor/trunk/doc/Makefile.am
===================================================================
--- tor/trunk/doc/Makefile.am	2006-12-19 19:48:48 UTC (rev 9154)
+++ tor/trunk/doc/Makefile.am	2006-12-19 19:48:54 UTC (rev 9155)
@@ -1,7 +1,7 @@
 
 EXTRA_DIST = tor-spec.txt rend-spec.txt control-spec.txt     \
              dir-spec.txt socks-extensions.txt path-spec.txt \
-             version-spec.txt                                \
+             version-spec.txt address-spec.txt               \
              website img HACKING                             \
              tor-resolve.1                                   \
              tor-osx-dmg-creation.txt tor-rpm-creation.txt   \

Modified: tor/trunk/doc/TODO
===================================================================
--- tor/trunk/doc/TODO	2006-12-19 19:48:48 UTC (rev 9154)
+++ tor/trunk/doc/TODO	2006-12-19 19:48:54 UTC (rev 9155)
@@ -60,7 +60,7 @@
         a version, treat it like one. If it's something else, assume
         it's at least 0.1.2.x.
 
-N - Document .noconnect addresses...
+  o Document .noconnect addresses...
     A new file 'address-spec.txt' that describes .exit, .onion,
     .noconnect, etc?
 

Added: tor/trunk/doc/address-spec.txt
===================================================================
--- tor/trunk/doc/address-spec.txt	2006-12-19 19:48:48 UTC (rev 9154)
+++ tor/trunk/doc/address-spec.txt	2006-12-19 19:48:54 UTC (rev 9155)
@@ -0,0 +1,61 @@
+$Id$
+
+                          Special Hostnames in Tor
+                               Nick Mathewson
+
+1. Overview
+
+  Most of the time, Tor treats user-specified hostnames as opaque:  When the
+  user connects to tor.eff.org, Tor picks an exit node and uses that node to
+  connect to "tor.eff.org".  Some hostnames, however, can be used to override
+  Tor's default behavior and circuit-building rules.
+
+  These hostnames can be passed to Tor as the address part of a SOCKS4a or
+  SOCKS5 request.  If the application is connected to Tor using an IP-only
+  method (such as SOCKS4, TransPort, or NatdPort), these hostnames can be
+  substituted for certain IP addresses using the MapAddress configuration
+  option or the MAPADDRESS control command.
+
+2. .exit
+
+  SYNTAX:  [hostname].[name-or-digest].exit
+           [name-or-digest].exit
+
+  Hostname is a valid hostname; [name-or-digest] is either the nickname of a
+  Tor node or the hex-encoded digest of that node's public key.
+
+  When Tor sees an address in this format, it uses the specified hostname as
+  the exit node.  If no "hostname" component is given, Tor defaults to the
+  published IPv4 address of the exit node.
+
+  It is valid to try to resolve hostnames 
+
+  EXAMPLES:
+     www.example.com.exampletornode.exit
+
+        Connect to www.example.com from the node called "exampletornode."
+
+     exampletornode.exit
+
+        Connect to the published IP address of "exampletornode" using
+        "exampletornode" as the exit.
+
+3. .onion
+
+  SYNTAX [digest].onion
+
+  The digest is the first eighty bits of a SHA1 hash of the identity key for
+  a hidden service, encoded in base32.
+
+  When Tor sees an address in this format, it tries to look up and connect to
+  the specified hidden service.  See rend-spec.txt for full details.
+
+4. .noconnect
+
+  SYNTAX: [string].noconnect
+
+  When Tor sees an address in this format, it immediately closes the
+  connection without attaching it to any circuit.  This is useful for
+  controllers that want to test whether a given application is indeed using
+  the same instance of Tor that they're controlling.
+


Property changes on: tor/trunk/doc/address-spec.txt
___________________________________________________________________
Name: svn:keywords
   + Author Date Id Revision