doc/spec/address-spec.txt

   1 $Id$
   2
   3                           Special Hostnames in Tor
   4                                Nick Mathewson
   5
   6 1. Overview
   7
   8   Most of the time, Tor treats user-specified hostnames as opaque:  When
   9   the user connects to www.torproject.org, Tor picks an exit node and uses
  10   that node to connect to "www.torproject.org".  Some hostnames, however,
  11   can be used to override Tor's default behavior and circuit-building
  12   rules.
  13
  14   These hostnames can be passed to Tor as the address part of a SOCKS4a or
  15   SOCKS5 request.  If the application is connected to Tor using an IP-only
  16   method (such as SOCKS4, TransPort, or NatdPort), these hostnames can be
  17   substituted for certain IP addresses using the MapAddress configuration
  18   option or the MAPADDRESS control command.
  19
  20 2. .exit
  21
  22   SYNTAX:  [hostname].[name-or-digest].exit
  23            [name-or-digest].exit
  24
  25   Hostname is a valid hostname; [name-or-digest] is either the nickname of a
  26   Tor node or the hex-encoded digest of that node's public key.
  27
  28   When Tor sees an address in this format, it uses the specified hostname as
  29   the exit node.  If no "hostname" component is given, Tor defaults to the
  30   published IPv4 address of the exit node.
  31
  32   It is valid to try to resolve hostnames, and in fact upon success Tor
  33   will cache an internal mapaddress of the form
  34   "www.google.com.foo.exit=64.233.161.99.foo.exit" to speed subsequent
  35   lookups.
  36
  37   EXAMPLES:
  38      www.example.com.exampletornode.exit
  39
  40         Connect to www.example.com from the node called "exampletornode."
  41
  42      exampletornode.exit
  43
  44         Connect to the published IP address of "exampletornode" using
  45         "exampletornode" as the exit.
  46
  47 3. .onion
  48
  49   SYNTAX:  [digest].onion
  50
  51   The digest is the first eighty bits of a SHA1 hash of the identity key for
  52   a hidden service, encoded in base32.
  53
  54   When Tor sees an address in this format, it tries to look up and connect to
  55   the specified hidden service.  See rend-spec.txt for full details.
  56
  57 4. .noconnect
  58
  59   SYNTAX:  [string].noconnect
  60
  61   When Tor sees an address in this format, it immediately closes the
  62   connection without attaching it to any circuit.  This is useful for
  63   controllers that want to test whether a given application is indeed using
  64   the same instance of Tor that they're controlling.
  65
  66 5. [XXX Is there a ".virtual" address that we expose too, or is that
  67 just intended to be internal? -RD]
  68