Please read the file README.txt first; this file is the reference
manual for Deadwood and does not describe how to install the Deadwood
service.
NAME
Deadwood - A fully recursive caching DNS resolver
DESCRIPTION
Deadwood is a fully recursive DNS cache. This is a DNS server
with the following features:
* Full support for both DNS recursion and DNS forwarding
caching
* Small size and memory footprint suitable for embedded
systems
* Simple and clean codebase
* Secure design
* Spoof protection: Strong cryptography used to determine the
Query ID and source port
* Ability to read and write the cache to a file
* Dynamic cache that deletes entries not recently used
* Ability to use expired entries in the cache when it is
impossible to contact upstream DNS servers.
* Ipv6 support can be compiled in if desired
* Both DNS-over-UDP and DNS-over-TCP are handled by the same
daemon
* Built-in dnswall functionality
CONFIGURATION FILE FORMAT
The Deadwood configuration file, dwood3rc.txt, supports the following
parameters:
bind_address
This is the IP (or possibly IPv6) address we bind to.
cache_file
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.
chroot_dir
This is the directory the program will run from.
deliver_all
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.
dns_port
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
filter_rfc1918
When this is set to 1, RFC1918 (private) IP addresses are not
allowed to be in DNS replies. See http://crypto.stanford.edu/dns/
for why this improves security.
The default value for this is 1
handle_noreply
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.
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.
The default value for this is 1
handle_overload
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.
hash_magic_number
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.
ip_blacklist
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.
This parameter only accepts individual IPs, and does not use
netmasks.
max_ar_chain
Whether resource record rotation is enabled. If this has a
value of 1, resource record rotation is enabled, otherwise
resource record rotation is disabled.
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.
The reason for the unusual name for this variable is to retain
compatibility with MaraDNS mararc files.
The default value is 1: Resource record rotation enabled.
max_inflights
The maximum number of simultanious clients we process at the
same time for the same query.
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.
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.
The default value is 8.
maximum_cache_elements
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.
Each cache entry uses approximately four kilobytes of memory.
maxprocs
This is the maximum number of pending remote UDP connections
Deadwood can have. The default value for this is 32.
max_tcp_procs
This is the number of allowed open TCP connections. Default
value: 8
num_retries
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
random_seed_file
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).
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.
recurse_min_bind_port
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.
recurse_number_ports
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.
recursive_acl
This is a list of who is allowed to use Deadwood, in
"ip/mask" format. Mask must be a number between 0 and 32.
For example, "127.0.0.1/8" allows local connections.
reject_aaaa
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.
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.
This has a default value of 0. In other words, AAAA queries are
processed normally unless this is set.
reject_mx
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.
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.
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).
resurrections
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
root_servers
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.
tcp_listen
In order to enable DNS-over-TCP, this variable must be set and
have a value of 1. Default value: 0
timeout_seconds
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.
timeout_seconds_tcp
How long to wait on an idle TCP connection before dropping it.
The default value for this is 4, as in 4 seconds.
ttl_age
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.
If this has a value of 1, TTL entries are aged. Otherwise, they
are not. The default value for this is 1.
upstream_port
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.
upstream_servers
This is a list of DNS servers that the load balancer will try to
contact. This is a dictionary variable (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.
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.
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 ".".
Here is an example of upstream_servers:
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"
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.
Important: the domain name upstream_servers points to must end
in a "." character. This is OK:
upstream_servers["example.com."] = "192.168.42.1"
But this is not OK:
upstream_servers["example.com"] = "192.168.42.1"
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.
If neither root_servers nor upstream_servers are set, Deadwood
sets root_servers to use the default ICANN root servers, as
follows:
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)
This list is current as of May 3, 2010, and was last changed on
November 1, 2007.
verbose_level
This determines how many messages are logged on standard output;
larger values log more messages. The default value for this is
3.
ip/mask format of IPs
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).
The netmask is used to specify a range of IPs. The netmask is
a single number between 1 and 32, which indicates the number of
leading "1" bits in the netmask.
10.1.1.1/24 indicates that any ip from 10.1.1.0 to 10.1.1.255
will match.
10.2.3.4/16 indicates that any ip from 10.2.0.0 to 10.2.255.255
will match.
127.0.0.0/8 indicates that any ip with "127" as the first octet
(number) will match.
The netmask is optional, and, if not present, indicates that
only a single IP will match.
DNS over TCP
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.
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.
Parsing other files
It is possible to have Deadwood, while parsing the dwood3rc
file, read other files and parse them as if they were dwood3rc
files.
This is done using execfile. To use execfile, place a line like
this in the dwood3rc file:
execfile("path/to/filename")
Where path/to/filename is the path to the file to be parsed like
a dwood3rc file.
All files must be in or under the directory Deadwood is run from.
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.
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.
SECURITY
Deadwood is a program written with security in mind.
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).
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.
Note that Deadwood is not protected from someone on the same
network viewing packets sent by Deadwood and sending forged
packets as a reply.
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.
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.
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.
Example configuration file
Here is an example dwood3rc configuration file:
# 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"
BUGS
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.
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).
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.
LEGAL DISCLAIMER
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.
AUTHORS
Sam Trenholme (http://www.samiam.org) is responsible for this
program and reference.
