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" as
46 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 try
397 to read 256 bytes from this file (the RNG Deadwood uses can accept a
398 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 rfc8482
484 If this is set to 1, Deadwood will not allow ANY or HINFO queries,
486 sending a RFC8482 response if one is given to Deadwood. If this is 0,
487 ANY and HINFO queries are allowed. Default value: 1
488 If ANY queries are enabled, since Deadwood does not support EDNS nor
490 DNS-over-TCP for upstream queries, Deadwood may not get meaningful
491 replies from upstream servers.
492 root_servers
494 This is a list of root servers; its syntax is identical to
496 upstream_servers (see below). This is the type of DNS service ICANN,
497 for example, runs. These are servers used that do not give us complete
498 answers to DNS questions, but merely tell us which DNS servers to
499 connect to to get an answer closer to our desired answer.
500 As of Deadwood 3.5.0004, it is no longer needed to increase
502 maximum_cache_elements to store root_server entries.
503 Please be aware that this parameter is deprecated. While there are no
505 plans to remove this parameter, Deadwood is no longer being updated to
506 resolve DNS resolution issues when using root_servers to resolve names
507 on the internet. Please use upstream_servers instead.
508 source_ip4
510 With certain complicated networks, it may be desirable to set the
512 source IP of queries sent to upstream or root DNS servers. If so, set
513 this parameter to have the dotted decimal IPv4 address to use when
514 sending IPv4 queries to an upstream DNS server.
515 Use this parameter with caution; Deadwood can very well become non-
517 functional if one uses a source IPv4 address which Deadwood is not
518 bound to.
519 tcp_listen
521 In order to enable DNS-over-TCP, this variable must be set and have a
523 value of 1. Default value: 0
524 timeout_seconds
526 This is how long Deadwood will wait before giving up and discarding a
528 pending UDP DNS reply. The default value for this is 1, as in 1 second,
529 unless Deadwood was compiled with FALLBACK_TIME enabled.
530 timeout_seconds_tcp
532 How long to wait on an idle TCP connection before dropping it. The
534 default value for this is 4, as in 4 seconds.
535 ttl_age
537 Whether TTL aging is enabled; whether entries in the cache have their
539 TTLs set to be the amount of time the entries have left in the cache.
540 If this has a value of 1, TTL entries are aged. Otherwise, they are
542 not. The default value for this is 1.
543 upstream_port
545 This is the port Deadwood uses to connect or send packets to the
547 upstream servers. The default value for this is 53; the standard DNS
548 port.
549 upstream_servers
551 This is a list of DNS servers that the load balancer will try to
553 contact. This is a dictionary variable (array indexed by a string
554 instead of by a number) instead of a simple variable. Since
555 upstream_servers is a dictionary variable, it needs to be initialized
556 before being used.
557 Deadwood will look at the name of the host that it is trying to find
559 the upstream server for, and will match against the longest suffix it
560 can find.
561 For example, if someone sends a query for "www.foo.example.com" to
563 Deadwood, Deadwood will first see if there is an upstream_servers
564 variable for "www.foo.example.com.", then look for "foo.example.com.",
565 then look for "example.com.", then "com.", and finally ".".
566 Here is an example of upstream_servers:
568 upstream_servers = {} # Initialize dictionary variable
570 upstream_servers["foo.example.com."] = "192.168.42.1"
571 upstream_servers["example.com."] = "192.168.99.254"
572 upstream_servers["."] = "10.1.2.3, 10.1.2.4"
573 In this example, anything ending in "foo.example.com" is resolved by
575 the DNS server at 192.168.42.1; anything else ending in "example.com"
576 is resolved by 192.168.99.254; and anything not ending in "example.com"
577 is resolved by either 10.1.2.3 or 10.1.2.4.
578 Important: the domain name upstream_servers points to must end in a "."
580 character. This is OK:
581 upstream_servers["example.com."] = "192.168.42.1"
583 But this is not OK:
585 upstream_servers["example.com"] = "192.168.42.1"
587 The reason for this is because BIND engages in unexpected behavior when
589 a host name doesn't end in a dot, and by forcing a dot at the end of a
590 hostname, Deadwood doesn't have to guess whether the user wants BIND's
591 behavior or the "normal" behavior.
592 If neither root_servers nor upstream_servers are set, Deadwood sets
594 upstream_servers to use the https://quad9.net servers, as follows:
595 9.9.9.9
597 149.112.112.112
598 Please note that, as of Deadwood 3.5.0004, is is no longer needed to
600 increase maximum_cache_elements to store upstream_server entries.
601 verbose_level
603 This determines how many messages are logged on standard output; larger
605 values log more messages. The default value for this is 3.
606
608 Deadwood uses a standard ip/netmask formats to specify IPs. An ip is in
609 dotted-decimal format, e.g. "10.1.2.3" (or in IPv6 format when IPv6
610 support is compiled in).
611 The netmask is used to specify a range of IPs. The netmask is a single
613 number between 1 and 32 (128 when IPv6 support is compiled in), which
614 indicates the number of leading "1" bits in the netmask.
615 10.1.1.1/24 indicates that any ip from 10.1.1.0 to 10.1.1.255 will
617 match.
618 10.2.3.4/16 indicates that any ip from 10.2.0.0 to 10.2.255.255 will
620 match.
621 127.0.0.0/8 indicates that any ip with "127" as the first octet
623 (number) will match.
624 The netmask is optional, and, if not present, indicates that only a
626 single IP will match.
627
629 DNS-over-TCP needs to be explicitly enabled by setting tcp_listen to 1.
630 Deadwood extracts useful information from UDP DNS packets marked
632 truncated which almost always removes the need to have DNS-over-TCP.
633 However, Deadwood does not cache DNS packets larger than 512 bytes in
634 size that need to be sent using TCP. In addition, DNS-over-TCP packets
635 which are "incomplete" DNS replies (replies which a stub resolver can
636 not use, which can be either a NS referral or an incomplete CNAME
637 reply) are not handled correctly by Deadwood.
638 Deadwood has support for both DNS-over-UDP and DNS-over-TCP; the same
640 daemon listens on both the UDP and TCP DNS port.
641 Only UDP DNS queries are cached. Deadwood does not support caching over
643 TCP; it handles TCP to resolve the rare truncated reply without any
644 useful information or to work with very uncommon non-RFC-compliant TCP-
645 only DNS resolvers. In the real world, DNS-over-TCP is almost never
646 used.
647
649 It is possible to have Deadwood, while parsing the dwood3rc file, read
650 other files and parse them as if they were dwood3rc files.
651 This is done using execfile. To use execfile, place a line like this
653 in the dwood3rc file:
654 execfile("path/to/filename")
656 Where path/to/filename is the path to the file to be parsed like a
658 dwood3rc file.
659 All files must be in or under the directory /etc/deadwood/execfile.
661 Filenames can only have lower-case letters and the underscore character
662 ("_"). Absolute paths are not allowed as the argument to execfile; the
663 filename can not start with a slash ("/") character.
664 If there is a parse error in the file pointed to by execfile, Deadwood
666 will report the error as being on the line with the execfile command in
667 the main dwood3rc file. To find where a parse error is in the sub-file,
668 use something like "Deadwood -f /etc/deadwood/execfile/filename" to
669 find the parse error in the offending file, where "filename" is the
670 file to to parsed via execfile.
671
673 This server can also be optionally compiled to have IPv6 support. In
674 order to enable IPv6 support, add '-DIPV6' to the compile-time flags.
675 For example, to compile this to make a small binary, and to have IPv6
676 support:
677 export FLAGS='-Os -DIPV6'
679 make
680
682 Deadwood is a program written with security in mind.
683 In addition to use a buffer-overflow resistant string library and a
685 coding style and SQA process that checks for buffer overflows and
686 memory leaks, Deadwood uses a strong pseudo-random number generator
687 (The 32-bit version of RadioGatun) to generate both the query ID and
688 source port. For the random number generator to be secure, Deadwood
689 needs a good source of entropy; by default Deadwood will use
690 /dev/urandom to get this entropy. If you are on a system without
691 /dev/urandom support, it is important to make sure that Deadwood has a
692 good source of entropy so that the query ID and source port are hard to
693 guess (otherwise it is possible to forge DNS packets).
694 The Windows port of Deadwood includes a program called
696 "mkSecretTxt.exe" that creates a 64-byte (512 bit) random file called
697 "secret.txt" that can be used by Deadwood (via the "random_seed_file"
698 parameter); Deadwood also gets entropy from the timestamp when Deadwood
699 is started and Deadwood's process ID number, so it is same to use the
700 same static secret.txt file as the random_seed_file for multiple
701 invocations of Deadwood.
702 Note that Deadwood is not protected from someone on the same network
704 viewing packets sent by Deadwood and sending forged packets as a reply.
705 To protect Deadwood from certain possible denial-of-service attacks, it
707 is best if Deadwood's prime number used for hashing elements in the
708 cache is a random 31-bit prime number. The program RandomPrime.c
709 generates a random prime that is placed in the file DwRandPrime.h that
710 is regenerated whenever either the program is compiled or things are
711 cleaned up with make clean. This program uses /dev/urandom for its
712 entropy; the file DwRandPrime.h will not be regenerated on systems
713 without /dev/urandom.
714 On systems without direct /dev/urandom support, it is suggested to see
716 if there is a possible way to give the system a working /dev/urandom.
717 This way, when Deadwood is compiled, the hash magic number will be
718 suitably random.
719 If using a precompiled binary of Deadwood, please ensure that the
721 system has /dev/urandom support (on Windows system, please ensure that
722 the file with the name secret.txt is generated by the included
723 mkSecretTxt.exe program); Deadwood, at runtime, uses /dev/urandom
724 (secret.txt in Windows) as a hardcoded path to get entropy (along with
725 the timestamp) for the hash algorithm.
726
728 Deadwood's configuration file format supports two kinds of comments:
729 # This is a comment
731 Here, a comment starts with the # character and continues until the end
733 of the line. In some circumstances, a comment can start after a
734 variable is set, for example:
735 bind_address="127.0.0.1" # IP we bind to
737 The second comment type supports multi-line comments. For example:
739 _rem={}
741 _rem={ #_rem --[=[
742 """
743 We are now in a multi-line comment.
744 This allows a long explanation to be
745 in a Deadwood configuration file
746 """ # ]=]
747 }
748 The actual format is _rem={ at the start of a line, which begins a
750 multi-line comment. The comment continues until a } is seen. The reason
751 for this unusual format is that it allows a Deadwood configuration file
752 to have multi-line comments in a form which are compatible with both
753 Lua and Python, as can be seen in the above example.
754
756 Deadwood does not have any built-in daemonization facilities; this is
757 handled by the external program Duende or any other daemonizer.
758
760 Here is an example dwood3rc configuration file:
761 # This is an example deadwood rc file
763 # Note that comments are started by the hash symbol
764 bind_address="127.0.0.1" # IP we bind to
766 # The following line is disabled by being commented out
768 #bind_address="::1" # We have optional IPv6 support
769 # Directory we run program from (not used in Win32)
771 chroot_dir = "/etc/deadwood"
772 # The following upstream DNS servers are Google's
774 # (as of December 2009) public DNS servers. For
775 # more information, see the page at
776 # http://code.google.com/speed/public-dns/
777 #
778 # If neither root_servers nor upstream_servers are set,
779 # Deadwood will use the default ICANN root servers.
780 #upstream_servers = {}
781 #upstream_servers["."]="8.8.8.8, 8.8.4.4"
782 # Who is allowed to use the cache. This line
784 # allows anyone with "127.0" as the first two
785 # digits of their IP to use Deadwood
786 recursive_acl = "127.0.0.1/16"
787 # Maximum number of pending requests
789 maxprocs = 2048
790 # Send SERVER FAIL when overloaded
792 handle_overload = 1
793 maradns_uid = 99 # UID Deadwood runs as
795 maradns_gid = 99 # GID Deadwood runs as
796 maximum_cache_elements = 60000
798 # If you want to read and write the cache from disk,
800 # make sure chroot_dir above is readable and writable
801 # by the maradns_uid/gid above, and uncomment the
802 # following line.
803 #cache_file = "dw_cache"
804 # If your upstream DNS server converts "not there" DNS replies
806 # in to IPs, this parameter allows Deadwood to convert any reply
807 # with a given IP back in to a "not there" IP. If any of the IPs
808 # listed below are in a DNS answer, Deadwood converts the answer
809 # in to a "not there"
810 #ip_blocklist = "10.222.33.44, 10.222.3.55"
811 # By default, for security reasons, Deadwood does not allow IPs in
813 # the 192.168.x.x, 172.[16-31].x.x, 10.x.x.x, 127.x.x.x,
814 # 169.254.x.x, 224.x.x.x, or 0.0.x.x range. If using Deadwood
815 # to resolve names on an internal network, uncomment the
816 # following line:
817 #filter_rfc1918 = 0
818
820 Deadwood does not follow RFC2181's advice to ignore DNS responses with
821 the TC (truncated) bit set, but instead extracts the first RR. If this
822 is not desired, set the undocumented parameter truncation_hack to 0
823 (but read the DNS over TCP section of this man page).
824 Deadwood can not process DNS resource record types with numbers between
826 65392 and 65407. These RR types are marked by the IANA for "private
827 use"; Deadwood reserves these record types for internal use. This is
828 only 16 record types out of the 65536 possible DNS record types (only
829 71 have actually been assigned by IANA, so this is a non-issue in the
830 real world).
831 It is not clear whether the DNS RFCs allow ASCII control characters in
833 DNS names. Even if they were, Deadwood does not allow ASCII control
834 characters (bytes with a value less then 32) in DNS names. Other
835 characters (UTF-8, etc.) are allowed.
836 Combining a CNAME record with other records is prohibited in RFC1034
838 section 3.6.2 and RFC1912 section 2.4; it makes an answer ambiguous.
839 Deadwood handles this ambiguity differently than some other DNS
840 servers.
841
843 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR
844 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
845 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
846 DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
847 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
848 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
849 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
850 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
851 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
852 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
853 POSSIBILITY OF SUCH DAMAGE.
854
856 Sam Trenholme (http://www.samiam.org) is responsible for this program
857 and man page. He appreciates all of Jean-Jacques Sarton's help giving
858 this program IPv6 support.
859DEADWOOD August 2009 DEADWOOD(1)