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.
This in mind, whitespace is significant; Deadwood parameters must be in the leftmost column with no leading whitespace. This is a valid line (as long as there are no spaces to its left):
recursive_acl = "127.0.0.1/16"The following line, however, will raise a parse error:
recursive_acl = "127.0.0.1/16"Observe the space to the left of the "recusive_acl" string in the incorrectly formatted line.
filter_rfc1918 = 0If a numeric parameter is surrounded by quotes, the error message "Unknown dwood3rc string parameter" will appear.
bind_address = "127.0.0.1"
upstream_servers = {}
upstream_servers["."]="8.8.8.8, 8.8.4.4"
This file is read and written as the user Deadwood runs as.
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/
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).
The default value for this is 1
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
This parameter only accepts individual IPs, and does not use netmasks.
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.
If, while processing 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.
This is the longest we will keep an entry cached. The default value for this parameter is 86400 (one day); the minimum value is 300 (5 minutes) and the maximum value this can have is 7776000 (90 days).
The reason why this parameter is here is to protect Deadwood from attacks which exploit there being stale data in the cache, such as the "Ghost Domain Names" attack.
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.
Please note that each root_servers and upstream_servers entry takes up space in Deadwood's cache and that maximum_cache_elements will need to be increased to store a large number of these entries.
The default value is 1: An A (IPv4 IP) record. This parameter has not been tested; use at your own risk.
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.
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.
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).
This is useful for people who are getting slow DNS timeouts when trying to perform a reverse DNS lookups on IPs.
This has a default value of 0. In other words, PTR queries are processed normally unless this is set.
Please note that each root_servers entry takes up space in Deadwood's cache and that maximum_cache_elements will need to be increased to store a large number of these entries.
If this has a value of 1, TTL entries are aged. Otherwise, they are not. The default value for this is 1.
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 doesn'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) 199.7.91.13 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.
Please note that each upstream_servers entry takes up space in Deadwood's cache and that maximum_cache_elements will need to be increased to store a large number of these entries.
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.
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.
Deadwood extracts useful information from UDP DNS packets marked truncated which almost always removes the need to have DNS-over-TCP. However, 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, which can be either a NS referral or an incomplete CNAME reply) are not handled correctly by Deadwood.
Deadwood has support for both DNS-over-UDP and DNS-over-TCP; the same daemon listens on both the UDP and TCP DNS port.
Only UDP DNS queries are cached. Deadwood does not support caching over TCP; it handles TCP to resolve the rare truncated reply without any useful information or to work with very uncommon non-RFC-compliant TCP-only DNS resolvers. In the real world, DNS-over-TCP is almost never used.
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 /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.
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.
export FLAGS='-Os -DIPV6' make
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.
# 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"
# By default, for security reasons, Deadwood does not allow IPs in
# the 192.168.x.x, 172.[16-31].x.x, 10.x.x.x, 127.x.x.x,
# 169.254.x.x, 224.x.x.x, or 0.0.x.x range. If using Deadwood
# to resolve names on an internal network, uncomment the
# following line:
#filter_rfc1918 = 0
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.