1
.\" Do *not* edit this file; it was automatically generated by ej2man
2
.\" Look for a name.ej file with the same name as this filename
4
.\" Process this file with the following
5
.\" nroff -man -Tutf8 maradns.8 | tr '\020' ' '
7
.\" Last updated Fri Aug 13 01:48:01 2010
9
.TH DEADWOOD 1 "August 2009" DEADWOOD "Deadwood reference"
10
.\" We don't want hyphenation (it's too ugly)
11
.\" We also disable justification when using nroff
12
.\" Due to the way the -mandoc macro works, this needs to be placed
13
.\" after the .TH heading
17
.\" We need the following stuff so that we can have single quotes
18
.\" In both groff and other UNIX *roff processors
19
.if \n(.g .mso www.tmac
21
.if !\n(.g .if '\(aq'' .ds aq \'
25
Deadwood - A recursive caching DNS resolver
28
Deadwood is a DNS cache and recursive server. This is a DNS server with
29
the following features:
32
Small size and memory footprint suitable for embedded systems
35
Simple and clean codebase
41
Spoof protection: Strong cryptography used to determine the Query ID
45
Ability to read and write the cache to a file
48
Dynamic cache that deletes entries not recently used
51
Ability to use expired entries in the cache when it is impossible to
52
contact upstream DNS servers.
55
Ipv6 support can be compiled in if desired
58
Both DNS-over-UDP and DNS-over-TCP are handled by the same daemon
61
Built-in dnswall functionality
63
.SH "COMMAND LINE ARGUMENTS"
65
Deadwood has a single optional command line argument: The location
66
of the configuration file that Deadwood uses specified with the "-f"
68
If this is not defined, Deadwood uses the file "/etc/dwood3rc" as the
71
In other words, invoking Deadwood as
73
will cause Deadwood to
74
use /etc/dwood3rc as the configuration file; invoking Deadwood as
75
.B "Deadwood -f foobar"
76
will cause Deadwood to use the file "foobar"
77
in the current working directory (the directory one is in when
78
starting Deadwood) as the configuration file.
79
.SH "CONFIGURATION FILE FORMAT"
81
The Deadwood configuration file supports the following parameters:
86
This is the IP (or possibly IPv6) address we bind to.
91
This is the filename of the file used for reading and
92
writing the cache to disk; this string can have lowercase letters,
93
the \(aq-\(aq symbol, the \(aq_\(aq symbol, and the \(aq/\(aq symbol
95
the cache in a subdirectory). All other symbols become a \(aq_\(aq
101
This is the directory the program will run from.
106
Some upstream DNS servers violate the RFCs and send "name error"
107
DNS packets without a SOA record in the NS section of the reply.
108
Deadwood used to discard such packets; Deadwood now passes such
109
packets on to the client without caching them.
111
Should the old behavior of discarding these packets is desired,
112
set this to 0 with "deliver_all=0" in the dwood3rc file.
114
The default value for this is 1
119
This is the port Deadwood binds to and listens on for
120
incoming connections. The default value for this is the standard DNS
127
When this is set to 1, RFC1918 (private) IP addresses are not allowed
129
in DNS replies. See http://crypto.stanford.edu/dns/ for why this
133
The default value for this is 1
138
When this is set to 0, Deadwood sends no reply
139
back to the client (when the client is a TCP client, Deadwood closes
141
TCP connection) when a UDP query is sent upstream and the upstream DNS
144
When this is set to 1, Deadwood sends a SERVER FAIL
145
back to the client when a UDP query is sent upstream and the upstream
149
The default value for this is 1
152
\fBhandle_overload\fR
154
When this has a value of 0, Deadwood sends no reply when a UDP query is
155
sent and the server is overloaded (has too many pending connections);
156
when it has a value of 1, Deadwood sends a SERVER FAIL packet back to
157
the sender of the UDP query. The default value for this is 1.
160
\fBhash_magic_number\fR
162
This is a large 31-bit prime number that the hash compression function
163
uses; use the RandomPrime C program to generate a suitable random prime
164
for this function. This number should be secret; its default value
165
changes for every release of Deadwood.
170
This is a list of IPs that we do not allow to be in the answer to a
171
DNS request. The reason for this is to counteract the practice some
172
ISPs have of converting a "this site does not exist" DNS answer in to
173
a page controlled by the ISP; this results in possible security issues.
175
This parameter only accepts individual IPs, and does not use netmasks.
180
The user-id Deadwood runs as. This can be any number
181
between 10 and 65535; the default value is 99 (nobody on
182
RedHat-derived Linux distributions). This value is not
183
used on Windows systems.
188
The group-id Deadwood runs as. This can be any
189
number between 10 and 65535; the default value is 99. This
190
value is not used on Windows systems.
195
Whether resource record rotation is enabled. This this has a value
196
of 1, resource record rotation is enabled, otherwise resource record
197
rotation is disabled.
199
Resource record rotation is usually desirable, since it allows DNS to
200
act like a crude load balancer. However, on heavily loaded systems it
201
may be desirable to disable to disbale it to reduce CPU usage.
203
The reason for the unusual name for this variable is to retain
205
with MaraDNS mararc files.
207
The default value is 1: Resource record rotation enabled.
212
The maximum number of simultanious clients we process at the same
213
time for the same query.
215
If, while processone a query for, say, "example.com.", another
216
DNS client sends to Deadwood another query for example.com, instead
217
of creating a new query to process example.com, Deadwood will
218
attach the new client to the same query that is already "in flight",
220
send a reply to both clients once we have an answer for example.com.
222
This is the number of simultaneous clients a given query can have. If
224
limit is exceeded, subsequents clients with the same query are refused
226
an answer is found. If this has a value of 1, we do not merge multiple
227
requests for the same query, but give each request its own connection.
229
The default value is 8.
232
\fBmaximum_cache_elements\fR
234
The maximum number of elements our cache
235
is allowed to have. This is a number between 32 and 16,777,216;
236
the default value for this is 1024. Note that, if writing the
237
cache to disk or reading the cache from disk, higher values of
238
this will slow down cache reading/writing.
243
This is the maximum number of pending remote UDP connections
244
Deadwood can have. The default value for this is 32.
249
This is the number of allowed open TCP connections. Default value: 8
254
The number of times we retry to send a query upstream
255
before giving up. If this is 0, we only try once; if this is 1,
256
we try twice, and so on, up to 8 retries. Note that each retry
257
takes timeout_seconds seconds before we retry again. Default
261
\fBns_glueless_type\fR
263
The RR type we send to resolve glueless records. This should be
264
1 (A) when mainly using IPv4 to resolve records. If glueless NS records
265
have AAAA but not A records, and IPv6 is enabled, it may make sense to
266
give this a value of 255 (ANY). If IPv4 ever stops being used on a
268
scale, it may eventually become possible to make this have a value of
271
The default value is 1: An A (IPv4 IP) record.
274
\fBrandom_seed_file\fR
276
This is a file that contains random numbers, and
277
is used as a seed for the cryptographically strong random number
279
Deadwood will try to read 256 bytes from this file (the RNG Deadwood
281
accept a stream of any arbitrary length).
284
\fBrecurse_min_bind_port\fR
286
The lowest numbered port Deadwood is
287
allowed to bind to; this is a random port number used for the source
288
port of outgoing queries, and is not 53 (see dns_port above). This
289
is a number between 1025 and 32767, and has a default value of 15000.
290
This is used to make DNS spoofing attacks more difficult.
293
\fBrecurse_number_ports\fR
295
The number of ports Deadwood binds to for the source port for
296
outgoing connections; this is a power of 2 between 256 and 32768.
297
This is used to make DNS spoofing attacks more difficult. The default
303
This is a list of who is allowed to use the
304
load balancer, in "ip/mask" format. Mask must be a number between
305
0 and 32 (for IPv6, between 0 and 128). For example, "127.0.0.1/8"
306
allows local connections.
311
If this has a value of 1, a bogus SOA "not there" reply is sent
313
an AAAA query is sent to Deadwood. In other words, every time a program
315
Deadwood for an IPv6 IP address, instead of trying to process the
317
when this is set to 1, Deadwood pretends the host name in question does
319
have an IPv6 address.
321
This is useful for people who aren\(aqt using IPv6 but use applications
323
*NIX command like applications like "telnet") which slow things down
325
to find an IPv6 address.
327
This has a default value of 0. In other words, AAAA queries are
329
normally unless this is set.
334
If this is set to 1, Deadwood will try to send an
335
expired record to the user before giving up. If it is 0, we
336
don\(aqt. Default value: 1
341
This is a list of root servers; its syntax is identical to
342
upstream_servers (see below). This is the type of DNS service
343
ICANN, for example, runs. These are servers used that do
344
not give us complete answers to DNS questions, but merely tell
345
us which DNS servers to connect to to get an answer closer to
351
In order to enable DNS-over-TCP, this variable must be set and have
352
a value of 1. Default value: 0
355
\fBtimeout_seconds\fR
357
This is how long Deadwood will wait before giving
358
up and discarding a pending UDP DNS reply.
359
The default value for this is 2, as in 2 seconds.
362
\fBtimeout_seconds_tcp\fR
364
How long to wait on an idle TCP connection before
365
dropping it. The default value for this is 4, as in 4 seconds.
370
Whether TTL aging is enabled; whether entries in the cache have their
371
TTLs set to be the amount of time the entries have left in the cache.
373
If this has a value of 1, TTL entries are aged. Otherwise, they are
375
The default value for this is 1.
380
This is the port Deadwood uses to connect or send packets to the
381
upstream server. The default value for this is 53; the standard
385
\fBupstream_servers\fR
387
This is a list of DNS servers that the load balancer will try to
390
.I "dictionary variable"
391
(array indexed by a string instead of
392
by a number) instead of a simple variable. Since upstream_servers
393
is a dictionary variable, it needs to be initialized before being used.
395
Deadwood will look at the name of the host that it is trying to find
396
the upstream server for, and will match against the longest suffix it
399
For example, if someone sends a query for "www.foo.example.com" to
400
Deadwood, Deadwood will first see if there is an upstream_servers
401
variable for "www.foo.example.com.", then look for "foo.example.com.",
402
then look for "example.com.", then "com.", and finally ".".
404
Here is an example of upstream_servers:
407
upstream_servers = {} # Initialize dictionary variable
408
upstream_servers["foo.example.com."] = "192.168.42.1"
409
upstream_servers["example.com."] = "192.168.99.254"
410
upstream_servers["."] = "10.1.2.3, 10.1.2.4"
413
In this example, anything ending in "foo.example.com" is resolved
414
by the DNS server at 192.168.42.1; anything else ending in
416
is resolved by 192.168.99.254; and anything not ending in "example.com"
417
is resolved by either 10.1.2.3 or 10.1.2.4.
420
the domain name upstream_servers points to must end in
421
a "." character. This is OK:
424
upstream_servers["example.com."] = "192.168.42.1"
432
upstream_servers["example.com"] = "192.168.42.1"
435
The reason for this is because BIND engages in unexpected behavior
436
when a host name deoesn\(aqt end in a dot, and by forcing a dot at the
438
of a hostname, Deadwood doesn\(aqt have to guess whether the user wants
439
BIND\(aqs behavior or the "normal" behavior.
441
If neither root_servers nor upstream_servers are set, Deadwood sets
442
root_servers to use the default ICANN root servers, as follows:
446
198.41.0.4 a.root-servers.net (VeriSign)
447
192.228.79.201 b.root-servers.net (ISI)
448
192.33.4.12 c.root-servers.net (Cogent)
449
128.8.10.90 d.root-servers.net (UMaryland)
450
192.203.230.10 e.root-servers.net (NASA Ames)
451
192.5.5.241 f.root-servers.net (ISC)
452
192.112.36.4 g.root-servers.net (DOD NIC)
453
128.63.2.53 h.root-servers.net (ArmyRU)
454
192.36.148.17 i.root-servers.net (NORDUnet)
455
192.58.128.30 j.root-servers.net (VeriSign)
456
193.0.14.129 k.root-servers.net (Reseaux)
457
199.7.83.42 l.root-servers.net (IANA)
458
202.12.27.33 m.root-servers.net (WIDE)
461
This list is current as of May 3, 2010, and was last changed on
467
This determines how many messages are logged on standard output; larger
468
values log more messages. The default value for this is 3.
469
.SH "ip/mask format of IPs"
471
Deadwood uses both standard ip/netmask formats to specify IPs.
472
An ip is in dotted-decimal format, e.g. "10.1.2.3" (or in ipv6
473
format when ipv6 support is compiled in).
475
The netmask is used to specify a range of IPs.
476
The netmask can be in one of two formats: A single number between
477
1 and 32 (128 when ipv6 support is compiled in), which indicates the
478
number of leading "1" bits in the netmask, or a 4-digit
479
dotted-decimal netmask.
482
indicates that any ip from 10.1.1.0 to 10.1.1.255
485
.B "10.1.1.1/255.255.255.0"
486
is identical to 10.1.1.1/24
489
indicates that any ip from 10.2.0.0 to 10.2.255.255
492
.B "10.2.3.4/255.255.0.0"
493
is identical to 10.2.3.4/16
496
indicates that any ip with "127" as the first
497
octet (number) will match.
499
.B "127.0.0.0/255.0.0.0"
500
is identical to 127.0.0.0/8
502
The netmask is optional, and, if not present, indicates that only
503
a single IP will match.
506
Deadwood has support for both DNS-over-UDP and DNS-over-TCP; the same
507
daemon listens on both the UDP and TCP DNS port. DNS-over-TCP must
508
be explicitly enabled by setting tcp_listen to 1.
510
Only UDP DNS queries are cached. Deadwood does not support caching
511
over TCP; it handles TCP to resolve the occasional truncated reply or
512
handle the occasional non-RFC-compliant TCP-only DNS resolver.
513
.SH "Parsing other files"
515
It is possible to have Deadwood, while parsing the dwood3rc file, read
516
other files and parse them as if they were dwood3rc files.
520
To use execfile, place a line like
521
this in the dwood3rc file:
523
execfile("path/to/filename")
525
Where path/to/filename is the path to the file to be parsed like a
528
All files must be in or under the directory /etc/deadwood/execfile.
529
Filenames can only have lower-case letters and the underscore
530
character ("_"). Absolute paths are not allowed as the argument to
531
execfile; the filename can not start with a slash ("/") character.
533
If there is a parse error in the file pointed to by execfile, Deadwood
534
will report the error as being on the line with the execfile command in
535
the main dwood3rc file. To find where a parse error is in the sub-file,
536
use something like "Deadwood -f /etc/deadwood/execfile/filename"
537
to find the parse error in the offending file, where "filename" is the
539
to to parsed via execfile.
542
This server can also be optionally compiled to have IPv6 support. In
544
to enable IPv6 support, add \(aq-DIPV6\(aq to the compile-time flags.
546
example, to compile this to make a small binary, and to have ipv6
550
export FLAGS=\(aq-Os -DIPV6\(aq
556
Deadwood is a program written with security in mind.
558
In addition to use a buffer-overflow resistant string library and a
560
style and SQA process that checks for buffer overflows and memory
562
Deadwood uses a strong pseudo-random number generator (The 32-bit
564
of Radio Gatun) to generate both the query ID and source port. For the
565
random number generator to be secure, Deadwood needs a good source of
566
entropy; by default Deadwood will use /dev/urandom to get this entropy.
567
If you are on a system without /dev/urandom support, it is important
568
to make sure that Deadwood has a good source of entropy so that the
570
ID and source port are hard to guess (otherwise it is possible to forge
573
Note that Deadwood is not protected from someone on the same network
575
packets sent by Deadwood and sending forged packets as a reply.
577
To protect Deadwood from certain possible denial-of-service attacks, it
579
best if Deadwood\(aqs prime number used for hashing elements in the
581
a random 31-bit prime number. The program RandomPrime.c generates a
582
random prime that is placed in the file DwRandPrime.h that is
584
whenever either the program is compiled or things are cleaned up with
585
make clean. This program uses /dev/urandom for its entropy; the file
586
DwRandPrime.h will not be regenerated on systems without /dev/urandom.
588
On systems without direct /dev/urandom support, it is suggested to see
590
there is a possible way to give the system a working /dev/urandom. This
591
way, when Deadwood is compiled, the hash magic number will be suitably
594
If using a precompiled binary of Deadwood, or if using a system where
596
not feasible to add /dev/urandom support, one can use another system to
597
generate a 31-bit random prime (perhaps using a different system with
598
/dev/urandom support), then use the hash_magic_number parameter to have
599
Deadwood use this random prime number.
602
Deadwood does not have any built-in daemonization facilities; this is
603
handled by the external program Duende or any other daemonizer.
604
.SH "Example configuration file"
606
Here is an example dwood3rc configuration file:
609
# This is an example deadwood rc file
610
# Note that comments are started by the hash symbol
612
bind_address="127.0.0.1" # IP we bind to
614
# The following line is disabled by being commented out
615
#bind_address="::1" # We have optional IPv6 support
617
# Directory we run program from (not used in Win32)
618
chroot_dir = "/etc/deadwood"
620
# The following upstream DNS servers are Google\(aqs
621
# newly-announced (as of December 2009) public DNS
622
# servers. For more information, see the page at
623
# http://code.google.com/speed/public-dns/
625
# These IPs can be changed to the IPs of any recursive
626
# DNS servers that can be reached from the computer
627
# running Deadwood, such as your ISP\(aqs DNS servers.
628
upstream_servers = {}
629
upstream_servers["."]="8.8.8.8, 8.8.4.4"
631
# Who is allowed to use the cache. This line
632
# allows anyone with "127.0" as the first two
633
# digits of their IP to use Deadwood
634
recursive_acl = "127.0.0.1/16"
636
# Maximum number of pending requests
639
# Send SERVER FAIL when overloaded
642
maradns_uid = 99 # UID Deadwood runs as
643
maradns_gid = 99 # GID Deadwood runs as
645
maximum_cache_elements = 60000
647
# If you want to read and write the cache from disk,
648
# make sure chroot_dir above is readable and writable
649
# by the maradns_uid/gid above, and uncomment the
651
#cache_file = "dw_cache"
653
# If your upstream DNS server converts "not there" DNS replies
654
# in to IPs, this parameter allows Deadwood to convert any reply
655
# with a given IP back in to a "not there" IP. If any of the IPs
656
# listed below are in a DNS answer, Deadwood converts the answer
657
# in to a "not there"
658
#ip_blacklist = "10.222.33.44, 10.222.3.55"
663
DNS-over-TCP needs to be explicitly enabled. Note that DNS-over-TCP is
664
almost never used. Also,
665
Deadwood does not cache DNS packets larger than 512 bytes in size that
666
need to be sent using TCP. In addition, DNS-over-TCP packets which
667
are "incomplete" DNS replies (replies which a stub resolver can not
669
namely either a NS referral or an incomplete CNAME reply) are not
670
handled correctly by Deadwood. Again, DNS-over-TCP is very rare.
672
Deadwood can not process DNS resource record types with numbers between
673
65392 and 65407. These RR types are marked by the IANA for "private
675
Deadwood reserves these record types for internal use. This is only 16
676
record types out of the 65536 possible DNS record types (only 71 have
677
actually been assigned by IANA, so this is a non-issue in the real
680
It is not clear whether the DNS RFCs allow ASCII control characters
681
in DNS names. Even if they were, Deadwood does not allow ASCII
682
control characters (bytes with a value less then 32) in DNS names.
683
Other characters (UTF-8, etc.) are allowed.
684
.SH "LEGAL DISCLAIMER"
686
THIS SOFTWARE IS PROVIDED BY THE AUTHORS \(aq\(aqAS IS\(aq\(aq AND ANY
688
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
689
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
690
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE
691
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
692
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
693
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
694
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
695
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
696
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
697
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
700
Sam Trenholme (http://www.samiam.org) is
701
responsible for this program and man page. He appreciates all of
702
Jean-Jacques Sarton\(aqs help giving this program Ipv6 support.
added
removed
doc/en/man/Deadwood.1
