==== Recursive DNS serving ====

=== 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"


