1DEADWOOD(1)                   Deadwood reference                   DEADWOOD(1)
2
3
4

NAME

6       Deadwood - A fully recursive caching DNS resolver
7

DESCRIPTION

9       Deadwood is a fully recursive DNS cache. This is a DNS server with the
10       following features:
11
12       * Full support for both DNS recursion and DNS forwarding caching
13
14       * Small size and memory footprint suitable for embedded systems
15
16       * Simple and clean codebase
17
18       * Secure design
19
20       * Spoof protection: Strong cryptography used to determine the Query ID
21         and source port
22
23       * Ability to read and write the cache to a file
24
25       * Dynamic cache that deletes entries not recently used
26
27       * Ability to use expired entries in the cache when it is impossible to
28         contact upstream DNS servers.
29
30       * IPv6 support can be compiled in if desired
31
32       * Both DNS-over-UDP and DNS-over-TCP are handled by the same daemon
33
34       * Built-in dnswall functionality
35

COMMAND LINE ARGUMENTS

37       Deadwood has a single optional command line argument: The location of
38       the configuration file that Deadwood uses, specified with the "-f"
39       flag.  If this is not defined, Deadwood uses the file "/etc/dwood3rc"
40       as the configuration file.
41
42       In other words, invoking Deadwood as Deadwood will cause Deadwood to
43       use /etc/dwood3rc as the configuration file; invoking Deadwood as
44       Deadwood -f foobar will cause Deadwood to use the file "foobar" in the
45       current working directory (the directory one is in when starting
46       Deadwood) as the configuration file.
47

CONFIGURATION FILE FORMAT

49       The Deadwood configuration file is modeled after Python 2's syntax.
50       Any valid Deadwood configuration file should also correctly parse in
51       both Python 2.4.3 and Python 2.6.6. If any configuration file does
52       correctly parse in Deadwood but raises a syntax error in Python, this
53       is a bug that should be fixed.
54
55       This in mind, whitespace is significant; Deadwood parameters must be in
56       the leftmost column with no leading whitespace. This is a valid line
57       (as long as there are no spaces to its left):
58
59       recursive_acl = "127.0.0.1/16"
60
61       The following line, however, will raise a parse error:
62
63        recursive_acl = "127.0.0.1/16"
64
65       Observe the space to the left of the "recusive_acl" string in the
66       incorrectly formatted line.
67

PARAMETER TYPES

69       Deadwood has three different parameter types:
70
71       * Numeric parameters. Numeric parameters must not be surrounded by
72         quotes, such as this example:
73
74         filter_rfc1918 = 0
75
76         If a numeric parameter is surrounded by quotes, the error message
77         "Unknown dwood3rc string parameter" will appear.
78
79       * String parameters. String parameters must be surrounded by quotes,
80         such as in this example:
81
82         bind_address = "127.0.0.1"
83
84       * Dictionary parameters. All dictionary parameters must be initialized
85         before use, and dictionary parameters must have both the dictionary
86         index and the value for said index surrounded by quotes, such as in
87         this example:
88
89         upstream_servers = {}
90         upstream_servers["."]="8.8.8.8, 8.8.4.4"
91
92       All dwood3rc parameters except the following are numeric parameters:
93
94       * bind_address (string)
95
96       * cache_file (string)
97
98       * chroot_dir (string)
99
100       * ip_blacklist (string)
101
102       * ipv4_bind_addresses (string)
103
104       * random_seed_file (string)
105
106       * recursive_acl (string)
107
108       * root_servers (dictionary)
109
110       * upstream_servers (dictionary)
111

SUPPORTED PARAMETERS

113       The Deadwood configuration file supports the following parameters:
114
115    bind_address
116
117       This is the IP (or possibly IPv6) address we bind to.
118
119    cache_file
120
121       This is the filename of the file used for reading and writing the cache
122       to disk; this string can have lowercase letters, the '-' symbol, the
123       '_' symbol, and the '/' symbol (for putting the cache in a
124       subdirectory). All other symbols become a '_' symbol.
125
126       This file is read and written as the user Deadwood runs as.
127
128    chroot_dir
129
130       This is the directory the program will run from.
131
132    deliver_all
133
134       This affects behavior in Deadwood 2.3, but has no effect in Deadwood 3.
135       This variable is only here so Deadwood 2 rc files can run in Deadwood
136       3.
137
138    dns_port
139
140       This is the port Deadwood binds to and listens on for incoming
141       connections. The default value for this is the standard DNS port: port
142       53
143
144    filter_rfc1918
145
146       When this has a value of 1, a number of different IP ranges are not
147       allowed to be in DNS A replies:
148
149       * 192.168.x.x
150
151       * 172.[16-31].x.x
152
153       * 10.x.x.x
154
155       * 127.x.x.x
156
157       * 169.254.x.x
158
159       * 224.x.x.x
160
161       * 0.0.x.x
162
163       If one of the above IPs is detected in a DNS reply, and filter_rfc1918
164       has a value of 1, Deadwood will return a synthetic "this host does not
165       reply" response (a SOA record in the NS section) instead of the A
166       record.
167
168       The reason for this is to provide a "dnswall" that protects users for
169       some kinds of attacks, as described at http://crypto.stanford.edu/dns/
170
171       Please note that Deadwood only provides IPv4 "dnswall" functionality
172       and does not help protect against IPv6 answers. If protection against
173       certain IPv6 AAAA records is needed, either disable all AAAA answers by
174       setting reject_aaaa to have a value of 1, or use an external program to
175       filter undesired IPv4 answers (such as the dnswall program).
176
177       The default value for this is 1
178
179    handle_noreply
180
181       When this is set to 0, Deadwood sends no reply back to the client (when
182       the client is a TCP client, Deadwood closes the TCP connection) when a
183       UDP query is sent upstream and the upstream DNS never sends a reply.
184
185       When this is set to 1, Deadwood sends a SERVER FAIL back to the client
186       when a UDP query is sent upstream and the upstream DNS never sends a
187       reply.
188
189       The default value for this is 1
190
191    handle_overload
192
193       When this has a value of 0, Deadwood sends no reply when a UDP query is
194       sent and the server is overloaded (has too many pending connections);
195       when it has a value of 1, Deadwood sends a SERVER FAIL packet back to
196       the sender of the UDP query. The default value for this is 1.
197
198    hash_magic_number
199
200       This used to be used for Deadwood's internal hash generator to keep the
201       hash generator somewhat random and immune to certain types of attacks.
202       In Deadwood 3.0, entropy for the hash function is created by looking at
203       the contents of /dev/urandom (secret.txt on Windows machines) and the
204       current timestamp. This parameter is only here so older configuration
205       files do not break in Deadwood 3.0.
206
207    ip_blacklist
208
209       This is a list of IPs that we do not allow to be in the answer to a DNS
210       request. The reason for this is to counteract the practice some ISPs
211       have of converting a "this site does not exist" DNS answer in to a page
212       controlled by the ISP; this results in possible security issues.
213
214       This parameter only accepts individual IPs, and does not use netmasks.
215
216    maradns_uid
217
218       The user-id Deadwood runs as. This can be any number between 10 and
219       65535; the default value is 99 (nobody on RedHat-derived Linux
220       distributions). This value is not used on Windows systems.
221
222    maradns_gid
223
224       The group-id Deadwood runs as. This can be any number between 10 and
225       65535; the default value is 99. This value is not used on Windows
226       systems.
227
228    max_ar_chain
229
230       Whether resource record rotation is enabled. If this has a value of 1,
231       resource record rotation is enabled, otherwise resource record rotation
232       is disabled.
233
234       Resource record rotation is usually desirable, since it allows DNS to
235       act like a crude load balancer. However, on heavily loaded systems it
236       may be desirable to disable it to reduce CPU usage.
237
238       The reason for the unusual name for this variable is to retain
239       compatibility with MaraDNS mararc files.
240
241       The default value is 1: Resource record rotation enabled.
242
243    max_inflights
244
245       The maximum number of simultaneous clients we process at the same time
246       for the same query.
247
248       If, while processing a query for, say, "example.com.", another DNS
249       client sends to Deadwood another query for example.com, instead of
250       creating a new query to process example.com, Deadwood will attach the
251       new client to the same query that is already "in flight", and send a
252       reply to both clients once we have an answer for example.com.
253
254       This is the number of simultaneous clients a given query can have. If
255       this limit is exceeded, subsequents clients with the same query are
256       refused until an answer is found. If this has a value of 1, we do not
257       merge multiple requests for the same query, but give each request its
258       own connection.
259
260       The default value is 8.
261
262    max_ttl
263
264       The maximum amount of time we will keep an entry in the cache, in
265       seconds (also called "Maximum TTL").
266
267       This is the longest we will keep an entry cached. The default value for
268       this parameter is 86400 (one day); the minimum value is 300 (5 minutes)
269       and the maximum value this can have is 7776000 (90 days).
270
271       The reason why this parameter is here is to protect Deadwood from
272       attacks which exploit there being stale data in the cache, such as the
273       "Ghost Domain Names" attack.
274
275    maximum_cache_elements
276
277       The maximum number of elements our cache is allowed to have. This is a
278       number between 32 and 16,777,216; the default value for this is 1024.
279       Note that, if writing the cache to disk or reading the cache from disk,
280       higher values of this will slow down cache reading/writing.
281
282       The amount of memory each cache entry uses is variable depending on the
283       operating system used and the size of memory allocation pages assigned.
284       In Windows XP, for example, each entry uses approximately four
285       kilobytes of memory and Deadwood has an overhead of approximately 512
286       kilobytes.  So, if there are 512 cache elements, Deadwood uses
287       approximately 2.5 megabytes of memory, and if there are 1024 cache
288       elements, Deadwood uses approximately 4.5 megabytes of memory. Again,
289       these numbers are for Windows XP and other operating systems will have
290       different memory allocation numbers.
291
292       Please note that each root_servers and upstream_servers entry takes up
293       space in Deadwood's cache and that maximum_cache_elements will need to
294       be increased to store a large number of these entries.
295
296    maxprocs
297
298       This is the maximum number of pending remote UDP connections Deadwood
299       can have. The default value for this is 1024.
300
301    max_tcp_procs
302
303       This is the number of allowed open TCP connections. Default value: 8
304
305    num_retries
306
307       The number of times we retry to send a query upstream before giving up.
308       If this is 0, we only try once; if this is 1, we try twice, and so on,
309       up to 32 retries. Note that each retry takes timeout_seconds seconds
310       before we retry again. Default value: 5
311
312    ns_glueless_type
313
314       The RR type we send to resolve glueless records. This should be 1 (A)
315       when mainly using IPv4 to resolve records. If glueless NS records have
316       AAAA but not A records, and IPv6 is enabled, it may make sense to give
317       this a value of 255 (ANY). If IPv4 ever stops being used on a large
318       scale, it may eventually become possible to make this have a value of
319       28 (AAAA).
320
321       The default value is 1: An A (IPv4 IP) record. This parameter has not
322       been tested; use at your own risk.
323
324    random_seed_file
325
326       This is a file that contains random numbers, and is used as a seed for
327       the cryptographically strong random number generator.  Deadwood will
328       try to read 256 bytes from this file (the RNG Deadwood uses can accept
329       a stream of any arbitrary length).
330
331       Note that the hash compression function obtains some of its entropy
332       before parsing the mararc file, and is hard-coded to get entropy from
333       /dev/urandom (secret.txt on Windows systems). Most other entropy used
334       by Deadwood comes from the file pointed to by random_seed_file.
335
336    recurse_min_bind_port
337
338       The lowest numbered port Deadwood is allowed to bind to; this is a
339       random port number used for the source port of outgoing queries, and is
340       not 53 (see dns_port above). This is a number between 1025 and 32767,
341       and has a default value of 15000.  This is used to make DNS spoofing
342       attacks more difficult.
343
344    recurse_number_ports
345
346       The number of ports Deadwood binds to for the source port for outgoing
347       connections; this is a power of 2 between 256 and 32768.  This is used
348       to make DNS spoofing attacks more difficult. The default value is 4096.
349
350    recursive_acl
351
352       This is a list of who is allowed to use Deadwood to perform DNS
353       recursion, in "ip/mask" format. Mask must be a number between 0 and 32
354       (for IPv6, between 0 and 128). For example, "127.0.0.1/8" allows local
355       connections.
356
357    reject_aaaa
358
359       If this has a value of 1, a bogus SOA "not there" reply is sent
360       whenever an AAAA query is sent to Deadwood. In other words, every time
361       a program asks Deadwood for an IPv6 IP address, instead of trying to
362       process the request, when this is set to 1, Deadwood pretends the host
363       name in question does not have an IPv6 address.
364
365       This is useful for people who aren't using IPv6 but use applications
366       (usually *NIX command like applications like "telnet") which slow
367       things down trying to find an IPv6 address.
368
369       This has a default value of 0. In other words, AAAA queries are
370       processed normally unless this is set.
371
372    reject_mx
373
374       When this has the default value of 1, MX queries are silently dropped
375       with their IP logged. A MX query is a query that is only done by a
376       machine if it wishes to be its own mail server sending mail to machines
377       on the internet. This is a query an average desktop machine (including
378       one that uses Outlook or another mail user agent to read and send
379       email) will never make.
380
381       Most likely, if a machine is trying to make a MX query, the machine is
382       being controlled by a remote source to send out undesired "spam" email.
383       This in mind, Deadwood will not allow MX queries to be made unless
384       reject_mx is explicitly set with a value of 0.
385
386       Before disabling this, please keep in mind that Deadwood is optimized
387       to be used for web surfing, not as a DNS server for a mail hub.  In
388       particular, the IPs for MX records are removed from Deadwood's replies
389       and Deadwood needs to perform additional DNS queries to get the IPs
390       corresponding to MX records, and Deadwood's testing is more geared for
391       web surfing (almost 100% A record lookup) and not for mail delivery
392       (extensive MX record lookup).
393
394    reject_ptr
395
396       If this has a value of 1, a bogus SOA "not there" reply is sent
397       whenever a PTR query is sent to Deadwood. In other words, every time a
398       program asks Deadwood for "reverse DNS lookup" -- the hostname for a
399       given IP address -- instead of trying to process the request, when this
400       is set to 1, Deadwood pretends the IP address in question does not have
401       a hostname.
402
403       This is useful for people who are getting slow DNS timeouts when trying
404       to perform a reverse DNS lookups on IPs.
405
406       This has a default value of 0. In other words, PTR queries are
407       processed normally unless this is set.
408
409    resurrections
410
411       If this is set to 1, Deadwood will try to send an expired record to the
412       user before giving up. If it is 0, we don't. Default value: 1
413
414    root_servers
415
416       This is a list of root servers; its syntax is identical to
417       upstream_servers (see below). This is the type of DNS service ICANN,
418       for example, runs. These are servers used that do not give us complete
419       answers to DNS questions, but merely tell us which DNS servers to
420       connect to to get an answer closer to our desired answer.
421
422       Please note that each root_servers entry takes up space in Deadwood's
423       cache and that maximum_cache_elements will need to be increased to
424       store a large number of these entries.
425
426    tcp_listen
427
428       In order to enable DNS-over-TCP, this variable must be set and have a
429       value of 1. Default value: 0
430
431    timeout_seconds
432
433       This is how long Deadwood will wait before giving up and discarding a
434       pending UDP DNS reply.  The default value for this is 1, as in 1
435       second, unless Deadwood was compiled with FALLBACK_TIME enabled.
436
437    timeout_seconds_tcp
438
439       How long to wait on an idle TCP connection before dropping it. The
440       default value for this is 4, as in 4 seconds.
441
442    ttl_age
443
444       Whether TTL aging is enabled; whether entries in the cache have their
445       TTLs set to be the amount of time the entries have left in the cache.
446
447       If this has a value of 1, TTL entries are aged. Otherwise, they are
448       not.  The default value for this is 1.
449
450    upstream_port
451
452       This is the port Deadwood uses to connect or send packets to the
453       upstream servers. The default value for this is 53; the standard DNS
454       port.
455
456    upstream_servers
457
458       This is a list of DNS servers that the load balancer will try to
459       contact.  This is a dictionary variable (array indexed by a string
460       instead of by a number) instead of a simple variable. Since
461       upstream_servers is a dictionary variable, it needs to be initialized
462       before being used.
463
464       Deadwood will look at the name of the host that it is trying to find
465       the upstream server for, and will match against the longest suffix it
466       can find.
467
468       For example, if someone sends a query for "www.foo.example.com" to
469       Deadwood, Deadwood will first see if there is an upstream_servers
470       variable for "www.foo.example.com.", then look for "foo.example.com.",
471       then look for "example.com.", then "com.", and finally ".".
472
473       Here is an example of upstream_servers:
474
475       upstream_servers = {} # Initialize dictionary variable
476       upstream_servers["foo.example.com."] = "192.168.42.1"
477       upstream_servers["example.com."] = "192.168.99.254"
478       upstream_servers["."] = "10.1.2.3, 10.1.2.4"
479
480       In this example, anything ending in "foo.example.com" is resolved by
481       the DNS server at 192.168.42.1; anything else ending in "example.com"
482       is resolved by 192.168.99.254; and anything not ending in "example.com"
483       is resolved by either 10.1.2.3 or 10.1.2.4.
484
485       Important: the domain name upstream_servers points to must end in a "."
486       character. This is OK:
487
488       upstream_servers["example.com."] = "192.168.42.1"
489
490       But this is not OK:
491
492       upstream_servers["example.com"] = "192.168.42.1"
493
494       The reason for this is because BIND engages in unexpected behavior when
495       a host name doesn't end in a dot, and by forcing a dot at the end of a
496       hostname, Deadwood doesn't have to guess whether the user wants BIND's
497       behavior or the "normal" behavior.
498
499       If neither root_servers nor upstream_servers are set, Deadwood sets
500       root_servers to use the default ICANN root servers, as follows:
501
502       198.41.0.4      a.root-servers.net (VeriSign)
503       199.9.14.201    b.root-servers.net (ISI)
504       192.33.4.12     c.root-servers.net (Cogent)
505       199.7.91.13     d.root-servers.net (UMaryland)
506       192.203.230.10  e.root-servers.net (NASA Ames)
507       192.5.5.241     f.root-servers.net (ISC)
508       192.112.36.4    g.root-servers.net (DOD NIC)
509       198.97.190.53   h.root-servers.net (ArmyRU)
510       192.36.148.17   i.root-servers.net (NORDUnet)
511       192.58.128.30   j.root-servers.net (VeriSign)
512       193.0.14.129    k.root-servers.net (Reseaux)
513       199.7.83.42     l.root-servers.net (IANA)
514       202.12.27.33    m.root-servers.net (WIDE)
515
516       This list is current as of November 9, 2017, and was last changed in
517       October of 2017.
518
519       Please note that each upstream_servers entry takes up space in
520       Deadwood's cache and that maximum_cache_elements will need to be
521       increased to store a large number of these entries.
522
523    verbose_level
524
525       This determines how many messages are logged on standard output; larger
526       values log more messages. The default value for this is 3.
527

ip/mask format of IPs

529       Deadwood uses a standard ip/netmask formats to specify IPs.  An ip is
530       in dotted-decimal format, e.g. "10.1.2.3" (or in IPv6 format when IPv6
531       support is compiled in).
532
533       The netmask is used to specify a range of IPs.  The netmask is a single
534       number between 1 and 32 (128 when IPv6 support is compiled in), which
535       indicates the number of leading "1" bits in the netmask.
536
537       10.1.1.1/24 indicates that any ip from 10.1.1.0 to 10.1.1.255 will
538       match.
539
540       10.2.3.4/16 indicates that any ip from 10.2.0.0 to 10.2.255.255 will
541       match.
542
543       127.0.0.0/8 indicates that any ip with "127" as the first octet
544       (number) will match.
545
546       The netmask is optional, and, if not present, indicates that only a
547       single IP will match.
548

DNS over TCP

550       DNS-over-TCP needs to be explicitly enabled by setting tcp_listen to 1.
551
552       Deadwood extracts useful information from UDP DNS packets marked
553       truncated which almost always removes the need to have DNS-over-TCP.
554       However, Deadwood does not cache DNS packets larger than 512 bytes in
555       size that need to be sent using TCP. In addition, DNS-over-TCP packets
556       which are "incomplete" DNS replies (replies which a stub resolver can
557       not use, which can be either a NS referral or an incomplete CNAME
558       reply) are not handled correctly by Deadwood.
559
560       Deadwood has support for both DNS-over-UDP and DNS-over-TCP; the same
561       daemon listens on both the UDP and TCP DNS port.
562
563       Only UDP DNS queries are cached. Deadwood does not support caching over
564       TCP; it handles TCP to resolve the rare truncated reply without any
565       useful information or to work with very uncommon non-RFC-compliant TCP-
566       only DNS resolvers. In the real world, DNS-over-TCP is almost never
567       used.
568

Parsing other files

570       It is possible to have Deadwood, while parsing the dwood3rc file, read
571       other files and parse them as if they were dwood3rc files.
572
573       This is done using execfile.  To use execfile, place a line like this
574       in the dwood3rc file:
575
576       execfile("path/to/filename")
577
578       Where path/to/filename is the path to the file to be parsed like a
579       dwood3rc file.
580
581       All files must be in or under the directory /etc/deadwood/execfile.
582       Filenames can only have lower-case letters and the underscore character
583       ("_"). Absolute paths are not allowed as the argument to execfile; the
584       filename can not start with a slash ("/") character.
585
586       If there is a parse error in the file pointed to by execfile, Deadwood
587       will report the error as being on the line with the execfile command in
588       the main dwood3rc file. To find where a parse error is in the sub-file,
589       use something like "Deadwood -f /etc/deadwood/execfile/filename" to
590       find the parse error in the offending file, where "filename" is the
591       file to to parsed via execfile.
592

IPV6 support

594       This server can also be optionally compiled to have IPv6 support. In
595       order to enable IPv6 support, add '-DIPV6' to the compile-time flags.
596       For example, to compile this to make a small binary, and to have IPv6
597       support:
598
599            export FLAGS='-Os -DIPV6'
600            make
601
602

SECURITY

604       Deadwood is a program written with security in mind.
605
606       In addition to use a buffer-overflow resistant string library and a
607       coding style and SQA process that checks for buffer overflows and
608       memory leaks, Deadwood uses a strong pseudo-random number generator
609       (The 32-bit version of RadioGatun) to generate both the query ID and
610       source port. For the random number generator to be secure, Deadwood
611       needs a good source of entropy; by default Deadwood will use
612       /dev/urandom to get this entropy.  If you are on a system without
613       /dev/urandom support, it is important to make sure that Deadwood has a
614       good source of entropy so that the query ID and source port are hard to
615       guess (otherwise it is possible to forge DNS packets).
616
617       The Windows port of Deadwood includes a program called
618       "mkSecretTxt.exe" that creates a 64-byte (512 bit) random file called
619       "secret.txt" that can be used by Deadwood (via the "random_seed_file"
620       parameter); Deadwood also gets entropy from the timestamp when Deadwood
621       is started and Deadwood's process ID number, so it is same to use the
622       same static secret.txt file as the random_seed_file for multiple
623       invocations of Deadwood.
624
625       Note that Deadwood is not protected from someone on the same network
626       viewing packets sent by Deadwood and sending forged packets as a reply.
627
628       To protect Deadwood from certain possible denial-of-service attacks, it
629       is best if Deadwood's prime number used for hashing elements in the
630       cache is a random 31-bit prime number. The program RandomPrime.c
631       generates a random prime that is placed in the file DwRandPrime.h that
632       is regenerated whenever either the program is compiled or things are
633       cleaned up with make clean. This program uses /dev/urandom for its
634       entropy; the file DwRandPrime.h will not be regenerated on systems
635       without /dev/urandom.
636
637       On systems without direct /dev/urandom support, it is suggested to see
638       if there is a possible way to give the system a working /dev/urandom.
639       This way, when Deadwood is compiled, the hash magic number will be
640       suitably random.
641
642       If using a precompiled binary of Deadwood, please ensure that the
643       system has /dev/urandom support (on Windows system, please ensure that
644       the file with the name secret.txt is generated by the included
645       mkSecretTxt.exe program); Deadwood, at runtime, uses /dev/urandom
646       (secret.txt in Windows) as a hardcoded path to get entropy (along with
647       the timestamp) for the hash algorithm.
648

DAEMONIZATION

650       Deadwood does not have any built-in daemonization facilities; this is
651       handled by the external program Duende or any other daemonizer.
652

Example configuration file

654       Here is an example dwood3rc configuration file:
655
656       # This is an example deadwood rc file
657       # Note that comments are started by the hash symbol
658
659       bind_address="127.0.0.1" # IP we bind to
660
661       # The following line is disabled by being commented out
662       #bind_address="::1" # We have optional IPv6 support
663
664       # Directory we run program from (not used in Win32)
665       chroot_dir = "/etc/deadwood"
666
667       # The following upstream DNS servers are Google's
668       # (as of December 2009) public DNS servers.  For
669       # more information, see the page at
670       # http://code.google.com/speed/public-dns/
671       #
672       # If neither root_servers nor upstream_servers are set,
673       # Deadwood will use the default ICANN root servers.
674       #upstream_servers = {}
675       #upstream_servers["."]="8.8.8.8, 8.8.4.4"
676
677       # Who is allowed to use the cache.  This line
678       # allows anyone with "127.0" as the first two
679       # digits of their IP to use Deadwood
680       recursive_acl = "127.0.0.1/16"
681
682       # Maximum number of pending requests
683       maxprocs = 2048
684
685       # Send SERVER FAIL when overloaded
686       handle_overload = 1
687
688       maradns_uid = 99 # UID Deadwood runs as
689       maradns_gid = 99 # GID Deadwood runs as
690
691       maximum_cache_elements = 60000
692
693       # If you want to read and write the cache from disk,
694       # make sure chroot_dir above is readable and writable
695       # by the maradns_uid/gid above, and uncomment the
696       # following line.
697       #cache_file = "dw_cache"
698
699       # If your upstream DNS server converts "not there" DNS replies
700       # in to IPs, this parameter allows Deadwood to convert any reply
701       # with a given IP back in to a "not there" IP.  If any of the IPs
702       # listed below are in a DNS answer, Deadwood converts the answer
703       # in to a "not there"
704       #ip_blacklist = "10.222.33.44, 10.222.3.55"
705
706       # By default, for security reasons, Deadwood does not allow IPs in
707       # the 192.168.x.x, 172.[16-31].x.x, 10.x.x.x, 127.x.x.x,
708       # 169.254.x.x, 224.x.x.x, or 0.0.x.x range.  If using Deadwood
709       # to resolve names on an internal network, uncomment the
710       # following line:
711       #filter_rfc1918 = 0
712
713

BUGS

715       Deadwood does not follow RFC2181's advice to ignore DNS responses with
716       the TC (truncated) bit set, but instead extracts the first RR. If this
717       is not desired, set the undocumented parameter truncation_hack to 0
718       (but read the DNS over TCP section of this man page).
719
720       Deadwood can not process DNS resource record types with numbers between
721       65392 and 65407. These RR types are marked by the IANA for "private
722       use"; Deadwood reserves these record types for internal use. This is
723       only 16 record types out of the 65536 possible DNS record types (only
724       71 have actually been assigned by IANA, so this is a non-issue in the
725       real world).
726
727       It is not clear whether the DNS RFCs allow ASCII control characters in
728       DNS names. Even if they were, Deadwood does not allow ASCII control
729       characters (bytes with a value less then 32) in DNS names.  Other
730       characters (UTF-8, etc.) are allowed.
731
732       Combining a CNAME record with other records is prohibited in RFC1034
733       section 3.6.2 and RFC1912 section 2.4; it makes an answer ambiguous.
734       Deadwood handles this ambiguity differently than some other DNS
735       servers.
736
738       THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR
739       IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
740       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
741       DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
742       ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
743       DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
744       OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
745       HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
746       STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
747       IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
748       POSSIBILITY OF SUCH DAMAGE.
749

AUTHORS

751       Sam Trenholme (http://www.samiam.org) is responsible for this program
752       and man page. He appreciates all of Jean-Jacques Sarton's help giving
753       this program IPv6 support.
754
755
756
757
758DEADWOOD                          August 2009                      DEADWOOD(1)
Impressum