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.

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: