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 non-recursive caching DNS resolver

                             DESCRIPTION

   Deadwood is a working DNS forwarding cache. This is a 
   server with the following features:

     * Small size and memory footprint 
     * 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.

                      CONFIGURATION FILE FORMAT

   The Deadwood configuration file 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

   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 dwood2rc 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

handle_noreply

   When this is set to 0, Deadwood sends no reply back to the
   client with a UDP query is sent and the upstream DNS never sends
   a reply.

   When this is set to 1, Deadwood sends a SERVER FAIL back to the
   client with a UDP query is sent 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.

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.

max_tcp_procs

   This is the number of allowed open TCP connections. Default
   value: 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 connections
   Deadwood can have. The default value for this is 32. With 
   DeadwoodTCP, this is the number of allowed open TCP 
   connections.

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: 1

random_seed_file

   This is a file that should contain random data, 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.

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

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. DwTcp uses this to determine
   how long to wait on an idle TCP connection before dropping it.
   The default value for this is 3, as in 3 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.

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 both standard ip/netmask formats to specify IPs. An
   ip is in dotted-decimal format, e.g. "10.1.2.3" 

   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

   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 dwood2rc
   file, read other files and parse them as if they were dwood2rc
   files.

   This is done using execfile. To use execfile, place a line like
   this in the dwood2rc file:

   execfile("path/to/filename")

   Where path/to/filename is the path to the file to be parsed like
   a dwood2rc file.  Forward slashes are used to separate 
   directories.

   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 dwood2rc 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 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;
   make sure the file secret.txt is sufficiently random to be
   nay-to-impossible to guess the contents of.

   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. 

   When using a precompiled binary of Deadwood, one can generate a 
   31-bit random prime, then use the hash_magic_number parameter to 
   have Deadwood use this random prime number.

                      Example configuration file

   Here is an example dwood2rc 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"

 # Please replace these numbers with the IPs of
 # real recursive DNS servers; this information
 # can be obtained from your ISP or network
 # manager.
 upstream_servers = {}
 upstream_servers["."]="10.1.2.3, 10.2.3.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"

                           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. 
