Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DEADWOOD(1)		      Deadwood reference		   DEADWOOD(1)

NAME
       Deadwood	- A recursive caching DNS resolver

DESCRIPTION
       Deadwood	is a DNS cache and recursive server. This is a DNS server with
       the following features:

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

       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
       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 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
       Deadwood	uses both 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 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 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
       /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
       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:

	    export FLAGS='-Os -DIPV6'
	    make

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; 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
       Deadwood	does not have any built-in daemonization facilities; this is
       handled by the external program Duende or any other daemonizer.

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 = "/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
       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 man page. He	appreciates all	of Jean-Jacques	Sarton's help giving
       this program Ipv6 support.

DEADWOOD			  August 2009			   DEADWOOD(1)

NAME | DESCRIPTION | COMMAND LINE ARGUMENTS | CONFIGURATION FILE FORMAT | ip/mask format of IPs | DNS over TCP | Parsing other files | IPV6 support | SECURITY | DAEMONIZATION | Example configuration file | BUGS | LEGAL DISCLAIMER | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Deadwood&sektion=1&manpath=FreeBSD+11.1-RELEASE+and+Ports>

home | help