<HEAD><TITLE>Recursive DNS serving</TITLE>

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">

</HEAD><BODY>

<!-- Copyright 2005-2010 Sam Trenholme

    TERMS

    Redistribution and use, with or without modification, are permitted 
    provided that the following condition is met:

    1. Redistributions must retain the above copyright notice, this 
       list of conditions and the following disclaimer.

    This documentation is provided 'as is' with no guarantees of 
    correctness or fitness for purpose.

 -->

<H1>Using Deadwood as a recursive DNS server</H1>

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 <A 
href=compile.html>compiled and installed</A>.

<A name=toc>
<H2>Table of contents</H2>
</A>

<ul>
<li><A href=#basic>Basic configuration</A>
<li><A href=#slow>Using Deadwood on a slow network</A>
<li><A href=#upstream>Using other recursive DNS servers</A>
<li><A href=#otherroot>Using different root servers</A>
<li><A href=#private>Having private host names</A>
<li><A href=#privateauth>Using authoritative records for private names</A>
<li><A href=#privateroot>Private names with custom root servers</A>
<li><A href=#custom>Customizing the resolution of some names</A>
</ul>

<A name=basic>
<H2>Basic configuration</H2>
</A>

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

<pre>
ipv4_bind_addresses = "127.0.0.1"
chroot_dir = "/etc/maradns"
recursive_acl = "127.0.0.1"
</pre>

<p>
This three-line file needs to be called <tt>/etc/dwood3rc</tt>.

<p>
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.  

<p>
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.

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

<pre>
ipv4_bind_addresses = "10.1.3.2, 192.168.0.1, 127.0.0.1"
</pre>

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

<p>

The third line, <tt>recursive_acl</tt>, 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.<i>any</i> be allowed to make
recursive queries:

<pre>
recursive_acl = "<b>192.168.1.0/24</b>"</tt>
</pre>

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

<p>
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 
<tt>/etc/resolv.conf</tt>.

<A name=slow>
<h2>Using Deadwood on a slow network</h2></A>

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 <tt>timeout_seconds</tt> value.

<p>

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

<pre>
ipv4_bind_addresses = "127.0.0.1"
chroot_dir = "/etc/maradns"
recursive_acl = "127.0.0.1"
timeout_seconds = 6
</pre>

<!-- Guess what?  All of the supported OSes that MaraDNS compiled on,
     with the exception of the mingw32 semi-port (which has its own
     workaround), have /dev/urandom support.  So we don't need to tell
     people how to set up a random_seed_file in the tutorial. 
  
     Good thing I wrote mkSecretTxt for Deadwood in Windows to have
     a good source of random numbers

     DOC HERE: Use mkSecretTxt.exe to make secret.txt in Windows 
-->

<A name=upstream>
<h2>Using other recursive DNS servers</h2> 
</A>

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 <tt>upstream_servers</tt> in the dwood3rc file.

<p>

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:

<pre>
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"
</pre>

<A name=otherroot>
<h2>Using different root servers</h2></A>

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.

<p>

It is possible, however, to change the root DNS servers used by setting the
<tt>root_servers</tt> 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:

<pre>
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"
</pre>

This file will do the exact same thing as the following <tt>mararc</tt> file:

<pre>
ipv4_bind_addresses = "127.0.0.1"
chroot_dir = "/etc/maradns"
recursive_acl = "127.0.0.1"
</pre>

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

<A name="privateroot"> 
<h2>Private names with custom root servers</h2>
</A>

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 
<tt>office</tt> by having a line like this in one's mararc file:

<pre>
root_servers["office."] = "192.168.0.7"
</pre>

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

<pre>
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"
</pre>

And the configuration on 192.168.0.7, the MaraDNS authoritative server:

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

</BODY>
