<HEAD>
<TH>DEADWOOD 1 "August 2009" DEADWOOD "Deadwood reference"</TH>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=utf-8">
</HEAD>
<BODY>
<h1>NAME</h1>
Deadwood - A fully recursive caching DNS resolver
<h1>DESCRIPTION</h1>
Deadwood is a fully recursive DNS cache. This is a DNS server with
the following features:
<ul>
<li>Full support for both DNS recursion and DNS forwarding caching
<li>Small size and memory footprint suitable for embedded systems
<li>Simple and clean codebase
<li>Secure design
<li>Spoof protection: Strong cryptography used to determine the Query ID
and source port
<li>Ability to read and write the cache to a file
<li>Dynamic cache that deletes entries not recently used
<li>Ability to use expired entries in the cache when it is impossible to
contact upstream DNS servers.
<li>Ipv6 support can be compiled in if desired
<li>Both DNS-over-UDP and DNS-over-TCP are handled by the same daemon
<li>Built-in dnswall functionality
</ul>
<h1>COMMAND LINE ARGUMENTS</h1>
Deadwood has a single optional command line argument: The location
of the configuration file that Deadwood uses, specified with the "-f" flag.
If this is not defined, Deadwood uses the file "/etc/dwood3rc" as the
configuration file.
<p>
In other words, invoking Deadwood as <b>Deadwood</b> will cause Deadwood to
use /etc/dwood3rc as the configuration file; invoking Deadwood as
<b>Deadwood -f foobar</b> will cause Deadwood to use the file "foobar"
in the current working directory (the directory one is in when
starting Deadwood) as the configuration file.
<h1>CONFIGURATION FILE FORMAT</h1>
The Deadwood configuration file supports the following parameters:
<h2>bind_address</h2>
This is the IP (or possibly IPv6) address we bind to.
<h2>cache_file</h2>
This is the filename of the file used for reading and
writing the cache to disk; this string can have lowercase letters,
the '-' symbol, the '_' symbol, and the '/' symbol (for putting
the cache in a subdirectory). All other symbols become a '_'
symbol.
<p>
This file is read and written as the user Deadwood runs as.
<h2>chroot_dir</h2>
This is the directory the program will run from.
<h2>deliver_all</h2>
This affects behavior in Deadwood 2.3, but has no effect in Deadwood 3.
This variable is only here so Deadwood 2 rc files can run in Deadwood 3.
<h2>dns_port</h2>
This is the port Deadwood binds to and listens on for
incoming connections. The default value for this is the standard DNS port:
port 53
<h2>filter_rfc1918</h2>
When this has a value of 1, a number of different IP ranges are not allowed
to be in DNS A replies:
<ul>
<li>192.168.x.x
<li>172.[16-31].x.x
<li>10.x.x.x
<li>127.x.x.x
<li>169.254.x.x
<li>224.x.x.x
<li>0.0.x.x
</ul>
If one of the above IPs is detected in a DNS reply, and filter_rfc1918 has
a value of 1, Deadwood will return a synthetic "this host does not reply"
response (a SOA record in the NS section) instead of the A record.
<p>
The reason for this is to provide a "dnswall" that protects users for some
kinds of attacks, as described at http://crypto.stanford.edu/dns/
<p>
Please note that Deadwood only provides IPv4 "dnswall" functionality and
does not help protect against IPv6 answers. If protection against certain
IPv6 AAAA records is needed, either disable all AAAA answers by setting
reject_aaaa to have a value of 1, or use an external program to filter
undesired IPv4 answers (such as the dnswall program).
<p>
The default value for this is 1
<h2>handle_noreply</h2>
When this is set to 0, Deadwood sends no reply
back to the client (when the client is a TCP client, Deadwood closes the
TCP connection) when a UDP query is sent upstream and the upstream DNS
never sends a reply.
<p>
When this is set to 1, Deadwood sends a SERVER FAIL
back to the client when a UDP query is sent upstream and the upstream DNS
never sends a reply.
<p>
The default value for this is 1
<h2>handle_overload</h2>
When this has a value of 0, Deadwood sends no reply when a UDP query is
sent and the server is overloaded (has too many pending connections);
when it has a value of 1, Deadwood sends a SERVER FAIL packet back to
the sender of the UDP query. The default value for this is 1.
<h2>hash_magic_number</h2>
This used to be used for Deadwood's internal hash generator to keep
the hash generator somewhat random and immune to certain types of attacks.
In Deadwood 3.0, entropy for the hash function is created by looking
at the contents of /dev/urandom (secret.txt on Windows machines) and the
current timestamp. This parameter is only here so older configuration
files do not break in Deadwood 3.0.
<h2>ip_blacklist</h2>
This is a list of IPs that we do not allow to be in the answer to a
DNS request. The reason for this is to counteract the practice some
ISPs have of converting a "this site does not exist" DNS answer in to
a page controlled by the ISP; this results in possible security issues.
<p>
This parameter only accepts individual IPs, and does not use netmasks.
<h2>maradns_uid</h2>
The user-id Deadwood runs as. This can be any number
between 10 and 65535; the default value is 99 (nobody on
RedHat-derived Linux distributions). This value is not
used on Windows systems.
<h2>maradns_gid</h2>
The group-id Deadwood runs as. This can be any
number between 10 and 65535; the default value is 99. This
value is not used on Windows systems.
<h2>max_ar_chain</h2>
Whether resource record rotation is enabled. If this has a value
of 1, resource record rotation is enabled, otherwise resource record
rotation is disabled.
<p>
Resource record rotation is usually desirable, since it allows DNS to
act like a crude load balancer. However, on heavily loaded systems it
may be desirable to disable it to reduce CPU usage.
<p>
The reason for the unusual name for this variable is to retain compatibility
with MaraDNS mararc files.
<p>
The default value is 1: Resource record rotation enabled.
<h2>max_inflights</h2>
The maximum number of simultanious clients we process at the same
time for the same query.
<p>
If, while processone a query for, say, "example.com.", another
DNS client sends to Deadwood another query for example.com, instead
of creating a new query to process example.com, Deadwood will
attach the new client to the same query that is already "in flight", and
send a reply to both clients once we have an answer for example.com.
<p>
This is the number of simultaneous clients a given query can have. If this
limit is exceeded, subsequents clients with the same query are refused until
an answer is found. If this has a value of 1, we do not merge multiple
requests for the same query, but give each request its own connection.
<p>
The default value is 8.
<h2>maximum_cache_elements</h2>
The maximum number of elements our cache
is allowed to have. This is a number between 32 and 16,777,216;
the default value for this is 1024. Note that, if writing the
cache to disk or reading the cache from disk, higher values of
this will slow down cache reading/writing.
<p>
The amount of memory each cache entry uses is variable depending on the
operating system used and the size of memory allocation pages assigned.
In Windows XP, for example, each entry uses approximately four kilobytes
of memory and Deadwood has an overhead of approximately 512 kilobytes.
So, if there are 512 cache elements, Deadwood uses approximately 2.5
megabytes of memory, and if there are 1024 cache elements, Deadwood uses
approximately 4.5 megabytes of memory. Again, these numbers are for
Windows XP and other operating systems will have different memory allocation
numbers.
<h2>maxprocs</h2>
This is the maximum number of pending remote UDP connections
Deadwood can have. The default value for this is 32.
<h2>max_tcp_procs</h2>
This is the number of allowed open TCP connections. Default value: 8
<h2>num_retries</h2>
The number of times we retry to send a query upstream
before giving up. If this is 0, we only try once; if this is 1,
we try twice, and so on, up to 8 retries. Note that each retry
takes timeout_seconds seconds before we retry again. Default
value: 2
<h2>ns_glueless_type</h2>
The RR type we send to resolve glueless records. This should be
1 (A) when mainly using IPv4 to resolve records. If glueless NS records
have AAAA but not A records, and IPv6 is enabled, it may make sense to
give this a value of 255 (ANY). If IPv4 ever stops being used on a large
scale, it may eventually become possible to make this have a value of
28 (AAAA).<p>
The default value is 1: An A (IPv4 IP) record. This parameter has <b>not</b>
been tested; use at your own risk.
<h2>random_seed_file</h2>
This is a file that contains random numbers, and
is used as a seed for the cryptographically strong random number generator.
Deadwood will try to read 256 bytes from this file (the RNG Deadwood uses can
accept a stream of any arbitrary length).
<p>
Note that the hash compression function obtains some of its entropy before
parsing the mararc file, and is hard-coded to get entropy from /dev/urandom
(secret.txt on Windows systems). Most other entropy used by Deadwood
comes from the file pointed to by random_seed_file.
<h2>recurse_min_bind_port</h2>
The lowest numbered port Deadwood is
allowed to bind to; this is a random port number used for the source
port of outgoing queries, and is not 53 (see dns_port above). This
is a number between 1025 and 32767, and has a default value of 15000.
This is used to make DNS spoofing attacks more difficult.
<h2>recurse_number_ports</h2>
The number of ports Deadwood binds to for the source port for
outgoing connections; this is a power of 2 between 256 and 32768.
This is used to make DNS spoofing attacks more difficult. The default
value is 4096.
<h2>recursive_acl</h2>
This is a list of who is allowed to use Deadwood to perform DNS recursion,
in "ip/mask" format. Mask must be a number between
0 and 32 (for IPv6, between 0 and 128). For example, "127.0.0.1/8"
allows local connections.
<h2>reject_aaaa</h2>
If this has a value of 1, a bogus SOA "not there" reply is sent whenever
an AAAA query is sent to Deadwood. In other words, every time a program asks
Deadwood for an IPv6 IP address, instead of trying to process the request,
when this is set to 1, Deadwood pretends the host name in question does not
have an IPv6 address.
<p>
This is useful for people who aren't using IPv6 but use applications (usually
*NIX command like applications like "telnet") which slow things down trying
to find an IPv6 address.
<p>
This has a default value of 0. In other words, AAAA queries are processed
normally unless this is set.
<h2>reject_mx</h2>
When this has the default value of 1, MX queries are silently dropped
with their IP logged. A MX query is a query that is only done by a
machine if it wishes to be its own mail server sending mail to machines
on the internet. This is a query an average desktop machine (including
one that uses Outlook or another mail user agent to read and send email)
will never make.
<p>
Most likely, if a machine is trying to make a MX query, the machine is
being controlled by a remote source to send out undesired "spam" email.
This in mind, Deadwood will not allow MX queries to be made unless
reject_mx is explicitly set with a value of 0.
<p>
Before disabling this, please keep in mind that Deadwood is optimized
to be used for web surfing, not as a DNS server for a mail hub.
In particular, the IPs for MX records are removed from Deadwood's
replies and Deadwood needs to perform additional DNS queries to get the
IPs corresponding to MX records, and Deadwood's testing is more geared
for web surfing (almost 100% A record lookup) and not for mail delivery
(extensive MX record lookup).
<h2>resurrections</h2>
If this is set to 1, Deadwood will try to send an
expired record to the user before giving up. If it is 0, we
don't. Default value: 1
<h2>root_servers</h2>
This is a list of root servers; its syntax is identical to
upstream_servers (see below). This is the type of DNS service
ICANN, for example, runs. These are servers used that do
not give us complete answers to DNS questions, but merely tell
us which DNS servers to connect to to get an answer closer to
our desired answer.
<h2>tcp_listen</h2>
In order to enable DNS-over-TCP, this variable must be set and have
a value of 1. Default value: 0
<h2>timeout_seconds</h2>
This is how long Deadwood will wait before giving
up and discarding a pending UDP DNS reply.
The default value for this is 2, as in 2 seconds.
<h2>timeout_seconds_tcp</h2>
How long to wait on an idle TCP connection before
dropping it. The default value for this is 4, as in 4 seconds.
<h2>ttl_age</h2>
Whether TTL aging is enabled; whether entries in the cache have their
TTLs set to be the amount of time the entries have left in the cache.
<p>
If this has a value of 1, TTL entries are aged. Otherwise, they are not.
The default value for this is 1.
<h2>upstream_port</h2>
This is the port Deadwood uses to connect or send packets to the
upstream servers. The default value for this is 53; the standard
DNS port.
<h2>upstream_servers</h2>
This is a list of DNS servers that the load balancer will try to contact.
This is a <i>dictionary variable</i> (array indexed by a string instead of
by a number) instead of a simple variable. Since upstream_servers
is a dictionary variable, it needs to be initialized before being used.
<p>
Deadwood will look at the name of the host that it is trying to find
the upstream server for, and will match against the longest suffix it
can find.
<p>
For example, if someone sends a query for "www.foo.example.com" to
Deadwood, Deadwood will first see if there is an upstream_servers
variable for "www.foo.example.com.", then look for "foo.example.com.",
then look for "example.com.", then "com.", and finally ".".
<p>
Here is an example of upstream_servers:
<pre>
upstream_servers = {} # Initialize dictionary variable
upstream_servers["foo.example.com."] = "192.168.42.1"
upstream_servers["example.com."] = "192.168.99.254"
upstream_servers["."] = "10.1.2.3, 10.1.2.4"
</pre>
In this example, anything ending in "foo.example.com" is resolved
by the DNS server at 192.168.42.1; anything else ending in "example.com"
is resolved by 192.168.99.254; and anything not ending in "example.com"
is resolved by either 10.1.2.3 or 10.1.2.4.
<p>
<b>Important:</b> the domain name upstream_servers points to must end in
a "." character. This is OK:
<pre>
upstream_servers["example.com."] = "192.168.42.1"
</pre>
But this is <b>not</b> OK:
<pre>
upstream_servers["example.com"] = "192.168.42.1"
</pre>
The reason for this is because BIND engages in unexpected behavior
when a host name deoesn't end in a dot, and by forcing a dot at the end
of a hostname, Deadwood doesn't have to guess whether the user wants
BIND's behavior or the "normal" behavior.
<p>
If neither root_servers nor upstream_servers are set, Deadwood sets
root_servers to use the default ICANN root servers, as follows:
<p>
<pre>
198.41.0.4 a.root-servers.net (VeriSign)
192.228.79.201 b.root-servers.net (ISI)
192.33.4.12 c.root-servers.net (Cogent)
128.8.10.90 d.root-servers.net (UMaryland)
192.203.230.10 e.root-servers.net (NASA Ames)
192.5.5.241 f.root-servers.net (ISC)
192.112.36.4 g.root-servers.net (DOD NIC)
128.63.2.53 h.root-servers.net (ArmyRU)
192.36.148.17 i.root-servers.net (NORDUnet)
192.58.128.30 j.root-servers.net (VeriSign)
193.0.14.129 k.root-servers.net (Reseaux)
199.7.83.42 l.root-servers.net (IANA)
202.12.27.33 m.root-servers.net (WIDE)
</pre>
This list is current as of May 3, 2010, and was last changed on
November 1, 2007.
<h2>verbose_level</h2>
This determines how many messages are logged on standard output; larger
values log more messages. The default value for this is 3.
<h1>ip/mask format of IPs</h1>
Deadwood uses a standard ip/netmask formats to specify IPs.
An ip is in dotted-decimal format, e.g. "10.1.2.3" (or in ipv6
format when ipv6 support is compiled in).
<p>
The netmask is used to specify a range of IPs.
The netmask is a single number between
1 and 32 (128 when ipv6 support is compiled in), which indicates the
number of leading "1" bits in the netmask.
<p>
<b>10.1.1.1/24</b> indicates that any ip from 10.1.1.0 to 10.1.1.255
will match.
<p>
<b>10.2.3.4/16</b> indicates that any ip from 10.2.0.0 to 10.2.255.255
will match.
<p>
<b>127.0.0.0/8</b> indicates that any ip with "127" as the first
octet (number) will match.
<p>
The netmask is optional, and, if not present, indicates that only
a single IP will match.
<h1>DNS over TCP</h1>
Deadwood has support for both DNS-over-UDP and DNS-over-TCP; the same
daemon listens on both the UDP and TCP DNS port. DNS-over-TCP must
be explicitly enabled by setting tcp_listen to 1.
<p>
Only UDP DNS queries are cached. Deadwood does not support caching
over TCP; it handles TCP to resolve the occasional truncated reply or
handle the occasional non-RFC-compliant TCP-only DNS resolver.
<h1>Parsing other files</h1>
It is possible to have Deadwood, while parsing the dwood3rc file, read
other files and parse them as if they were dwood3rc files.
<p>
This is done using <b>execfile</b>. To use execfile, place a line like
this in the dwood3rc file:
<p>
execfile("path/to/filename")
<p>
Where path/to/filename is the path to the file to be parsed like a
dwood3rc file.
<p>
All files must be in or under the directory /etc/deadwood/execfile.
Filenames can only have lower-case letters and the underscore
character ("_"). Absolute paths are not allowed as the argument to
execfile; the filename can not start with a slash ("/") character.
<p>
If there is a parse error in the file pointed to by execfile, Deadwood
will report the error as being on the line with the execfile command in
the main dwood3rc file. To find where a parse error is in the sub-file,
use something like "Deadwood -f /etc/deadwood/execfile/filename"
to find the parse error in the offending file, where "filename" is the file
to to parsed via execfile.
<h1>IPV6 support</h1>
This server can also be optionally compiled to have IPv6 support. In order
to enable IPv6 support, add '-DIPV6' to the compile-time flags. For
example, to compile this to make a small binary, and to have ipv6 support:
<pre>
export FLAGS='-Os -DIPV6'
make
</pre>
<h1>SECURITY</h1>
Deadwood is a program written with security in mind.
<p>
In addition to use a buffer-overflow resistant string library and a coding
style and SQA process that checks for buffer overflows and memory leaks,
Deadwood uses a strong pseudo-random number generator (The 32-bit version
of RadioGatun) to generate both the query ID and source port. For the
random number generator to be secure, Deadwood needs a good source of
entropy; by default Deadwood will use /dev/urandom to get this entropy.
If you are on a system without /dev/urandom support, it is important
to make sure that Deadwood has a good source of entropy so that the query
ID and source port are hard to guess (otherwise it is possible to forge
DNS packets).
<p>
The Windows port of Deadwood includes a program called
"mkSecretTxt.exe" that creates a 64-byte (512 bit) random file called
"secret.txt" that can be used by Deadwood (via the "random_seed_file"
parameter); Deadwood also gets entropy from the timestamp
when Deadwood is started and Deadwood's process ID number, so it is
same to use the same static secret.txt file as the random_seed_file
for multiple invocations of Deadwood.
<p>
Note that Deadwood is not protected from someone on the same network viewing
packets sent by Deadwood and sending forged packets as a reply.
<p>
To protect Deadwood from certain possible denial-of-service attacks, it is
best if Deadwood's prime number used for hashing elements in the cache is
a random 31-bit prime number. The program RandomPrime.c generates a
random prime that is placed in the file DwRandPrime.h that is regenerated
whenever either the program is compiled or things are cleaned up with
make clean. This program uses /dev/urandom for its entropy; the file
DwRandPrime.h will not be regenerated on systems without /dev/urandom.
<p>
On systems without direct /dev/urandom support, it is suggested to see if
there is a possible way to give the system a working /dev/urandom. This
way, when Deadwood is compiled, the hash magic number will be suitably
random.
<p>
If using a precompiled binary of Deadwood, please ensure that the system
has /dev/urandom support (on Windows system, please ensure that the
file with the name secret.txt is generated by the included mkSecretTxt.exe
program); Deadwood, at runtime, uses /dev/urandom (secret.txt in Windows)
as a hardcoded path to get entropy (along with the timestamp) for the
hash algorithm.
<h1>DAEMONIZATION</h1>
Deadwood does not have any built-in daemonization facilities; this is
handled by the external program Duende or any other daemonizer.
<h1>Example configuration file</h1>
Here is an example dwood3rc configuration file:
<pre>
# This is an example deadwood rc file
# Note that comments are started by the hash symbol
bind_address="127.0.0.1" # IP we bind to
# The following line is disabled by being commented out
#bind_address="::1" # We have optional IPv6 support
# Directory we run program from (not used in Win32)
chroot_dir = "/etc/deadwood"
# The following upstream DNS servers are Google's
# (as of December 2009) public DNS servers. For
# more information, see the page at
# http://code.google.com/speed/public-dns/
#
# If neither root_servers nor upstream_servers are set,
# Deadwood will use the default ICANN root servers.
#upstream_servers = {}
#upstream_servers["."]="8.8.8.8, 8.8.4.4"
# Who is allowed to use the cache. This line
# allows anyone with "127.0" as the first two
# digits of their IP to use Deadwood
recursive_acl = "127.0.0.1/16"
# Maximum number of pending requests
maxprocs = 8
# Send SERVER FAIL when overloaded
handle_overload = 1
maradns_uid = 99 # UID Deadwood runs as
maradns_gid = 99 # GID Deadwood runs as
maximum_cache_elements = 60000
# If you want to read and write the cache from disk,
# make sure chroot_dir above is readable and writable
# by the maradns_uid/gid above, and uncomment the
# following line.
#cache_file = "dw_cache"
# If your upstream DNS server converts "not there" DNS replies
# in to IPs, this parameter allows Deadwood to convert any reply
# with a given IP back in to a "not there" IP. If any of the IPs
# listed below are in a DNS answer, Deadwood converts the answer
# in to a "not there"
#ip_blacklist = "10.222.33.44, 10.222.3.55"
</pre>
<h1>BUGS</h1>
DNS-over-TCP needs to be explicitly enabled. Note that DNS-over-TCP is
almost never used. Also,
Deadwood does not cache DNS packets larger than 512 bytes in size that
need to be sent using TCP. In addition, DNS-over-TCP packets which
are "incomplete" DNS replies (replies which a stub resolver can not use,
namely either a NS referral or an incomplete CNAME reply) are not
handled correctly by Deadwood. Again, DNS-over-TCP is very rare.
<p>
Deadwood can not process DNS resource record types with numbers between
65392 and 65407. These RR types are marked by the IANA for "private use";
Deadwood reserves these record types for internal use. This is only 16
record types out of the 65536 possible DNS record types (only 71 have
actually been assigned by IANA, so this is a non-issue in the real world).
<p>
It is not clear whether the DNS RFCs allow ASCII control characters
in DNS names. Even if they were, Deadwood does not allow ASCII
control characters (bytes with a value less then 32) in DNS names.
Other characters (UTF-8, etc.) are allowed.
<h1>LEGAL DISCLAIMER</h1>
THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
<h1>AUTHORS</h1>
Sam Trenholme (<A href=http://www.samiam.org/>http://www.samiam.org</a>) is
responsible for this program and man page. He appreciates all of
Jean-Jacques Sarton's help giving this program Ipv6 support.
</BODY>
