1DEADWOOD(1) Deadwood reference DEADWOOD(1)
2
6 Deadwood - A fully recursive caching DNS resolver
7
9 Deadwood is a fully recursive DNS cache. This is a DNS server with the
10 following features:
11 * Full support for both DNS recursion and DNS forwarding caching
13 * Small size and memory footprint suitable for embedded systems
15 * Simple and clean codebase
17 * Secure design
19 * Spoof protection: Strong cryptography used to determine the Query ID
21 and source port
22 * Ability to read and write the cache to a file
24 * Dynamic cache that deletes entries not recently used
26 * Ability to use expired entries in the cache when it is impossible to
28 contact upstream DNS servers.
29 * IPv6 support can be compiled in if desired
31 * Both DNS-over-UDP and DNS-over-TCP are handled by the same daemon
33 * Built-in dnswall functionality
35 * The ability to assign names to IPv4 IPs as specified in one's
37 dwood3rc file.
38 * The ability to quickly load and use a large blocklist of names to not
40 resolve.
41
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 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
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 In particular, leading whitespace is allowed in Deadwood configuration
62 files.
63
65 Deadwood has three different parameter types:
66 * Numeric parameters. Numeric parameters must not be surrounded by
68 quotes, such as this example:
69 filter_rfc1918 = 0
71 If a numeric parameter is surrounded by quotes, the error message
73 "Unknown dwood3rc string parameter" will appear.
74 * String parameters. String parameters must be surrounded by quotes,
76 such as in this example:
77 bind_address = "127.0.0.1"
79 * 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 upstream_servers = {}
86 upstream_servers["."]="8.8.8.8, 8.8.4.4"
87 All dwood3rc parameters except the following are numeric parameters:
89 * bind_address (string)
91 * cache_file (string)
93 * chroot_dir (string)
95 * ip_blacklist (string)
97 * ip_blocklist (string)
99 * ipv4_bind_addresses (string)
101 * random_seed_file (string)
103 * recursive_acl (string)
105 * root_servers (dictionary)
107 * upstream_servers (dictionary)
109 * ip4 (dictionary)
111 * ip6 (dictionary)
113 * source_ip4 (string)
115
117 The Deadwood configuration file supports the following parameters:
118 bind_address
120 This is the IP (or possibly IPv6) address we bind to.
122 cache_file
124 This is the filename of the file used for reading and writing the cache
126 to disk; this string can have lowercase letters, the '-' symbol, the
127 '_' symbol, and the '/' symbol (for putting the cache in a
128 subdirectory). All other symbols become a '_' symbol.
129 This file is read and written as the user Deadwood runs as.
131 chroot_dir
133 This is the directory the program will run from.
135 deliver_all
137 This affects behavior in Deadwood 2.3, but has no effect in Deadwood 3.
139 This variable is only here so Deadwood 2 rc files can run in Deadwood
140 3.
141 dns_port
143 This is the port Deadwood binds to and listens on for incoming
145 connections. The default value for this is the standard DNS port: port
146 53
147 filter_rfc1918
149 When this has a value of 1, a number of different IP ranges are not
151 allowed to be in DNS A replies:
152 * 192.168.x.x
154 * 172.[16-31].x.x
156 * 10.x.x.x
158 * 127.x.x.x
160 * 169.254.x.x
162 * 224.x.x.x
164 * 0.0.x.x
166 If one of the above IPs is detected in a DNS reply, and filter_rfc1918
168 has a value of 1, Deadwood will return a synthetic "this host does not
169 reply" response (a SOA record in the NS section) instead of the A
170 record.
171 The reason for this is to provide a "dnswall" that protects users for
173 some kinds of attacks, as described at http://crypto.stanford.edu/dns/
174 Please note that Deadwood only provides IPv4 "dnswall" functionality
176 and does not help protect against IPv6 answers. If protection against
177 certain IPv6 AAAA records is needed, either disable all AAAA answers by
178 setting reject_aaaa to have a value of 1, or use an external program to
179 filter undesired IPv4 answers (such as the dnswall program).
180 The default value for this is 1
182 handle_noreply
184 When this is set to 0, Deadwood sends no reply back to the client (when
186 the client is a TCP client, Deadwood closes the TCP connection) when a
187 UDP query is sent upstream and the upstream DNS never sends a reply.
188 When this is set to 1, Deadwood sends a SERVER FAIL back to the client
190 when a UDP query is sent upstream and the upstream DNS never sends a
191 reply.
192 The default value for this is 1
194 handle_overload
196 When this has a value of 0, Deadwood sends no reply when a UDP query is
198 sent and the server is overloaded (has too many pending connections);
199 when it has a value of 1, Deadwood sends a SERVER FAIL packet back to
200 the sender of the UDP query. The default value for this is 1.
201 hash_magic_number
203 This used to be used for Deadwood's internal hash generator to keep the
205 hash generator somewhat random and immune to certain types of attacks.
206 In Deadwood 3.0, entropy for the hash function is created by looking at
207 the contents of /dev/urandom (secret.txt on Windows machines) and the
208 current timestamp. This parameter is only here so older configuration
209 files do not break in Deadwood 3.0.
210 ip4
212 This is a dictionary variable which allows us to have given names
214 resolve to bogus IPv4 addresses. Here, we have the name "maradns.foo"
215 resolve to "10.10.10.10" and "kabah.foo" resolve to "10.11.11.11",
216 regardless of what real values these DNS records may have:
217 ip4 = {}
219 ip4["maradns.foo."] = "10.10.10.10"
220 ip4["kabah.foo."] = "10.11.11.11"
221 Note that a given name can only resolve to a single IP, and that the
223 records have a fixed TTL of 30 seconds.
224 It is also possible to use ip4 to set up a blocklist by using "X" for
226 the IP. When this is done, an IPv4 request for a given hostname results
227 in a synthetic "this name does not exist" response. In addition, the
228 corresponding IPv6 request will also return that "name does not exist"
229 reply. For example:
230 ip4 = {}
232 ip4["evil.example.com."] = "X"
233 Here, both the IPv4 and the IPv6 query for "evil.example.com" will not
235 resolve in Deadwood.
236 ip6
238 Like ip4, ip6 uses a similar syntax to have bogus IPv6 addresses. We
240 don't use standard notation for IPv6 addresses. Instead, we we use
241 32-character hex addresses (case insensitive); to make it easier to
242 count long strings of "0"s, the "_" acts like a 0; we also ignore "-"
243 (dash) and " " (space) in ip6 strings. Here is an example:
244 ip6 = {}
246 ip6["maradns.foo."] = "20010db84d617261444e530000001234"
247 ip6["kabah.foo."] = "2001-0DB8-4D61-7261 444E-5300-__00-2345"
248 ip_blocklist
250 This is a list of IPs that we do not allow to be in the answer to a DNS
252 request. The reason for this is to counteract the practice some ISPs
253 have of converting a "this site does not exist" DNS answer in to a page
254 controlled by the ISP; this results in possible security issues.
255 This parameter only accepts individual IPs, and does not use netmasks.
257 Note that this parameter used to be called ip_blacklist; while the
259 ip_blacklist name still works as before, ip_blocklist is the current
260 name.
261 maradns_uid
263 The user-id Deadwood runs as. This can be any number between 10 and
265 16777216; the default value is 707 (a system UID which should be
266 unused). This value is not used on Windows systems.
267 maradns_gid
269 The group-id Deadwood runs as. This can be any number between 10 and
271 16777216; the default value is 707. This value is not used on Windows
272 systems.
273 max_ar_chain
275 Whether resource record rotation is enabled. If this has a value of 1,
277 resource record rotation is enabled, otherwise resource record rotation
278 is disabled.
279 Resource record rotation is usually desirable, since it allows DNS to
281 act like a crude load balancer. However, on heavily loaded systems it
282 may be desirable to disable it to reduce CPU usage.
283 The reason for the unusual name for this variable is to retain
285 compatibility with MaraDNS mararc files.
286 The default value is 1: Resource record rotation enabled.
288 max_inflights
290 The maximum number of simultaneous clients we process at the same time
292 for the same query.
293 If, while processing a query for, say, "example.com.", another DNS
295 client sends to Deadwood another query for example.com, instead of
296 creating a new query to process example.com, Deadwood will attach the
297 new client to the same query that is already "in flight", and send a
298 reply to both clients once we have an answer for example.com.
299 This is the number of simultaneous clients a given query can have. If
301 this limit is exceeded, subsequents clients with the same query are
302 refused until an answer is found. If this has a value of 1, we do not
303 merge multiple requests for the same query, but give each request its
304 own connection.
305 The default value is 8.
307 max_ttl
309 The maximum amount of time we will keep an entry in the cache, in
311 seconds (also called "Maximum TTL").
312 This is the longest we will keep an entry cached. The default value for
314 this parameter is 86400 (one day); the minimum value is 300 (5 minutes)
315 and the maximum value this can have is 7776000 (90 days).
316 The reason why this parameter is here is to protect Deadwood from
318 attacks which exploit there being stale data in the cache, such as the
319 "Ghost Domain Names" attack.
320 maximum_cache_elements
322 The maximum number of elements our cache is allowed to have. This is a
324 number between 32 and 16,777,216; the default value for this is 1024.
325 Note that, if writing the cache to disk or reading the cache from disk,
326 higher values of this will slow down cache reading/writing.
327 The amount of memory each cache entry uses is variable depending on the
329 operating system used and the size of memory allocation pages assigned.
330 In Windows XP, for example, each entry uses approximately four
331 kilobytes of memory and Deadwood has an overhead of approximately 512
332 kilobytes. So, if there are 512 cache elements, Deadwood uses
333 approximately 2.5 megabytes of memory, and if there are 1024 cache
334 elements, Deadwood uses approximately 4.5 megabytes of memory. Again,
335 these numbers are for Windows XP and other operating systems will have
336 different memory allocation numbers.
337 Please note that, as of Deadwood 3.5.0004, is is no longer needed to
339 increase maximum_cache_elements to store upstream_server and
340 root_server entries.
341 maxprocs
343 This is the maximum number of pending remote UDP connections Deadwood
345 can have. The default value for this is 1024.
346 max_tcp_procs
348 This is the number of allowed open TCP connections. Default value: 8
350 min_ttl
352 The minimum amount of time we will keep an entry in the cache, in
354 seconds (also called "Minimum TTL").
355 num_retries
357 The number of times we retry to send a query upstream before giving up.
359 If this is 0, we only try once; if this is 1, we try twice, and so on,
360 up to 32 retries. Note that each retry takes timeout_seconds seconds
361 before we retry again. Default value: 5
362 ns_glueless_type
364 The RR type we send to resolve glueless records. This should always be
366 1 (A; i.e. IPv4 DNS servers). This should never be ANY, see RFC8482.
367 This should not be any other value, since only A glueless NS referrals
368 have ever been tested with Deadwood.
369 The reason why this exists is because, often times in DNS, we get a
371 reply like "The name server for this foo.example.com and no I do not
372 have the IP for foo.example.com" when recursively solving an answer.
373 So, the question is this: Is foo.example.com an IPv4 DNS server, an
374 IPv6 server, or both?
375 On today's internet (mid-2020, during the COVID-19 crisis), the answer
377 is that the name server in question is only on the IPv4 Internet. IPv6
378 is now mainstream (e.g. my ISP gives me a /64 and I no longer have to
379 tunnel through he.net to try out IPv6), but most servers are still IPv4
380 only (e.g. my domains are only on IPv4, and amazon.com does not have an
381 IPv6 address).
382 The reason this parameter exists is because, when I was writing the
384 recursive code for Deadwood, I was thinking of a future where IPv6 is
385 prevalent enough that we would have DNS servers with only IPv6
386 addresses, and glueless NS referrals (the "foo.example.com" case above)
387 would point to servers with IPv6, but not IPv4, addresses.
388 That day may yet come, but preparing Deadwood to still be a viable DNS
390 server when that day comes will require more than changing the RR type
391 sent when it gets a glueless NS referral.
392 random_seed_file
394 This is a file that contains random numbers, and is used as a seed for
396 the cryptographically strong random number generator. Deadwood will
397 try to read 256 bytes from this file (the RNG Deadwood uses can accept
398 a stream of any arbitrary length).
399 Note that the hash compression function obtains some of its entropy
401 before parsing the mararc file, and is hard-coded to get entropy from
402 /dev/urandom (secret.txt on Windows systems). Most other entropy used
403 by Deadwood comes from the file pointed to by random_seed_file.
404 recurse_min_bind_port
406 The lowest numbered port Deadwood is allowed to bind to; this is a
408 random port number used for the source port of outgoing queries, and is
409 not 53 (see dns_port above). This is a number between 1025 and 32767,
410 and has a default value of 15000. This is used to make DNS spoofing
411 attacks more difficult.
412 recurse_number_ports
414 The number of ports Deadwood binds to for the source port for outgoing
416 connections; this is a power of 2 between 256 and 32768. This is used
417 to make DNS spoofing attacks more difficult. The default value is 4096.
418 recursive_acl
420 This is a list of who is allowed to use Deadwood to perform DNS
422 recursion, in "ip/mask" format. Mask must be a number between 0 and 32
423 (for IPv6, between 0 and 128). For example, "127.0.0.1/8" allows local
424 connections.
425 reject_aaaa
427 If this has a value of 1, a bogus SOA "not there" reply is sent
429 whenever an AAAA query is sent to Deadwood. In other words, every time
430 a program asks Deadwood for an IPv6 IP address, instead of trying to
431 process the request, when this is set to 1, Deadwood pretends the host
432 name in question does not have an IPv6 address.
433 This is useful for people who aren't using IPv6 but use applications
435 (usually *NIX command like applications like "telnet") which slow
436 things down trying to find an IPv6 address.
437 This has a default value of 0. In other words, AAAA queries are
439 processed normally unless this is set.
440 reject_mx
442 When this has the default value of 1, MX queries are silently dropped
444 with their IP logged. A MX query is a query that is only done by a
445 machine if it wishes to be its own mail server sending mail to machines
446 on the internet. This is a query an average desktop machine (including
447 one that uses Outlook or another mail user agent to read and send
448 email) will never make.
449 Most likely, if a machine is trying to make a MX query, the machine is
451 being controlled by a remote source to send out undesired "spam" email.
452 This in mind, Deadwood will not allow MX queries to be made unless
453 reject_mx is explicitly set with a value of 0.
454 Before disabling this, please keep in mind that Deadwood is optimized
456 to be used for web surfing, not as a DNS server for a mail hub. In
457 particular, the IPs for MX records are removed from Deadwood's replies
458 and Deadwood needs to perform additional DNS queries to get the IPs
459 corresponding to MX records, and Deadwood's testing is more geared for
460 web surfing (almost 100% A record lookup) and not for mail delivery
461 (extensive MX record lookup).
462 reject_ptr
464 If this has a value of 1, a bogus SOA "not there" reply is sent
466 whenever a PTR query is sent to Deadwood. In other words, every time a
467 program asks Deadwood for "reverse DNS lookup" -- the hostname for a
468 given IP address -- instead of trying to process the request, when this
469 is set to 1, Deadwood pretends the IP address in question does not have
470 a hostname.
471 This is useful for people who are getting slow DNS timeouts when trying
473 to perform a reverse DNS lookups on IPs.
474 This has a default value of 0. In other words, PTR queries are
476 processed normally unless this is set.
477 resurrections
479 If this is set to 1, Deadwood will try to send an expired record to the
481 user before giving up. If it is 0, we don't. Default value: 1
482 root_servers
484 This is a list of root servers; its syntax is identical to
486 upstream_servers (see below). This is the type of DNS service ICANN,
487 for example, runs. These are servers used that do not give us complete
488 answers to DNS questions, but merely tell us which DNS servers to
489 connect to to get an answer closer to our desired answer.
490 Please note that, as of Deadwood 3.5.0004, it is no longer needed to
492 increase maximum_cache_elements to store root_server entries.
493 source_ip4
495 With certain complicated networks, it may be desirable to set the
497 source IP of queries sent to upstream or root DNS servers. If so, set
498 this parameter to have the dotted decimal IPv4 address to use when
499 sending IPv4 queries to an upstream DNS server.
500 Use this parameter with caution; Deadwood can very well become non-
502 functional if one uses a source IPv4 address which Deadwood is not
503 bound to.
504 tcp_listen
506 In order to enable DNS-over-TCP, this variable must be set and have a
508 value of 1. Default value: 0
509 timeout_seconds
511 This is how long Deadwood will wait before giving up and discarding a
513 pending UDP DNS reply. The default value for this is 1, as in 1
514 second, unless Deadwood was compiled with FALLBACK_TIME enabled.
515 timeout_seconds_tcp
517 How long to wait on an idle TCP connection before dropping it. The
519 default value for this is 4, as in 4 seconds.
520 ttl_age
522 Whether TTL aging is enabled; whether entries in the cache have their
524 TTLs set to be the amount of time the entries have left in the cache.
525 If this has a value of 1, TTL entries are aged. Otherwise, they are
527 not. The default value for this is 1.
528 upstream_port
530 This is the port Deadwood uses to connect or send packets to the
532 upstream servers. The default value for this is 53; the standard DNS
533 port.
534 upstream_servers
536 This is a list of DNS servers that the load balancer will try to
538 contact. This is a dictionary variable (array indexed by a string
539 instead of by a number) instead of a simple variable. Since
540 upstream_servers is a dictionary variable, it needs to be initialized
541 before being used.
542 Deadwood will look at the name of the host that it is trying to find
544 the upstream server for, and will match against the longest suffix it
545 can find.
546 For example, if someone sends a query for "www.foo.example.com" to
548 Deadwood, Deadwood will first see if there is an upstream_servers
549 variable for "www.foo.example.com.", then look for "foo.example.com.",
550 then look for "example.com.", then "com.", and finally ".".
551 Here is an example of upstream_servers:
553 upstream_servers = {} # Initialize dictionary variable
555 upstream_servers["foo.example.com."] = "192.168.42.1"
556 upstream_servers["example.com."] = "192.168.99.254"
557 upstream_servers["."] = "10.1.2.3, 10.1.2.4"
558 In this example, anything ending in "foo.example.com" is resolved by
560 the DNS server at 192.168.42.1; anything else ending in "example.com"
561 is resolved by 192.168.99.254; and anything not ending in "example.com"
562 is resolved by either 10.1.2.3 or 10.1.2.4.
563 Important: the domain name upstream_servers points to must end in a "."
565 character. This is OK:
566 upstream_servers["example.com."] = "192.168.42.1"
568 But this is not OK:
570 upstream_servers["example.com"] = "192.168.42.1"
572 The reason for this is because BIND engages in unexpected behavior when
574 a host name doesn't end in a dot, and by forcing a dot at the end of a
575 hostname, Deadwood doesn't have to guess whether the user wants BIND's
576 behavior or the "normal" behavior.
577 If neither root_servers nor upstream_servers are set, Deadwood sets
579 upstream_servers to use the https://quad9.net servers, as follows:
580 9.9.9.9
582 149.112.112.112
583 Please note that, as of Deadwood 3.5.0004, is is no longer needed to
585 increase maximum_cache_elements to store upstream_server entries.
586 verbose_level
588 This determines how many messages are logged on standard output; larger
590 values log more messages. The default value for this is 3.
591
593 Deadwood uses a standard ip/netmask formats to specify IPs. An ip is
594 in dotted-decimal format, e.g. "10.1.2.3" (or in IPv6 format when IPv6
595 support is compiled in).
596 The netmask is used to specify a range of IPs. The netmask is a single
598 number between 1 and 32 (128 when IPv6 support is compiled in), which
599 indicates the number of leading "1" bits in the netmask.
600 10.1.1.1/24 indicates that any ip from 10.1.1.0 to 10.1.1.255 will
602 match.
603 10.2.3.4/16 indicates that any ip from 10.2.0.0 to 10.2.255.255 will
605 match.
606 127.0.0.0/8 indicates that any ip with "127" as the first octet
608 (number) will match.
609 The netmask is optional, and, if not present, indicates that only a
611 single IP will match.
612
614 DNS-over-TCP needs to be explicitly enabled by setting tcp_listen to 1.
615 Deadwood extracts useful information from UDP DNS packets marked
617 truncated which almost always removes the need to have DNS-over-TCP.
618 However, Deadwood does not cache DNS packets larger than 512 bytes in
619 size that need to be sent using TCP. In addition, DNS-over-TCP packets
620 which are "incomplete" DNS replies (replies which a stub resolver can
621 not use, which can be either a NS referral or an incomplete CNAME
622 reply) are not handled correctly by Deadwood.
623 Deadwood has support for both DNS-over-UDP and DNS-over-TCP; the same
625 daemon listens on both the UDP and TCP DNS port.
626 Only UDP DNS queries are cached. Deadwood does not support caching over
628 TCP; it handles TCP to resolve the rare truncated reply without any
629 useful information or to work with very uncommon non-RFC-compliant TCP-
630 only DNS resolvers. In the real world, DNS-over-TCP is almost never
631 used.
632
634 It is possible to have Deadwood, while parsing the dwood3rc file, read
635 other files and parse them as if they were dwood3rc files.
636 This is done using execfile. To use execfile, place a line like this
638 in the dwood3rc file:
639 execfile("path/to/filename")
641 Where path/to/filename is the path to the file to be parsed like a
643 dwood3rc file.
644 All files must be in or under the directory /etc/deadwood/execfile.
646 Filenames can only have lower-case letters and the underscore character
647 ("_"). Absolute paths are not allowed as the argument to execfile; the
648 filename can not start with a slash ("/") character.
649 If there is a parse error in the file pointed to by execfile, Deadwood
651 will report the error as being on the line with the execfile command in
652 the main dwood3rc file. To find where a parse error is in the sub-file,
653 use something like "Deadwood -f /etc/deadwood/execfile/filename" to
654 find the parse error in the offending file, where "filename" is the
655 file to to parsed via execfile.
656
658 This server can also be optionally compiled to have IPv6 support. In
659 order to enable IPv6 support, add '-DIPV6' to the compile-time flags.
660 For example, to compile this to make a small binary, and to have IPv6
661 support:
662 export FLAGS='-Os -DIPV6'
664 make
665
668 Deadwood is a program written with security in mind.
669 In addition to use a buffer-overflow resistant string library and a
671 coding style and SQA process that checks for buffer overflows and
672 memory leaks, Deadwood uses a strong pseudo-random number generator
673 (The 32-bit version of RadioGatun) to generate both the query ID and
674 source port. For the random number generator to be secure, Deadwood
675 needs a good source of entropy; by default Deadwood will use
676 /dev/urandom to get this entropy. If you are on a system without
677 /dev/urandom support, it is important to make sure that Deadwood has a
678 good source of entropy so that the query ID and source port are hard to
679 guess (otherwise it is possible to forge DNS packets).
680 The Windows port of Deadwood includes a program called
682 "mkSecretTxt.exe" that creates a 64-byte (512 bit) random file called
683 "secret.txt" that can be used by Deadwood (via the "random_seed_file"
684 parameter); Deadwood also gets entropy from the timestamp when Deadwood
685 is started and Deadwood's process ID number, so it is same to use the
686 same static secret.txt file as the random_seed_file for multiple
687 invocations of Deadwood.
688 Note that Deadwood is not protected from someone on the same network
690 viewing packets sent by Deadwood and sending forged packets as a reply.
691 To protect Deadwood from certain possible denial-of-service attacks, it
693 is best if Deadwood's prime number used for hashing elements in the
694 cache is a random 31-bit prime number. The program RandomPrime.c
695 generates a random prime that is placed in the file DwRandPrime.h that
696 is regenerated whenever either the program is compiled or things are
697 cleaned up with make clean. This program uses /dev/urandom for its
698 entropy; the file DwRandPrime.h will not be regenerated on systems
699 without /dev/urandom.
700 On systems without direct /dev/urandom support, it is suggested to see
702 if there is a possible way to give the system a working /dev/urandom.
703 This way, when Deadwood is compiled, the hash magic number will be
704 suitably random.
705 If using a precompiled binary of Deadwood, please ensure that the
707 system has /dev/urandom support (on Windows system, please ensure that
708 the file with the name secret.txt is generated by the included
709 mkSecretTxt.exe program); Deadwood, at runtime, uses /dev/urandom
710 (secret.txt in Windows) as a hardcoded path to get entropy (along with
711 the timestamp) for the hash algorithm.
712
714 Deadwood does not have any built-in daemonization facilities; this is
715 handled by the external program Duende or any other daemonizer.
716
718 Here is an example dwood3rc configuration file:
719 # This is an example deadwood rc file
721 # Note that comments are started by the hash symbol
722 bind_address="127.0.0.1" # IP we bind to
724 # The following line is disabled by being commented out
726 #bind_address="::1" # We have optional IPv6 support
727 # Directory we run program from (not used in Win32)
729 chroot_dir = "/etc/deadwood"
730 # The following upstream DNS servers are Google's
732 # (as of December 2009) public DNS servers. For
733 # more information, see the page at
734 # http://code.google.com/speed/public-dns/
735 #
736 # If neither root_servers nor upstream_servers are set,
737 # Deadwood will use the default ICANN root servers.
738 #upstream_servers = {}
739 #upstream_servers["."]="8.8.8.8, 8.8.4.4"
740 # Who is allowed to use the cache. This line
742 # allows anyone with "127.0" as the first two
743 # digits of their IP to use Deadwood
744 recursive_acl = "127.0.0.1/16"
745 # Maximum number of pending requests
747 maxprocs = 2048
748 # Send SERVER FAIL when overloaded
750 handle_overload = 1
751 maradns_uid = 99 # UID Deadwood runs as
753 maradns_gid = 99 # GID Deadwood runs as
754 maximum_cache_elements = 60000
756 # If you want to read and write the cache from disk,
758 # make sure chroot_dir above is readable and writable
759 # by the maradns_uid/gid above, and uncomment the
760 # following line.
761 #cache_file = "dw_cache"
762 # If your upstream DNS server converts "not there" DNS replies
764 # in to IPs, this parameter allows Deadwood to convert any reply
765 # with a given IP back in to a "not there" IP. If any of the IPs
766 # listed below are in a DNS answer, Deadwood converts the answer
767 # in to a "not there"
768 #ip_blocklist = "10.222.33.44, 10.222.3.55"
769 # By default, for security reasons, Deadwood does not allow IPs in
771 # the 192.168.x.x, 172.[16-31].x.x, 10.x.x.x, 127.x.x.x,
772 # 169.254.x.x, 224.x.x.x, or 0.0.x.x range. If using Deadwood
773 # to resolve names on an internal network, uncomment the
774 # following line:
775 #filter_rfc1918 = 0
776
779 Deadwood does not follow RFC2181's advice to ignore DNS responses with
780 the TC (truncated) bit set, but instead extracts the first RR. If this
781 is not desired, set the undocumented parameter truncation_hack to 0
782 (but read the DNS over TCP section of this man page).
783 Deadwood can not process DNS resource record types with numbers between
785 65392 and 65407. These RR types are marked by the IANA for "private
786 use"; Deadwood reserves these record types for internal use. This is
787 only 16 record types out of the 65536 possible DNS record types (only
788 71 have actually been assigned by IANA, so this is a non-issue in the
789 real world).
790 It is not clear whether the DNS RFCs allow ASCII control characters in
792 DNS names. Even if they were, Deadwood does not allow ASCII control
793 characters (bytes with a value less then 32) in DNS names. Other
794 characters (UTF-8, etc.) are allowed.
795 Combining a CNAME record with other records is prohibited in RFC1034
797 section 3.6.2 and RFC1912 section 2.4; it makes an answer ambiguous.
798 Deadwood handles this ambiguity differently than some other DNS
799 servers.
800
802 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR
803 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
804 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
805 DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
806 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
807 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
808 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
809 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
810 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
811 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
812 POSSIBILITY OF SUCH DAMAGE.
813
815 Sam Trenholme (http://www.samiam.org) is responsible for this program
816 and man page. He appreciates all of Jean-Jacques Sarton's help giving
817 this program IPv6 support.
818DEADWOOD August 2009 DEADWOOD(1)