NAME

DESCRIPTION

*

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

COMMAND LINE ARGUMENTS

In other words, invoking Deadwood as Deadwood will cause Deadwood to use /etc/dwood3rc as the configuration file; invoking Deadwood as Deadwood -f foobar 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.

CONFIGURATION FILE FORMAT

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

Some upstream DNS servers violate the RFCs and send "name error" DNS packets without a SOA record in the NS section of the reply. Deadwood used to discard such packets; Deadwood now passes such packets on to the client without caching them.

Should the old behavior of discarding these packets is desired, set this to 0 with "deliver_all=0" in the dwood3rc file.

The default value for this is 1

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 is a large 31-bit prime number that the hash compression function uses; use the RandomPrime C program to generate a suitable random prime for this function. This number should be secret; its default value changes for every release of Deadwood.

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.

maradns_uid

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.

maradns_gid

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.

max_ar_chain

Whether resource record rotation is enabled. This 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 to disbale 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.

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

ns_glueless_type

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

The default value is 1: An A (IPv4 IP) record.

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

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 the load balancer, 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.

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.

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

The netmask is used to specify a range of IPs. The netmask can be in one of two formats: 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, or a 4-digit dotted-decimal netmask.

10.1.1.1/24 indicates that any ip from 10.1.1.0 to 10.1.1.255 will match.

10.1.1.1/255.255.255.0 is identical to 10.1.1.1/24

10.2.3.4/16 indicates that any ip from 10.2.0.0 to 10.2.255.255 will match.

10.2.3.4/255.255.0.0 is identical to 10.2.3.4/16

127.0.0.0/8 indicates that any ip with "127" as the first octet (number) will match.

127.0.0.0/255.0.0.0 is identical to 127.0.0.0/8

The netmask is optional, and, if not present, indicates that only a single IP will match.

DNS over TCP

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

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 /usr/local/etc/maradns/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.

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 /usr/local/etc/maradns/execfile/filename" to find the parse error in the offending file, where "filename" is the file to to parsed via execfile.

IPV6 support

	export FLAGS='-Os -DIPV6'
	make

SECURITY

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 Radio Gatun) 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).

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, or if using a system where it is not feasible to add /dev/urandom support, one can use another system to generate a 31-bit random prime (perhaps using a different system with /dev/urandom support), then use the hash_magic_number parameter to have Deadwood use this random prime number.

DAEMONIZATION

Example 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 = "/usr/local/etc/maradns" 
# The following upstream DNS servers are Google's 
# newly-announced (as of December 2009) public DNS 
# servers.  For more information, see the page at
# http://code.google.com/speed/public-dns/
#
# These IPs can be changed to the IPs of any recursive 
# DNS servers that can be reached from the computer 
# running Deadwood, such as your ISP's DNS 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 = 53 # UID Deadwood runs as
maradns_gid = 53 # 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

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

AUTHORS