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
36       * The ability to assign names to IPv4 IPs as specified in one's
37         dwood3rc file.
38
39       * The ability to quickly load and use a large blocklist of names to not
40         resolve.
41

COMMAND LINE ARGUMENTS

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

CONFIGURATION FILE FORMAT

55       The Deadwood configuration file is modeled after Python 2's syntax.
56       However, since Deadwood 2 is no longer supported by the Python Software
57       Foundation, and since Deadwood configuration files can sometimes fail
58       to parse in Python 3, Deadwood does not strictly follow Python 2
59       syntax.
60
61       In particular, leading whitespace is allowed in Deadwood configuration
62       files.
63

PARAMETER TYPES

65       Deadwood has three different parameter types:
66
67       * Numeric parameters. Numeric parameters must not be surrounded by
68         quotes, such as this example:
69
70         filter_rfc1918 = 0
71
72         If a numeric parameter is surrounded by quotes, the error message
73         "Unknown dwood3rc string parameter" will appear.
74
75       * String parameters. String parameters must be surrounded by quotes,
76         such as in this example:
77
78         bind_address = "127.0.0.1"
79
80       * Dictionary parameters. All dictionary parameters must be initialized
81         before use, and dictionary parameters must have both the dictionary
82         index and the value for said index surrounded by quotes, such as in
83         this example:
84
85         upstream_servers = {}
86         upstream_servers["."]="8.8.8.8, 8.8.4.4"
87
88       All dwood3rc parameters except the following are numeric parameters:
89
90       * bind_address (string)
91
92       * cache_file (string)
93
94       * chroot_dir (string)
95
96       * ip_blacklist (string)
97
98       * ip_blocklist (string)
99
100       * ipv4_bind_addresses (string)
101
102       * random_seed_file (string)
103
104       * recursive_acl (string)
105
106       * root_servers (dictionary)
107
108       * upstream_servers (dictionary)
109
110       * ip4 (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    ip4
208
209       This is a dictionary variable which allows us to have given names
210       resolve to bogus IPv4 addresses. Here, we have the name "maradns.foo"
211       resolve to "10.10.10.10" and "kabah.foo" resolve to "10.11.11.11",
212       regardless of what real values these DNS records may have:
213
214       ip4 = {}
215       ip4["maradns.foo."] = "10.10.10.10"
216       ip4["kabah.foo."] = "10.11.11.11"
217
218       Note that a given name can only resolve to a single IP, and that the
219       records have a fixed TTL of 30 seconds.
220
221       It is also possible to use ip4 to set up a blocklist by using "X" for
222       the IP. When this is done, an IPv4 request for a given hostname results
223       in a synthetic "this name does not exist" response. In addition, the
224       corresponding IPv6 request will also return that "name does not exist"
225       reply. For example:
226
227       ip4 = {}
228       ip4["evil.example.com."] = "X"
229
230       Here, both the IPv4 and the IPv6 query for "evil.example.com" will not
231       resolve in Deadwood.
232
233    ip6
234
235       Like ip4, ip6 uses a similar syntax to have bogus IPv6 addresses.  We
236       don't use standard notation for IPv6 addresses. Instead, we we use
237       32-character hex addresses (case insensitive); to make it easier to
238       count long strings of "0"s, the "_" acts like a 0; we also ignore "-"
239       (dash) and " " (space) in ip6 strings.  Here is an example:
240
241       ip6 = {}
242       ip6["maradns.foo."] = "20010db84d617261444e530000001234"
243       ip6["kabah.foo."] = "2001-0DB8-4D61-7261 444E-5300-__00-2345"
244
245    ip_blocklist
246
247       This is a list of IPs that we do not allow to be in the answer to a DNS
248       request. The reason for this is to counteract the practice some ISPs
249       have of converting a "this site does not exist" DNS answer in to a page
250       controlled by the ISP; this results in possible security issues.
251
252       This parameter only accepts individual IPs, and does not use netmasks.
253
254       Note that this parameter used to be called ip_blacklist; while the
255       ip_blacklist name still works as before, ip_blocklist is the current
256       name.
257
258    maradns_uid
259
260       The user-id Deadwood runs as. This can be any number between 10 and
261       16777216; the default value is 707 (a system UID which should be
262       unused). This value is not used on Windows systems.
263
264    maradns_gid
265
266       The group-id Deadwood runs as. This can be any number between 10 and
267       16777216; the default value is 707. This value is not used on Windows
268       systems.
269
270    max_ar_chain
271
272       Whether resource record rotation is enabled. If this has a value of 1,
273       resource record rotation is enabled, otherwise resource record rotation
274       is disabled.
275
276       Resource record rotation is usually desirable, since it allows DNS to
277       act like a crude load balancer. However, on heavily loaded systems it
278       may be desirable to disable it to reduce CPU usage.
279
280       The reason for the unusual name for this variable is to retain
281       compatibility with MaraDNS mararc files.
282
283       The default value is 1: Resource record rotation enabled.
284
285    max_inflights
286
287       The maximum number of simultaneous clients we process at the same time
288       for the same query.
289
290       If, while processing a query for, say, "example.com.", another DNS
291       client sends to Deadwood another query for example.com, instead of
292       creating a new query to process example.com, Deadwood will attach the
293       new client to the same query that is already "in flight", and send a
294       reply to both clients once we have an answer for example.com.
295
296       This is the number of simultaneous clients a given query can have. If
297       this limit is exceeded, subsequents clients with the same query are
298       refused until an answer is found. If this has a value of 1, we do not
299       merge multiple requests for the same query, but give each request its
300       own connection.
301
302       The default value is 8.
303
304    max_ttl
305
306       The maximum amount of time we will keep an entry in the cache, in
307       seconds (also called "Maximum TTL").
308
309       This is the longest we will keep an entry cached. The default value for
310       this parameter is 86400 (one day); the minimum value is 300 (5 minutes)
311       and the maximum value this can have is 7776000 (90 days).
312
313       The reason why this parameter is here is to protect Deadwood from
314       attacks which exploit there being stale data in the cache, such as the
315       "Ghost Domain Names" attack.
316
317    maximum_cache_elements
318
319       The maximum number of elements our cache is allowed to have. This is a
320       number between 32 and 16,777,216; the default value for this is 1024.
321       Note that, if writing the cache to disk or reading the cache from disk,
322       higher values of this will slow down cache reading/writing.
323
324       The amount of memory each cache entry uses is variable depending on the
325       operating system used and the size of memory allocation pages assigned.
326       In Windows XP, for example, each entry uses approximately four
327       kilobytes of memory and Deadwood has an overhead of approximately 512
328       kilobytes.  So, if there are 512 cache elements, Deadwood uses
329       approximately 2.5 megabytes of memory, and if there are 1024 cache
330       elements, Deadwood uses approximately 4.5 megabytes of memory. Again,
331       these numbers are for Windows XP and other operating systems will have
332       different memory allocation numbers.
333
334       Please note that, as of Deadwood 3.5.0004, is is no longer needed to
335       increase maximum_cache_elements to store upstream_server and
336       root_server entries.
337
338    maxprocs
339
340       This is the maximum number of pending remote UDP connections Deadwood
341       can have. The default value for this is 1024.
342
343    max_tcp_procs
344
345       This is the number of allowed open TCP connections. Default value: 8
346
347    min_ttl
348
349       The minimum amount of time we will keep an entry in the cache, in
350       seconds (also called "Minimum TTL").
351
352    num_retries
353
354       The number of times we retry to send a query upstream before giving up.
355       If this is 0, we only try once; if this is 1, we try twice, and so on,
356       up to 32 retries. Note that each retry takes timeout_seconds seconds
357       before we retry again. Default value: 5
358
359    ns_glueless_type
360
361       The RR type we send to resolve glueless records. This should be 1 (A)
362       when mainly using IPv4 to resolve records. If glueless NS records have
363       AAAA but not A records, and IPv6 is enabled, it may make sense to give
364       this a value of 255 (ANY). If IPv4 ever stops being used on a large
365       scale, it may eventually become possible to make this have a value of
366       28 (AAAA).
367
368       The default value is 1: An A (IPv4 IP) record. This parameter has not
369       been tested; use at your own risk.
370
371    random_seed_file
372
373       This is a file that contains random numbers, and is used as a seed for
374       the cryptographically strong random number generator.  Deadwood will
375       try to read 256 bytes from this file (the RNG Deadwood uses can accept
376       a stream of any arbitrary length).
377
378       Note that the hash compression function obtains some of its entropy
379       before parsing the mararc file, and is hard-coded to get entropy from
380       /dev/urandom (secret.txt on Windows systems). Most other entropy used
381       by Deadwood comes from the file pointed to by random_seed_file.
382
383    recurse_min_bind_port
384
385       The lowest numbered port Deadwood is allowed to bind to; this is a
386       random port number used for the source port of outgoing queries, and is
387       not 53 (see dns_port above). This is a number between 1025 and 32767,
388       and has a default value of 15000.  This is used to make DNS spoofing
389       attacks more difficult.
390
391    recurse_number_ports
392
393       The number of ports Deadwood binds to for the source port for outgoing
394       connections; this is a power of 2 between 256 and 32768.  This is used
395       to make DNS spoofing attacks more difficult. The default value is 4096.
396
397    recursive_acl
398
399       This is a list of who is allowed to use Deadwood to perform DNS
400       recursion, in "ip/mask" format. Mask must be a number between 0 and 32
401       (for IPv6, between 0 and 128). For example, "127.0.0.1/8" allows local
402       connections.
403
404    reject_aaaa
405
406       If this has a value of 1, a bogus SOA "not there" reply is sent
407       whenever an AAAA query is sent to Deadwood. In other words, every time
408       a program asks Deadwood for an IPv6 IP address, instead of trying to
409       process the request, when this is set to 1, Deadwood pretends the host
410       name in question does not have an IPv6 address.
411
412       This is useful for people who aren't using IPv6 but use applications
413       (usually *NIX command like applications like "telnet") which slow
414       things down trying to find an IPv6 address.
415
416       This has a default value of 0. In other words, AAAA queries are
417       processed normally unless this is set.
418
419    reject_mx
420
421       When this has the default value of 1, MX queries are silently dropped
422       with their IP logged. A MX query is a query that is only done by a
423       machine if it wishes to be its own mail server sending mail to machines
424       on the internet. This is a query an average desktop machine (including
425       one that uses Outlook or another mail user agent to read and send
426       email) will never make.
427
428       Most likely, if a machine is trying to make a MX query, the machine is
429       being controlled by a remote source to send out undesired "spam" email.
430       This in mind, Deadwood will not allow MX queries to be made unless
431       reject_mx is explicitly set with a value of 0.
432
433       Before disabling this, please keep in mind that Deadwood is optimized
434       to be used for web surfing, not as a DNS server for a mail hub.  In
435       particular, the IPs for MX records are removed from Deadwood's replies
436       and Deadwood needs to perform additional DNS queries to get the IPs
437       corresponding to MX records, and Deadwood's testing is more geared for
438       web surfing (almost 100% A record lookup) and not for mail delivery
439       (extensive MX record lookup).
440
441    reject_ptr
442
443       If this has a value of 1, a bogus SOA "not there" reply is sent
444       whenever a PTR query is sent to Deadwood. In other words, every time a
445       program asks Deadwood for "reverse DNS lookup" -- the hostname for a
446       given IP address -- instead of trying to process the request, when this
447       is set to 1, Deadwood pretends the IP address in question does not have
448       a hostname.
449
450       This is useful for people who are getting slow DNS timeouts when trying
451       to perform a reverse DNS lookups on IPs.
452
453       This has a default value of 0. In other words, PTR queries are
454       processed normally unless this is set.
455
456    resurrections
457
458       If this is set to 1, Deadwood will try to send an expired record to the
459       user before giving up. If it is 0, we don't. Default value: 1
460
461    root_servers
462
463       This is a list of root servers; its syntax is identical to
464       upstream_servers (see below). This is the type of DNS service ICANN,
465       for example, runs. These are servers used that do not give us complete
466       answers to DNS questions, but merely tell us which DNS servers to
467       connect to to get an answer closer to our desired answer.
468
469       Please note that, as of Deadwood 3.5.0004, is is no longer needed to
470       increase maximum_cache_elements to store root_server entries.
471
472    tcp_listen
473
474       In order to enable DNS-over-TCP, this variable must be set and have a
475       value of 1. Default value: 0
476
477    timeout_seconds
478
479       This is how long Deadwood will wait before giving up and discarding a
480       pending UDP DNS reply.  The default value for this is 1, as in 1
481       second, unless Deadwood was compiled with FALLBACK_TIME enabled.
482
483    timeout_seconds_tcp
484
485       How long to wait on an idle TCP connection before dropping it. The
486       default value for this is 4, as in 4 seconds.
487
488    ttl_age
489
490       Whether TTL aging is enabled; whether entries in the cache have their
491       TTLs set to be the amount of time the entries have left in the cache.
492
493       If this has a value of 1, TTL entries are aged. Otherwise, they are
494       not.  The default value for this is 1.
495
496    upstream_port
497
498       This is the port Deadwood uses to connect or send packets to the
499       upstream servers. The default value for this is 53; the standard DNS
500       port.
501
502    upstream_servers
503
504       This is a list of DNS servers that the load balancer will try to
505       contact.  This is a dictionary variable (array indexed by a string
506       instead of by a number) instead of a simple variable. Since
507       upstream_servers is a dictionary variable, it needs to be initialized
508       before being used.
509
510       Deadwood will look at the name of the host that it is trying to find
511       the upstream server for, and will match against the longest suffix it
512       can find.
513
514       For example, if someone sends a query for "www.foo.example.com" to
515       Deadwood, Deadwood will first see if there is an upstream_servers
516       variable for "www.foo.example.com.", then look for "foo.example.com.",
517       then look for "example.com.", then "com.", and finally ".".
518
519       Here is an example of upstream_servers:
520
521       upstream_servers = {} # Initialize dictionary variable
522       upstream_servers["foo.example.com."] = "192.168.42.1"
523       upstream_servers["example.com."] = "192.168.99.254"
524       upstream_servers["."] = "10.1.2.3, 10.1.2.4"
525
526       In this example, anything ending in "foo.example.com" is resolved by
527       the DNS server at 192.168.42.1; anything else ending in "example.com"
528       is resolved by 192.168.99.254; and anything not ending in "example.com"
529       is resolved by either 10.1.2.3 or 10.1.2.4.
530
531       Important: the domain name upstream_servers points to must end in a "."
532       character. This is OK:
533
534       upstream_servers["example.com."] = "192.168.42.1"
535
536       But this is not OK:
537
538       upstream_servers["example.com"] = "192.168.42.1"
539
540       The reason for this is because BIND engages in unexpected behavior when
541       a host name doesn't end in a dot, and by forcing a dot at the end of a
542       hostname, Deadwood doesn't have to guess whether the user wants BIND's
543       behavior or the "normal" behavior.
544
545       If neither root_servers nor upstream_servers are set, Deadwood sets
546       upstream_servers to use the https://quad9.net servers, as follows:
547
548       9.9.9.9
549       149.112.112.112
550
551       Please note that, as of Deadwood 3.5.0004, is is no longer needed to
552       increase maximum_cache_elements to store upstream_server entries.
553
554    verbose_level
555
556       This determines how many messages are logged on standard output; larger
557       values log more messages. The default value for this is 3.
558

ip/mask format of IPs

560       Deadwood uses a standard ip/netmask formats to specify IPs.  An ip is
561       in dotted-decimal format, e.g. "10.1.2.3" (or in IPv6 format when IPv6
562       support is compiled in).
563
564       The netmask is used to specify a range of IPs.  The netmask is a single
565       number between 1 and 32 (128 when IPv6 support is compiled in), which
566       indicates the number of leading "1" bits in the netmask.
567
568       10.1.1.1/24 indicates that any ip from 10.1.1.0 to 10.1.1.255 will
569       match.
570
571       10.2.3.4/16 indicates that any ip from 10.2.0.0 to 10.2.255.255 will
572       match.
573
574       127.0.0.0/8 indicates that any ip with "127" as the first octet
575       (number) will match.
576
577       The netmask is optional, and, if not present, indicates that only a
578       single IP will match.
579

DNS over TCP

581       DNS-over-TCP needs to be explicitly enabled by setting tcp_listen to 1.
582
583       Deadwood extracts useful information from UDP DNS packets marked
584       truncated which almost always removes the need to have DNS-over-TCP.
585       However, Deadwood does not cache DNS packets larger than 512 bytes in
586       size that need to be sent using TCP. In addition, DNS-over-TCP packets
587       which are "incomplete" DNS replies (replies which a stub resolver can
588       not use, which can be either a NS referral or an incomplete CNAME
589       reply) are not handled correctly by Deadwood.
590
591       Deadwood has support for both DNS-over-UDP and DNS-over-TCP; the same
592       daemon listens on both the UDP and TCP DNS port.
593
594       Only UDP DNS queries are cached. Deadwood does not support caching over
595       TCP; it handles TCP to resolve the rare truncated reply without any
596       useful information or to work with very uncommon non-RFC-compliant TCP-
597       only DNS resolvers. In the real world, DNS-over-TCP is almost never
598       used.
599

Parsing other files

601       It is possible to have Deadwood, while parsing the dwood3rc file, read
602       other files and parse them as if they were dwood3rc files.
603
604       This is done using execfile.  To use execfile, place a line like this
605       in the dwood3rc file:
606
607       execfile("path/to/filename")
608
609       Where path/to/filename is the path to the file to be parsed like a
610       dwood3rc file.
611
612       All files must be in or under the directory /etc/deadwood/execfile.
613       Filenames can only have lower-case letters and the underscore character
614       ("_"). Absolute paths are not allowed as the argument to execfile; the
615       filename can not start with a slash ("/") character.
616
617       If there is a parse error in the file pointed to by execfile, Deadwood
618       will report the error as being on the line with the execfile command in
619       the main dwood3rc file. To find where a parse error is in the sub-file,
620       use something like "Deadwood -f /etc/deadwood/execfile/filename" to
621       find the parse error in the offending file, where "filename" is the
622       file to to parsed via execfile.
623

IPV6 support

625       This server can also be optionally compiled to have IPv6 support. In
626       order to enable IPv6 support, add '-DIPV6' to the compile-time flags.
627       For example, to compile this to make a small binary, and to have IPv6
628       support:
629
630            export FLAGS='-Os -DIPV6'
631            make
632
633

SECURITY

635       Deadwood is a program written with security in mind.
636
637       In addition to use a buffer-overflow resistant string library and a
638       coding style and SQA process that checks for buffer overflows and
639       memory leaks, Deadwood uses a strong pseudo-random number generator
640       (The 32-bit version of RadioGatun) to generate both the query ID and
641       source port. For the random number generator to be secure, Deadwood
642       needs a good source of entropy; by default Deadwood will use
643       /dev/urandom to get this entropy.  If you are on a system without
644       /dev/urandom support, it is important to make sure that Deadwood has a
645       good source of entropy so that the query ID and source port are hard to
646       guess (otherwise it is possible to forge DNS packets).
647
648       The Windows port of Deadwood includes a program called
649       "mkSecretTxt.exe" that creates a 64-byte (512 bit) random file called
650       "secret.txt" that can be used by Deadwood (via the "random_seed_file"
651       parameter); Deadwood also gets entropy from the timestamp when Deadwood
652       is started and Deadwood's process ID number, so it is same to use the
653       same static secret.txt file as the random_seed_file for multiple
654       invocations of Deadwood.
655
656       Note that Deadwood is not protected from someone on the same network
657       viewing packets sent by Deadwood and sending forged packets as a reply.
658
659       To protect Deadwood from certain possible denial-of-service attacks, it
660       is best if Deadwood's prime number used for hashing elements in the
661       cache is a random 31-bit prime number. The program RandomPrime.c
662       generates a random prime that is placed in the file DwRandPrime.h that
663       is regenerated whenever either the program is compiled or things are
664       cleaned up with make clean. This program uses /dev/urandom for its
665       entropy; the file DwRandPrime.h will not be regenerated on systems
666       without /dev/urandom.
667
668       On systems without direct /dev/urandom support, it is suggested to see
669       if there is a possible way to give the system a working /dev/urandom.
670       This way, when Deadwood is compiled, the hash magic number will be
671       suitably random.
672
673       If using a precompiled binary of Deadwood, please ensure that the
674       system has /dev/urandom support (on Windows system, please ensure that
675       the file with the name secret.txt is generated by the included
676       mkSecretTxt.exe program); Deadwood, at runtime, uses /dev/urandom
677       (secret.txt in Windows) as a hardcoded path to get entropy (along with
678       the timestamp) for the hash algorithm.
679

DAEMONIZATION

681       Deadwood does not have any built-in daemonization facilities; this is
682       handled by the external program Duende or any other daemonizer.
683

Example configuration file

685       Here is an example dwood3rc configuration file:
686
687       # This is an example deadwood rc file
688       # Note that comments are started by the hash symbol
689
690       bind_address="127.0.0.1" # IP we bind to
691
692       # The following line is disabled by being commented out
693       #bind_address="::1" # We have optional IPv6 support
694
695       # Directory we run program from (not used in Win32)
696       chroot_dir = "/etc/deadwood"
697
698       # The following upstream DNS servers are Google's
699       # (as of December 2009) public DNS servers.  For
700       # more information, see the page at
701       # http://code.google.com/speed/public-dns/
702       #
703       # If neither root_servers nor upstream_servers are set,
704       # Deadwood will use the default ICANN root servers.
705       #upstream_servers = {}
706       #upstream_servers["."]="8.8.8.8, 8.8.4.4"
707
708       # Who is allowed to use the cache.  This line
709       # allows anyone with "127.0" as the first two
710       # digits of their IP to use Deadwood
711       recursive_acl = "127.0.0.1/16"
712
713       # Maximum number of pending requests
714       maxprocs = 2048
715
716       # Send SERVER FAIL when overloaded
717       handle_overload = 1
718
719       maradns_uid = 99 # UID Deadwood runs as
720       maradns_gid = 99 # GID Deadwood runs as
721
722       maximum_cache_elements = 60000
723
724       # If you want to read and write the cache from disk,
725       # make sure chroot_dir above is readable and writable
726       # by the maradns_uid/gid above, and uncomment the
727       # following line.
728       #cache_file = "dw_cache"
729
730       # If your upstream DNS server converts "not there" DNS replies
731       # in to IPs, this parameter allows Deadwood to convert any reply
732       # with a given IP back in to a "not there" IP.  If any of the IPs
733       # listed below are in a DNS answer, Deadwood converts the answer
734       # in to a "not there"
735       #ip_blocklist = "10.222.33.44, 10.222.3.55"
736
737       # By default, for security reasons, Deadwood does not allow IPs in
738       # the 192.168.x.x, 172.[16-31].x.x, 10.x.x.x, 127.x.x.x,
739       # 169.254.x.x, 224.x.x.x, or 0.0.x.x range.  If using Deadwood
740       # to resolve names on an internal network, uncomment the
741       # following line:
742       #filter_rfc1918 = 0
743
744

BUGS

746       Deadwood does not follow RFC2181's advice to ignore DNS responses with
747       the TC (truncated) bit set, but instead extracts the first RR. If this
748       is not desired, set the undocumented parameter truncation_hack to 0
749       (but read the DNS over TCP section of this man page).
750
751       Deadwood can not process DNS resource record types with numbers between
752       65392 and 65407. These RR types are marked by the IANA for "private
753       use"; Deadwood reserves these record types for internal use. This is
754       only 16 record types out of the 65536 possible DNS record types (only
755       71 have actually been assigned by IANA, so this is a non-issue in the
756       real world).
757
758       It is not clear whether the DNS RFCs allow ASCII control characters in
759       DNS names. Even if they were, Deadwood does not allow ASCII control
760       characters (bytes with a value less then 32) in DNS names.  Other
761       characters (UTF-8, etc.) are allowed.
762
763       Combining a CNAME record with other records is prohibited in RFC1034
764       section 3.6.2 and RFC1912 section 2.4; it makes an answer ambiguous.
765       Deadwood handles this ambiguity differently than some other DNS
766       servers.
767
769       THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR
770       IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
771       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
772       DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
773       ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
774       DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
775       OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
776       HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
777       STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
778       IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
779       POSSIBILITY OF SUCH DAMAGE.
780

AUTHORS

782       Sam Trenholme (http://www.samiam.org) is responsible for this program
783       and man page. He appreciates all of Jean-Jacques Sarton's help giving
784       this program IPv6 support.
785
786
787
788
789DEADWOOD                          August 2009                      DEADWOOD(1)
Impressum