               Using Deadwood as a recursive DNS server

   This document is a step-by-step guide to setting up Deadwood as
   a recursive DNS server. It assumes that MaraDNS and Deadwood are
   already compiled and installed.

Table of contents

     * Basic configuration
     * Using Deadwood on a slow network
     * Using other recursive DNS servers
     * Using different root servers
     * Having private host names
     * Using authoritative records for private names
     * Private names with custom root servers
     * Customizing the resolution of some names

Basic configuration

   Once Deadwood is installed, the dwood3rc file needs to be set up
   before Deadwood will function as a recursive DNS server. This
   file only needs to be three lines long:

 ipv4_bind_addresses = "127.0.0.1"
 chroot_dir = "/etc/maradns"
 recursive_acl = "127.0.0.1"

   This three-line file needs to be called /etc/dwood3rc.

   The first line is the IP address or addresses Deadwood will use.
   Here, it has the address 127.0.0.1, which means that only the
   machine running Deadwood will be able to access the MaraDNS
   server--other machines will not be able to see it.

   If the machine running Deadwood will be accessed by other
   machines, this IP needs to be changed to an IP that the machine
   running Deadwood has.

   It is possible to have Deadwood run on multiple IP addresses:

 ipv4_bind_addresses = "10.1.3.2, 192.168.0.1, 127.0.0.1"

   The second line, chroot_dir is the directory Deadwood will be
   run from. This just has to be an empty directory, ideally owned
   by the root user.

   The third line, recursive_acl, determines the range of IPs that
   can access the recursive DNS server. This is in IP/netmask
   format. For example, if one has an office which uses IPs in the
   form 192.168.1.1, 192.168.1.2, etc., and wishes to have only
   192.168.1.any be allowed to make recursive queries:

 recursive_acl = "192.168.1.0/24"

   Here the "/24" indicates that we ignore the fourth number in an
   IP when determining who can contact Deadwood.

   Once this is done, other machines can contact the Deadwood
   server to perform DNS queries. For example, Deadwood is now a
   DNS server which Windows 98 can use in "Control Panel -> Network
   -> TCP/IP -> DNS configuration", or a UNIX system can point to
   from /etc/resolv.conf.

Using Deadwood on a slow network

   Deadwood, on a slow network, may time out. Deadwood normally
   only waits two seconds for a reply from a remote DNS server.
   This is not enough time to process queries on some slow
   networks. This can be changed by increasing the timeout_seconds
   value.

   Here is a mararc file which waits six seconds (instead of the
   default two) for a reply from a remote DNS server:

 ipv4_bind_addresses = "127.0.0.1"
 chroot_dir = "/etc/maradns"
 recursive_acl = "127.0.0.1"
 timeout_seconds = 6

Using other recursive DNS servers

   It is possible to have Deadwood contact other recursive name
   servers, instead of contacting the actual root servers to
   process recursive queries by using the variable upstream_servers
   in the dwood3rc file.

   In other words, one can use one's, say, ISP's DNS servers to
   resolve the names, and have MaraDNS act as a cache for the ISP's
   DNS servers. Supposing that the ISP name servers have the IPs
   10.66.77.88 and 10.99.11.22, the dwood3rc file will look like
   this:

 ipv4_bind_addresses = "127.0.0.1"
 chroot_dir = "/etc/maradns"
 recursive_acl = "127.0.0.1"
 upstream_servers = {}
 upstream_servers["."] = "10.66.77.88, 10.99.11.22"

Using different root servers

   Deadwood, by default, uses the ICANN name servers as the root
   name servers. The reason for this default is practical: In my
   experience, the ICANN root name servers are the ones which least
   frequently change their IP addresses. They are the best name
   servers for simple "set and forget" recursive environments.

   It is possible, however, to change the root DNS servers used by
   setting the root_servers variable in the mararc file. Here is
   what such a recursive configuration (this example uses the ICANN
   root servers; change this example to use another set of root
   servers as needed) looks like:

 ipv4_bind_addresses = "127.0.0.1"
 chroot_dir = "/etc/maradns"
 recursive_acl = "127.0.0.1"
 root_servers = {}
 root_servers["."] = "198.41.0.4,"
 root_servers["."] += "192.228.79.201,"
 root_servers["."] += "192.33.4.12,"
 root_servers["."] += "128.8.10.90,"
 root_servers["."] += "192.203.230.10,"
 root_servers["."] += "192.5.5.241,"
 root_servers["."] += "192.112.36.4,"
 root_servers["."] += "128.63.2.53,"
 root_servers["."] += "192.36.148.17,"
 root_servers["."] += "192.58.128.30,"
 root_servers["."] += "193.0.14.129,"
 root_servers["."] += "199.7.83.42,"
 root_servers["."] += "202.12.27.33"

   This file will do the exact same thing as the following mararc
   file:

 ipv4_bind_addresses = "127.0.0.1"
 chroot_dir = "/etc/maradns"
 recursive_acl = "127.0.0.1"

   The ICANN servers listed above are the ones that Deadwood use
   when no root servers are specified.

Private names with custom root servers

   Deadwood can have custom root name servers that only resolve
   names in a subtree of the DNS space. In other words, we can tell
   Deadwood to have 192.168.0.7 resolve all names ending in office
   by having a line like this in one's mararc file:

 root_servers["office."] = "192.168.0.7"

   Here is how a configuration may look on 192.168.0.1, the
   recursive server:

 ipv4_bind_addresses = "192.168.0.1"
 chroot_dir = "/etc/maradns"
 recursive_acl = "192.168.0.0/24"
 root_servers = {}
 root_servers["office."] = "192.168.0.7"
 root_servers["."] = "198.41.0.4,"
 root_servers["."] += "192.228.79.201,"
 root_servers["."] += "192.33.4.12,"
 root_servers["."] += "128.8.10.90,"
 root_servers["."] += "192.203.230.10,"
 root_servers["."] += "192.5.5.241,"
 root_servers["."] += "192.112.36.4,"
 root_servers["."] += "128.63.2.53,"
 root_servers["."] += "192.36.148.17,"
 root_servers["."] += "192.58.128.30,"
 root_servers["."] += "193.0.14.129,"
 root_servers["."] += "199.7.83.42,"
 root_servers["."] += "202.12.27.33"

   And the configuration on 192.168.0.7, the MaraDNS authoritative
   server:

 ipv4_bind_addresses = "192.168.0.7"
 chroot_dir = "/etc/maradns"
 csv2 = {}
 csv2["office."] = "db.office"
