Copyright (C) 1998 WIDE Project.  All rights reserved.
Copyright (C) 1999 University of Tromso.  All rights reserved.

*** What does totd do? ***

Totd is a small DNS proxy nameserver that supports IPv6 only hosts/networks
that communicate with the IPv4 world using some translation mechanism. 
Examples of such translation mechanisms currently in use are: 

   * IPv6/IPv4 Network Address and Packet Translation (NAT-PT)
     implemented e.g. by Cisco.
   * Application level translators as the faithd implemented by 
     the KAME project (http://www.kame.net). See faithd(8) on
     *BSD/Kame.

These translators translate map IPv4 to IPv6 connections and back in some
way. In order for an application to connect through such a translator to
the world beyond it needs to use fake or fabricated addresses that are
routed to this translator. These fake addresses don't exist in the DNS,
and most likely you would not want them to appear there either. Totd
fixes this problem for now (until more elegant solutions emerge?) by
translating DNS queries/responses for the faked addresses. totd constructs
these fake addresses based on a configured IPv6 translator prefix and
records it *does* find in DNS. Totd is merely a stateless DNS-proxy, not 
a nameserver itself. Totd needs to be able to forward requests to a real 
nameserver.

*** Some other experimental things you could use totd for ***

Totd can do some things that are more experimental. you can select at
compile time whether you want these or not. Totd supports re-writing of scoped
addresses in DNS responses and supports reverse namelookup for 6to4 names.

Scoped address rewriting is briefly explained below in the section on totd's
config file.  6to4 reverse lookup is based on draft-moore-6to4-dns-00.txt, 
section 3.3:

     When such a resolver received a PTR or NS query for a label that
had a [x2002].IP6.ARPA suffix, it would first attempt to satisfy that
query from its cache, or failing that, by forwarding the query to an
upstream server.  If that query failed due to a "no such domain" error,
the resolver would then attempt to find the server for the
{something}.[x2002].IP6.ARPA label by issuing an NS query for
{something}.IN-ADDR.ARPA.

     If the original query was for PTR records, and one or more NS
records were found for {something}.IN-ADDR.ARPA, the resolver would then
forward the original query for {something}.[x2002].IP6.ARPA to one or
more of those servers, and return the results from one of the forwarded
queries if any were successful.

     If the original query was for NS records, and one or more NS
records were found for {something}.IN-ADDR.ARPA, the resolver would then
return the pseudo-records corresponding to the IN-ADDR.ARPA domains.
Those pseudo-records would NOT be marked as authoritative, and the
resolver would NOT cache those records.

*** Example Setup on the Web ***

For an example setup you may checkout our WWW-site: 

   http://www.vermicelli.pasta.cs.uit.no

and the following clickable image in particular:

http://www.vermicelli.pasta.cs.uit.no/ipv6/UiTo-ipv6.html

*** Contacting the Author ***

You can contact me (Feico Dillema) at feico at pasta.cs.uit.no (s/ at /@).

*** Compiling and Installing totd ***

   totd is known to compile and run on FreeBSD-2.2.8/KAME, NetBSD-1.4/Kame
   and later NetBSD versions (meaning at time of writing: NetBSD-current).
   totd is known to not work on non-BSD, non-Kame systems (e.g. Linux).
   Feel free to add Linux support etc yourself ;-}, and send me the patches.
   If compilation on your non-BSD system fails you can send me problem reports,
   which I may process or maybe not.

   The best way to compile and install totd is to:

   1. run ./configure
      configure takes --prefix <dir> as option to specify installation directory
   2. make && make install

   You may configure some settings of totd manually by editing Makefile and config.h, 
   produced by the configure command. If you want no debugging stuff compiled
   in, comment out the NDEBUG define in config.h. You may also want to leave
   out the experimental code by setting SCOPED_REWRITE and STF to zero, if you
   do not need these features (if you have no clue what they are for you
   probably do not need them).

   If the best way doesn't work, you are basically on your own. Have fun.

*** How to use ***

You either have to run totd as root or define a user and group called `tot'.
In the latter case totd still needs to be started as root but it will only
grant itself root-privilege when opening the necessary sockets. At all other 
times it runs as user `tot'.

Usage: totd [-6|-no6|-4|-no4|-64|-d|-v]

-[no]6      : enable[disable] IPv6 service functionality
-[no]4      : enable[disable] IPv4 service functionality
-64         : alias to -6 -4
-d#         : debug mode (no fork, # defines debuglevel and ranges from 0 to 5)
-p <prefix> : specify translation network prefix (adds to those in config file)
-v          : show usage information

and you need to setup a <prefix>/etc/totd.conf file (seem below).

*** The <prefix>/etc/totd.conf configuration file ***

In the config file the first word is a keyword and it is followed by a
value and or one or more attributes or optional value. Stuff between
square brackets `[' and `]' below is optional while stuff between hooks
`<' and `>' signifies a value. (Neither the square brackets nor hooks are
meant to be in the config file).

The following keywords are valid in the totd.conf file:

forwarder <ip address> [port <service port>] 

   Totd is just a DNS-proxy; it does not make (recursive) queries itself. It can 
   only forward queries to a real nameserver. With keyword `forwarder' you can 
   specify an IP address (either IPv4 or IPv6) of such a nameserver for totd to 
   use. If there are multiple forwarders specified, it will use them in the order 
   listed.  When a nameserver is or becomes unreachable totd will use the next 
   nameserver in line. After the retry interval amount of time, totd will switch 
   back to the previous nameserver. If that nameserver is still unreachable it 
   will double the retry interval for it and start using the next nameserver 
   in the config file again. The (starting) retry interval can be specified in
   the config file (see below). You may see totd switch to backup nameservers
   for no apparent good reason, as totd is not very good at discriminating
   between an unreachable/malfunctioning nameserver or a single query that 
   returns erronous results. 

   (If the second nameserver is also unreachable and a third is specified, this
   sequence repeats itself with a retry interval kept for each nameserver that is
   down.)
   
   With the optional port attribute an alternative port can be specified to
   query the forwarder on.  The default is the standard domain service port,
   i.e. 53. This feature is mainly useful for running totd and a forwarder
   nameserver, e.g. bind on the same machine. In such a case, clients can
   talk to totd on port 53, totd talks to named over some other port.

   At least one forwarder needs to be specified in order for totd to have
   non-trivial behaviour.

prefix <IPv6 network prefix>
     
   Prefix must be written in IPv6 address format like (but without the quotes):

                          `3ffe:1234:abcd:1234::'

   Totd treats each AAAA type query in a special way. If the nameserver does
   not return an IPv6 address for the forwarded AAAA query, totd will make a
   second query but this time for an A record of the hostname of the original
   query. The resulting IPv4 address is then used to construct a fake IPv6
   address, by replacing the lower 32 bits of the specified prefix with
   this IPv4 address. The resulting IPv6 address is sent as response to
   the original AAAA record query. 

   In addition, totd treats PTR type queries (reverse name lookup) in the 
   ip6.int. domain specially. If the query matches the specified prefix,
   totd will forward a PTR query for an IPv4 address (using the lower 32
   bits of the address to construct an IPv4 address) instead and use that
   to construct a faked response to the original PTR query. 

   Introduced in patch release 1.1p2 is support for multiple prefixes. If 
   multiple prefixed are configured, totd will cycle through them consecutively. 
   In this way totd can balance the load for multiple NAT-PT/faithd(8)
   translators in a network. The maximum number of prefixes that totd will
   accept is by default set to 5. This can be changed at compile time by
   defining MAXPREFIXES (see config.h.in) to another value.

scoped <v6 prefix 1> <v6 prefix 2> <prefixlen>

   Scoped query support.

   If the query is made from scoped source address (link-local unicast or
   site-local unicast), and query's target address (totd's listening address)
   is also scoped address, attach additional AAAA records converted by using
   3 arguments.

   For example, when you configure as below:

	scoped 3ffe:501:ffff:: fec0:: 48

   and you made query from scoped source to totd's scoped destination,
   and the result has the following record:

	foo.kame.net.	IN AAAA	3ffe:501:ffff::9876:5432

   it will get additional records as follows:

	foo.kame.net.	IN AAAA	3ffe:501:ffff::9876:5432
	foo.kame.net.	IN AAAA	fec0::9876:5432

   At this moment, prefixlen must be multiple of 8.

   Reverse query for fec0::9876:5432 will be converted into
   3ffe:501:ffff::9876:5432 and forwarded to the real DNS servers.

retry <retry interval>

   This time interval is specified in seconds. It's meaning is described
   above under the forwarder keyword.


*** Example totd.conf ***

# This is a comment in the example totd.conf file
forwarder	127.0.0.1  			port 55
# specifying no port implies port 53, the default for DNS queries
# (note this didn't work in 1.1p1 release, due to a bug)
forwarder	3ffe:2fff:0101:9876::10	
forwarder	192.168.1.7
; This is also a comment
prefix	3ffe:2fff:0101:1234:: 		# this is a comment on the prefix
; 5 minutes retry interval 
retry	300				# in seconds
; exerimental stuff 
; scoped addresses
scoped 3ffe:2fff:0101:9800:: fec0:: 56
; enable 6to4 reverse address lookup trick
stf
