totd(8) net totd(8)NAMEtotd - DNS proxy and translator for IPv6 and IPv4
SYNTAXtotd [-6] [-no6] [-4] [-no4] [-64] [-d<n>] [-p <prefix>] [-c <config‐
file>] [-u <user>] [-g <group>] [-t <dir>] [-q] [-v] [-h]
DESCRIPTION
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.
CONFIGURATION
Totd can be configured using commandline options, via its configuration
file or even dynamically via HTTP requests (only if support for this
has been added at compile time).
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::'.
allow <IP addresstring>
Specifies an (IPv4 or IPv6) address of a machine that is allowed
to make http requests to totd.
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 sock‐
ets 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 rewrit‐
ing is not supported for wildcard sockets.
OPTIONS
-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
http-port <port number>
Specifies a different port than the default (6464) to listen on
for http requests. Note that http support is optional and needs
to be compiled in.
-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 mes‐
sages.
HTTP REQUESTS
When support for it is compiled into totd and totd is started with the
http-port commandline option, the following URLs can be requested from
totd (at the specified port, say 6464):
http://localhost:6464/index.html
http://localhost:6464/add_prefix?prefix=3ffe:abcd:1234:9876::
http://localhost:6464/del_prefix?prefix=3ffe:abcd:1234:9876::
Of course, you choose your own values for the prefix to add or delete.
Note that if your network can not be considered secure, it may be
appropriate to let totd only listen to localhost for http requests (and
use ssh-tunneling for remote access)? Basic http authentication could
easily be supported, but we do not see much value in that. HTTPS sup‐
port is more complicated and I currently do not believe it adds much
over using ssh.
FORWARDING
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 for‐
warders specified, it will use them in the order listed. When a name‐
server 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.)
ADDRESS TRANSLATION TRICK
Totd can treat each AAAA and A6 type query in a special way. This be‐
haviour 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
ip6.int. 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.
6TO4 PTR RECORDS
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 forward‐
ing 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 {some‐
thing}.[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
records.
SCOPED ADDRESSES
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 speci‐
fied 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 addi‐
tional AAAA records converted by using 3 arguments of the scoped key‐
word.
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:
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.
EXAMPLES
The Kame project provided network (NAT-PT) and transport (faithd) level
translators for the *BSD operating systems, see e.g.
http://www.kame.net for more information.
Another transport level translator is 'The Portable Transport Relay
Translator Daemon (pTRTd)' which supports Linux amongst others, see
http://v6web.litech.org/ptrtd/
FILES
PREFIX/etc/totd.conf
AUTHOR
Feike W. Dillema <feico at pasta.cs.uit.no>
Thanks to 6Net (EU project IST-2001-32603), http://www.6net.org/
SEE ALSOfaithd(8)natptd(8)natptconfig(8)stf(4)Feike W. Dillema 1.5 totd(8)
