-*- text -*-

Router Advertisement DNS (radns)

This is a small program used for finding out one or more addresses to
resolving DNS servers. It listens for IPv6 Router Advertisements with
the Recursive DNS Server (RDNSS) option and stores the address(es) in
a file in the same syntax as resolv.conf(5). Currently, the default
file name is ./resolv.conf, but is configurable with -f <filename>.

A typical way to start radns from the command line would be, for
instance, this command as the root user:

  # ./radns -f /etc/resolv.conf

The program drops priveleges to a user called radns (specify another
user with -u username). The file /etc/resolv.conf must be writable by
this user. Please note that some other programs also might want to
modify the same file which might interfer with radns's operation. See
below on Dual Stack and DHCP.

The program optionally calls another program, usually a shell script,
to act on the information it receives. Specify the script with -s
<filename>.

Logs will be sent through syslog to the LOG_DAEMON facility. If you
want radns to run in the foreground and log to the terminal instead,
add -v for "verbosity". For even more verbosity, including hex dumps
of the received messages, repeat it, up to -v -v -v.

For radns to be useful, there must be a corresponding program on the
IPv6 router sending out Router Advertisements with the RDNSS
option. One such program is radvd:

  http://www.litech.org/radvd/

= Dual Stack and DHCP =

If you're on a dual stack machine that uses DHCP, chances are that the
/etc/resolv.conf file will be written to by your DHCP client.

If this is the case, there are numerous options.

* Given that you're running the ISC dhclient:

  1. Copy the dhclient-exit-hooks file in this directory to /etc/.

  2. Start radns with:
  
     # touch /etc/radns-resolv.conf
     # chown radns /etc/radns-resolv.conf
     # radns -f /etc/radns-resolv.conf
     
  This will make sure that the information dhclient receives about a
  resolving DNS server is merged with radns' information into
  /etc/resolv.conf. Note, though, that this will only happen when
  dhclient takes action, not when radns receives a Router
  Advertisment.

  NOTA BENE: At the moment radns will never remove radns-resolv.conf!
  This might interfer with normal operation. This will be fixed in a
  future release.

* If your DHCP client uses the resolvconf program:

  1. Make sure resolvconf's interface directory
     (/usr/local/etc/resolvconf/run/interfaces/ on FreeBSD) is
     writable by the radns user, by default 'radns'.

  2. Put the enclosed file 'radns-script' somewhere, for instance in
     /usr/local/bin.

  3. Start radns like this:

     # touch /etc/radns-resolv.conf
     # chown radns /etc/radns-resolv.conf     
     # radns -f /tmp/radns-resolv.conf -s /usr/local/bin/radns-script

= Development =

The latest version can usually be found here:

  http://hack.org/mc/hacks/radns/

There is a git repository here:

  http://hack.org/mc/git/radns/

If you think the early history looks funny, it's because the releases
(not every commit) were exported from Perforce and imported to CVS by
hand. Not much development was done in CVS and then everything was
migrated to git.
 
= Texts =

RFC 2460 Internet Protocol, Version 6 (IPv6) 
RFC 3971 SEcure Neighbor Discovery (SEND)
RFC 3972 Cryptographically Generated Addresses (CGA)
RFC 4861 Neighbor Discovery for IP version 6 (IPv6).
RFC 5006 IPv6 Router Advertisement Option for DNS Configuration

= Authors =

radns was originally written by Michael Cardell Widerkrantz (MC) in
2008 for Stickybit AB and has since been maintained by MC. David
Westlund provided patches and suggestions.

Contact: mc at the domain hack.org
