Man Linux: Main Page and Category List


       totd - DNS proxy and translator for IPv6 and IPv4


       totd   [-6]   [-no6]  [-4]  [-no4]  [-64]  [-d<n>]  [-p  <prefix>]  [-c
       <configfile>]  [-u <user>]  [-g <group>]  [-t <dir>] [-q] [-v] [-h]


       Totd is a small DNS proxy nameserver. Its main purpose  is  to  support
       IPv6-only  hosts/networks  that  communicate  with the IPv4 world using
       some network or transport level translation mechanism, like  NAT-PT  or
       faithd(8).  In  addition,  it has some other useful tricks and features
       one might fancy in a DNS proxy.  Note that totd needs  to  be  able  to
       forward requests to a real nameserver (called a forwarder), in order to
       be useful.


       If you want to run totd on a privileged port, e.g. the default port 53,
       you  either have to run totd as root or start as root but let it switch
       to another user and group after it has opened  the  sockets  its  needs
       (see -u and -g options). In the former case, totd is able to rescan the
       interface list and deal with interface and address changes on the  fly.
       In  the  latter  case,  totd  will not be able to rescan interfaces and
       react to such changes but needs to be restarted to handle such changes.

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

       The following keywords are valid in the totd config file:

       forwarder <ip address> [port <service port>]
              With  this keyword you can specify an IP address (either IPv4 or
              IPv6) of a nameserver for totd to forward its queries to.   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>
              Specifies  a  64 bit IPv6 address prefix to use for the ‘address
              translation trick’ described in more detail below.   The  prefix
              must  be  written  in  IPv6 address format like (but without the
              quotes): ‘3ffe:1234:abcd:1234::’.

       port <port number>
              This option allows you to specify  a  different  (TCP/UDP)  port
              than the default (53) for totd to listen on.

       interfaces <ifa> [<ifb> <ifc> ...]
              By  default totd listens on wildcard sockets. This option allows
              you to specify what network interfaces totd should listen on for
              incoming requests. Note, that his option is not available on all
              operating systems (not on Linux e.g.).  When  ’*’  is  named  as
              interface,  the  the  interface  list  is  ignored  and wildcard
              sockets are used. If ’all’ is named as interface, totd will scan
              all  interfaces for addresses and open a socket to listen on for
              each of them. (Mostly useful in combination with scoped  address
              rewriting, see scoped keyword).

       pidfile <filename>
              Changes  the  default  filename for totd to write its process id
              into.  stf
              Enable 6to4 PTR rewriting.

       scoped <v6 prefix 1> <v6 prefix 2> <prefixlen>
              Enable scoped address rewriting. This  requires  currently  that
              the  interfaces  keyword  is  also  used,  i.e.  scoped  address
              rewriting is not supported for wildcard sockets.


       -d<n>  Run totd in foreground to facilitate debugging and set debugging
              output level to n.

       -6     Listen on IPv6 addresses for client queries

       -no6   Do not listen on IPv6 addresses

       -4     Listen on IPv4 addresses

       -no4   Do not listen on IPv4 addresses

       -64    Listen to both IPv4 and IPv6 addresses

       -p <prefix>
              Add a IPv6 prefix to trick list

       -c <filename>
              Specify alternative config file for totd to read in

       -u <user>
              Specify username or uid totd should switch to

       -g <group>
              Specify groupname or gid totd should switch to

       -t <dir>
              Specify a root directory to chroot() to

       -h     Output version and usage information and exit

       -q     Log only errors to syslog, be more quiet.

       -v     Log   more   verbosely,  also  log  warnings  and  informational


       Totd is just a DNS-proxy; it does not answer  queries  itself.  It  can
       only  forward  queries  to  a  real  nameserver.  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
       uses the next nameserver in the config file again.  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 or is simply
       delayed a lot.
       (If the second nameserver is also unreachable and a third is specified,
       this sequence repeats itself.)


       Totd  can  treat  each  AAAA  and  A6 type query in a special way. This
       behaviour is enabled when one or more prefixes are configured  (on  the
       commandline  or  with  the  ‘prefix’ keyword in the config file). It is
       meant to support network and transport level IPv6  to  IPv4  transition
       mechanisms, like NAT-PT and faith.
       If  the  nameserver  does  not return an IPv6 address for the forwarded
       AAAA/A6 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/A6
       record query.
       In  addition, totd treats PTR type queries (reverse name lookup) in the domain specially. If the query  matches  a  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.
       If  multiple  prefixed  are configured, totd will cycle through them in
       round-robin fashion. In this way totd can balance the load for multiple
       NAT-PT/faithd(8) translators in a network.


       To  enable  6to4  PTR query translation trick, add the ‘stf’ keyword to
       your  totd   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].IP 6.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].IP 6.ARPA
              label by issuing an NS query for {something}.I N-ADDR.ARPA.

                   If  the original query was for PTR records, and one or more
              NS  records  were  found  for  {something}.I  N-ADDR.ARPA,   the
              resolver   would   then   forward   the   original   query   for
              {something}.[x2002].IP 6.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}.I  N-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


       Totd  supports  re-writing  of scoped addresses in DNS responses.  This
       technique allows usage of scoped addresses like  site-local  addresses,
       without  having to maintain  such addresses in a DNS database. Instead,
       totd derives the scoped address record from the global  address  record
       it does find in DNS.

       Totd  only  performas  this  trick  on  queries  that  stay  within the
       specified scope. I.e. 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,  totd  attaches
       additional  AAAA  records  converted by using 3 arguments of the scoped

       When you configure as below in totd config file:

       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:   IN AAAA 3ffe:501:ffff::9876:5432

       it will get additional records as follows:   IN AAAA 3ffe:501:ffff::9876:5432   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.


       The Kame project provided network (NAT-PT) and transport (faithd) level
       translators    for    the    *BSD    operating    systems,   see   e.g. for more information.
       Another transport level translator is  ’The  Portable  Transport  Relay
       Translator  Daemon  (pTRTd)’  which  supports Linux amongst others, see

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

       and the following clickable image in particular:




       Feico Dillema <feico at>

       Thanks to 6Net (EU project IST-2001-32603),


       faithd(8) natptd(8) natptconfig(8) stf(4)