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 Python 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 * blocked_hosts_hash_file (string)
93 * cache_file (string)
95 * chroot_dir (string)
97 * ip4 (dictionary)
99 * ip6 (dictionary)
101 * ip_blacklist (string)
103 * ip_blocklist (string)
105 * ipv4_bind_addresses (string)
107 * random_seed_file (string)
109 * recursive_acl (string)
111 * root_servers (dictionary)
113 * source_ip4 (string)
115 * upstream_servers (dictionary)
117
119 The Deadwood configuration file supports the following parameters:
120 allow_block_hash_zero_key
122 If this numeric parameter has a value of 1, we allow a blocked hosts
124 hash file to have a key which is 0. Otherwise, if a blocked hosts file
125 has a 0 key, Deadwood will terminate when loading the blocked hosts
126 file with the error message "Zero key block hash not allowed by
127 default".
128 There is a security risk if we allow a blocked hosts file to have a 0
130 key: An attacker with access to a recursive instance of Deadwood could
131 have Deadwood use more resources than necessary if they know the block
132 hash file being used. Since the block hash file is read only, hash
133 flooding attacks are not possible, but an attacker could form queries
134 which use more resources to resolve as not being present in the block
135 hash.
136 Deadwood should never be an open recursor and this attack is limited in
138 scope. But be aware of the risks before setting this parameter to 1.
139 bind_address
141 This is the IP (or possibly IPv6) address we bind to.
143 blocked_hosts_hash_file
145 A blocked hosts hash file allows Deadwood to block a large number of
147 host names while using relatively little memory: While using a list of
148 over 200,000 hosts to block in a dwood3rc file uses over 200 megabytes
149 of memory, the same list in a block hash file uses only 7 megabytes of
150 memory.
151 The block hash file is in a special binary format so that a large
153 number of host names can be blocked quickly using little memory.
154 This parameter, if set, is the filename for a block hash file. The file
156 will be located in the directory set by chroot_dir (usually,
157 /etc/deadwood). The file name can have lower case letters, the '-'
158 character (dash), the '_' character (underscore), the '.' character
159 (dot or period), and the '/' character (slash). If the file name has
160 the '.' character (dot/period) in it, it can not have a '/' (slash)
161 after the '.' (dot).
162 The blockHashMake program generates the block hash file. The contents
164 of a block hash file can be looked at and read using the blockHashRead
165 program. See the man pages blockHashMake (1) and blockHashRead (1) for
166 more details.
167 Block hash files have wildcard support. For example, if "example.com"
169 is in the block hash file, then deadwood will block "example.com",
170 "anyname.example.com", "anything.else.example.com",
171 "12345.example.com", and so on.
172 Note that wildcards only work for domain names which are one, two, or
174 three labels long in the database. If "really.bad.example.com" is in
175 the database, "buzz.really.bad.example.com" will not match, since
176 "really.bad.example.com" has four (i.e. more than three) labels.
177 One usable block hash file is available at the repo at
179 https://github.com/samboy/BlockHash
180 cache_file
182 This is the filename of the file used for reading and writing the cache
184 to disk; this string can have lowercase letters, the '-' symbol, the
185 '_' symbol, and the '/' symbol (for putting the cache in a
186 subdirectory). All other symbols become a '_' symbol.
187 This file is read and written as the user Deadwood runs as.
189 chroot_dir
191 This is the directory the program will run from.
193 deliver_all
195 This affects behavior in Deadwood 2.3, but has no effect in Deadwood 3.
197 This variable is only here so Deadwood 2 rc files can run in Deadwood
198 3.
199 dns_port
201 This is the port Deadwood binds to and listens on for incoming
203 connections. The default value for this is the standard DNS port: port
204 53
205 filter_rfc1918
207 When this has a value of 1, a number of different IP ranges are not
209 allowed to be in DNS A replies:
210 * 192.168.x.x
212 * 172.[16-31].x.x
214 * 10.x.x.x
216 * 127.x.x.x
218 * 169.254.x.x
220 * 224.x.x.x
222 * 0.0.x.x
224 If one of the above IPs is detected in a DNS reply, and filter_rfc1918
226 has a value of 1, Deadwood will return a synthetic "this host does not
227 reply" response (a SOA record in the NS section) instead of the A
228 record.
229 The reason for this is to provide a "dnswall" that protects users for
231 some kinds of attacks, as described at http://crypto.stanford.edu/dns/
232 Please note that Deadwood only provides IPv4 "dnswall" functionality
234 and does not help protect against IPv6 answers. If protection against
235 certain IPv6 AAAA records is needed, either disable all AAAA answers by
236 setting reject_aaaa to have a value of 1, or use an external program to
237 filter undesired IPv4 answers (such as the dnswall program).
238 The default value for this is 1
240 handle_noreply
242 When this is set to 0, Deadwood sends no reply back to the client (when
244 the client is a TCP client, Deadwood closes the TCP connection) when a
245 UDP query is sent upstream and the upstream DNS never sends a reply.
246 When this is set to 1, Deadwood sends a SERVER FAIL back to the client
248 when a UDP query is sent upstream and the upstream DNS never sends a
249 reply.
250 The default value for this is 1
252 handle_overload
254 When this has a value of 0, Deadwood sends no reply when a UDP query is
256 sent and the server is overloaded (has too many pending connections);
257 when it has a value of 1, Deadwood sends a SERVER FAIL packet back to
258 the sender of the UDP query. The default value for this is 1.
259 hash_magic_number
261 This used to be used for Deadwood's internal hash generator to keep the
263 hash generator somewhat random and immune to certain types of attacks.
264 In Deadwood 3.0, entropy for the hash function is created by looking at
265 the contents of /dev/urandom (secret.txt on Windows machines) and the
266 current timestamp. This parameter is only here so older configuration
267 files do not break in Deadwood 3.0.
268 ip4
270 This is a dictionary variable which allows us to have given names
272 resolve to bogus IPv4 addresses. Here, we have the name "maradns.foo"
273 resolve to "10.10.10.10" and "kabah.foo" resolve to "10.11.11.11",
274 regardless of what real values these DNS records may have:
275 ip4 = {}
277 ip4["maradns.foo."] = "10.10.10.10"
278 ip4["kabah.foo."] = "10.11.11.11"
279 Note that a given name can only resolve to a single IP, and that the
281 records have a fixed TTL of 30 seconds.
282 It is also possible to use ip4 to set up a blocklist by using "X" for
284 the IP. When this is done, an IPv4 request for a given hostname results
285 in a synthetic "this name does not exist" response. In addition, the
286 corresponding IPv6 request will also return that "name does not exist"
287 reply. For example:
288 ip4 = {}
290 ip4["evil.example.com."] = "X"
291 Here, both the IPv4 and the IPv6 query for "evil.example.com" will not
293 resolve in Deadwood.
294 ip6
296 Like ip4, ip6 uses a similar syntax to have bogus IPv6 addresses. We
298 don't use standard notation for IPv6 addresses. Instead, we we use
299 32-character hex addresses (case insensitive); to make it easier to
300 count long strings of "0"s, the "_" acts like a 0; we also ignore "-"
301 (dash) and " " (space) in ip6 strings. Here is an example:
302 ip6 = {}
304 ip6["maradns.foo."] = "20010db84d617261444e530000001234"
305 ip6["kabah.foo."] = "2001-0DB8-4D61-7261 444E-5300-__00-2345"
306 ip_blocklist
308 This is a list of IPs that we do not allow to be in the answer to a DNS
310 request. The reason for this is to counteract the practice some ISPs
311 have of converting a "this site does not exist" DNS answer in to a page
312 controlled by the ISP; this results in possible security issues.
313 This parameter only accepts individual IPs, and does not use netmasks.
315 Note that this parameter used to be called ip_blacklist; while the
317 ip_blacklist name still works as before, ip_blocklist is the current
318 name.
319 maradns_uid
321 The user-id Deadwood runs as. This can be any number between 10 and
323 16777216; the default value is 707 (a system UID which should be
324 unused). This value is not used on Windows systems.
325 maradns_gid
327 The group-id Deadwood runs as. This can be any number between 10 and
329 16777216; the default value is 707. This value is not used on Windows
330 systems.
331 max_ar_chain
333 Whether resource record rotation is enabled. If this has a value of 1,
335 resource record rotation is enabled, otherwise resource record rotation
336 is disabled.
337 Resource record rotation is usually desirable, since it allows DNS to
339 act like a crude load balancer. However, on heavily loaded systems it
340 may be desirable to disable it to reduce CPU usage.
341 The reason for the unusual name for this variable is to retain
343 compatibility with MaraDNS mararc files.
344 The default value is 1: Resource record rotation enabled.
346 max_inflights
348 The maximum number of simultaneous clients we process at the same time
350 for the same query.
351 If, while processing a query for, say, "example.com.", another DNS
353 client sends to Deadwood another query for example.com, instead of
354 creating a new query to process example.com, Deadwood will attach the
355 new client to the same query that is already "in flight", and send a
356 reply to both clients once we have an answer for example.com.
357 This is the number of simultaneous clients a given query can have. If
359 this limit is exceeded, subsequents clients with the same query are
360 refused until an answer is found. If this has a value of 1, we do not
361 merge multiple requests for the same query, but give each request its
362 own connection.
363 The default value is 8.
365 max_ttl
367 The maximum amount of time we will keep an entry in the cache, in
369 seconds (also called "Maximum TTL").
370 This is the longest we will keep an entry cached. The default value for
372 this parameter is 86400 (one day); the minimum value is 300 (5 minutes)
373 and the maximum value this can have is 7776000 (90 days).
374 The reason why this parameter is here is to protect Deadwood from
376 attacks which exploit there being stale data in the cache, such as the
377 "Ghost Domain Names" attack.
378 maximum_cache_elements
380 The maximum number of elements our cache is allowed to have. This is a
382 number between 32 and 16,777,216; the default value for this is 1024.
383 Note that, if writing the cache to disk or reading the cache from disk,
384 higher values of this will slow down cache reading/writing.
385 The amount of memory each cache entry uses is variable depending on the
387 operating system used and the size of memory allocation pages assigned.
388 In Windows XP, for example, each entry uses approximately four
389 kilobytes of memory and Deadwood has an overhead of approximately 512
390 kilobytes. So, if there are 512 cache elements, Deadwood uses
391 approximately 2.5 megabytes of memory, and if there are 1024 cache
392 elements, Deadwood uses approximately 4.5 megabytes of memory. Again,
393 these numbers are for Windows XP and other operating systems will have
394 different memory allocation numbers.
395 Please note that, as of Deadwood 3.5.0004, is is no longer needed to
397 increase maximum_cache_elements to store upstream_server and
398 root_server entries.
399 maxprocs
401 This is the maximum number of pending remote UDP connections Deadwood
403 can have. The default value for this is 1024.
404 max_tcp_procs
406 This is the number of allowed open TCP connections. Default value: 8
408 min_ttl
410 The minimum amount of time we will keep an entry in the cache, in
412 seconds (also called "Minimum TTL").
413 num_retries
415 The number of times we retry to send a query upstream before giving up.
417 If this is 0, we only try once; if this is 1, we try twice, and so on,
418 up to 32 retries. Note that each retry takes timeout_seconds seconds
419 before we retry again. Default value: 5
420 ns_glueless_type
422 The RR type we send to resolve glueless records. This should always be
424 1 (A; i.e. IPv4 DNS servers). This should never be ANY, see RFC8482.
425 This should not be any other value, since only A glueless NS referrals
426 have ever been tested with Deadwood.
427 The reason why this exists is because, often times in DNS, we get a
429 reply like "The name server for this foo.example.com and no I do not
430 have the IP for foo.example.com" when recursively solving an answer.
431 So, the question is this: Is foo.example.com an IPv4 DNS server, an
432 IPv6 server, or both?
433 On today's internet (mid-2020, during the COVID-19 crisis), the answer
435 is that the name server in question is only on the IPv4 Internet. IPv6
436 is now mainstream (e.g. my ISP gives me a /64 and I no longer have to
437 tunnel through he.net to try out IPv6), but most servers are still IPv4
438 only (e.g. my domains are only on IPv4, and amazon.com does not have an
439 IPv6 address).
440 The reason this parameter exists is because, when I was writing the
442 recursive code for Deadwood, I was thinking of a future where IPv6 is
443 prevalent enough that we would have DNS servers with only IPv6
444 addresses, and glueless NS referrals (the "foo.example.com" case above)
445 would point to servers with IPv6, but not IPv4, addresses.
446 That day may yet come, but preparing Deadwood to still be a viable DNS
448 server when that day comes will require more than changing the RR type
449 sent when it gets a glueless NS referral.
450 random_seed_file
452 This is a file that contains random numbers, and is used as a seed for
454 the cryptographically strong random number generator. Deadwood will try
455 to read 256 bytes from this file (the RNG Deadwood uses can accept a
456 stream of any arbitrary length).
457 Note that the hash compression function obtains some of its entropy
459 before parsing the mararc file, and is hard-coded to get entropy from
460 /dev/urandom (secret.txt on Windows systems). Most other entropy used
461 by Deadwood comes from the file pointed to by random_seed_file.
462 recurse_min_bind_port
464 The lowest numbered port Deadwood is allowed to bind to; this is a
466 random port number used for the source port of outgoing queries, and is
467 not 53 (see dns_port above). This is a number between 1025 and 32767,
468 and has a default value of 15000. This is used to make DNS spoofing
469 attacks more difficult.
470 recurse_number_ports
472 The number of ports Deadwood binds to for the source port for outgoing
474 connections; this is a power of 2 between 256 and 32768. This is used
475 to make DNS spoofing attacks more difficult. The default value is 4096.
476 recursive_acl
478 This is a list of who is allowed to use Deadwood to perform DNS
480 recursion, in "ip/mask" format. Mask must be a number between 0 and 32
481 (for IPv6, between 0 and 128). For example, "127.0.0.1/8" allows local
482 connections.
483 reject_aaaa
485 If this has a value of 1, a bogus SOA "not there" reply is sent
487 whenever an AAAA query is sent to Deadwood. In other words, every time
488 a program asks Deadwood for an IPv6 IP address, instead of trying to
489 process the request, when this is set to 1, Deadwood pretends the host
490 name in question does not have an IPv6 address.
491 This is useful for people who aren't using IPv6 but use applications
493 (usually *NIX command like applications like "telnet") which slow
494 things down trying to find an IPv6 address.
495 This has a default value of 0. In other words, AAAA queries are
497 processed normally unless this is set.
498 reject_mx
500 When this has the default value of 1, MX queries are silently dropped
502 with their IP logged. A MX query is a query that is only done by a
503 machine if it wishes to be its own mail server sending mail to machines
504 on the internet. This is a query an average desktop machine (including
505 one that uses Outlook or another mail user agent to read and send
506 email) will never make.
507 Most likely, if a machine is trying to make a MX query, the machine is
509 being controlled by a remote source to send out undesired "spam" email.
510 This in mind, Deadwood will not allow MX queries to be made unless
511 reject_mx is explicitly set with a value of 0.
512 Before disabling this, please keep in mind that Deadwood is optimized
514 to be used for web surfing, not as a DNS server for a mail hub. In
515 particular, the IPs for MX records are removed from Deadwood's replies
516 and Deadwood needs to perform additional DNS queries to get the IPs
517 corresponding to MX records, and Deadwood's testing is more geared for
518 web surfing (almost 100% A record lookup) and not for mail delivery
519 (extensive MX record lookup).
520 reject_ptr
522 If this has a value of 1, a bogus SOA "not there" reply is sent
524 whenever a PTR query is sent to Deadwood. In other words, every time a
525 program asks Deadwood for "reverse DNS lookup" -- the hostname for a
526 given IP address -- instead of trying to process the request, when this
527 is set to 1, Deadwood pretends the IP address in question does not have
528 a hostname.
529 This is useful for people who are getting slow DNS timeouts when trying
531 to perform a reverse DNS lookups on IPs.
532 This has a default value of 0. In other words, PTR queries are
534 processed normally unless this is set.
535 resurrections
537 If this is set to 1, Deadwood will try to send an expired record to the
539 user before giving up. If it is 0, we don't. Default value: 1
540 rfc8482
542 If this is set to 1, Deadwood will not allow ANY or HINFO queries,
544 sending a RFC8482 response if one is given to Deadwood. If this is 0,
545 ANY and HINFO queries are allowed. Default value: 1
546 If ANY queries are enabled, since Deadwood does not support EDNS nor
548 DNS-over-TCP for upstream queries, Deadwood may not get meaningful
549 replies from upstream servers.
550 root_servers
552 This is a list of root servers; its syntax is identical to
554 upstream_servers (see below). This is the type of DNS service ICANN,
555 for example, runs. These are servers used that do not give us complete
556 answers to DNS questions, but merely tell us which DNS servers to
557 connect to to get an answer closer to our desired answer.
558 As of Deadwood 3.5.0004, it is no longer needed to increase
560 maximum_cache_elements to store root_server entries.
561 Please be aware that this parameter is deprecated. While there are no
563 plans to remove this parameter, Deadwood is no longer being updated to
564 resolve DNS resolution issues when using root_servers to resolve names
565 on the internet. Please use upstream_servers instead.
566 source_ip4
568 With certain complicated networks, it may be desirable to set the
570 source IP of queries sent to upstream or root DNS servers. If so, set
571 this parameter to have the dotted decimal IPv4 address to use when
572 sending IPv4 queries to an upstream DNS server.
573 Use this parameter with caution; Deadwood can very well become non-
575 functional if one uses a source IPv4 address which Deadwood is not
576 bound to.
577 tcp_listen
579 In order to enable DNS-over-TCP, this variable must be set and have a
581 value of 1. Default value: 0
582 timeout_seconds
584 This is how long Deadwood will wait before giving up and discarding a
586 pending UDP DNS reply. The default value for this is 1, as in 1 second,
587 unless Deadwood was compiled with FALLBACK_TIME enabled.
588 timeout_seconds_tcp
590 How long to wait on an idle TCP connection before dropping it. The
592 default value for this is 4, as in 4 seconds.
593 ttl_age
595 Whether TTL aging is enabled; whether entries in the cache have their
597 TTLs set to be the amount of time the entries have left in the cache.
598 If this has a value of 1, TTL entries are aged. Otherwise, they are
600 not. The default value for this is 1.
601 upstream_port
603 This is the port Deadwood uses to connect or send packets to the
605 upstream servers. The default value for this is 53; the standard DNS
606 port.
607 upstream_servers
609 This is a list of DNS servers that the load balancer will try to
611 contact. This is a dictionary variable (array indexed by a string
612 instead of by a number) instead of a simple variable. Since
613 upstream_servers is a dictionary variable, it needs to be initialized
614 before being used.
615 Deadwood will look at the name of the host that it is trying to find
617 the upstream server for, and will match against the longest suffix it
618 can find.
619 For example, if someone sends a query for "www.foo.example.com" to
621 Deadwood, Deadwood will first see if there is an upstream_servers
622 variable for "www.foo.example.com.", then look for "foo.example.com.",
623 then look for "example.com.", then "com.", and finally ".".
624 Here is an example of upstream_servers:
626 upstream_servers = {} # Initialize dictionary variable
628 upstream_servers["foo.example.com."] = "192.168.42.1"
629 upstream_servers["example.com."] = "192.168.99.254"
630 upstream_servers["."] = "10.1.2.3, 10.1.2.4"
631 In this example, anything ending in "foo.example.com" is resolved by
633 the DNS server at 192.168.42.1; anything else ending in "example.com"
634 is resolved by 192.168.99.254; and anything not ending in "example.com"
635 is resolved by either 10.1.2.3 or 10.1.2.4.
636 Important: the domain name upstream_servers points to must end in a "."
638 character. This is OK:
639 upstream_servers["example.com."] = "192.168.42.1"
641 But this is not OK:
643 upstream_servers["example.com"] = "192.168.42.1"
645 The reason for this is because BIND engages in unexpected behavior when
647 a host name doesn't end in a dot, and by forcing a dot at the end of a
648 hostname, Deadwood doesn't have to guess whether the user wants BIND's
649 behavior or the "normal" behavior.
650 If neither root_servers nor upstream_servers are set, Deadwood sets
652 upstream_servers to use the https://quad9.net servers, as follows:
653 9.9.9.9
655 149.112.112.112
656 Please note that, as of Deadwood 3.5.0004, is is no longer needed to
658 increase maximum_cache_elements to store upstream_server entries.
659 verbose_level
661 This determines how many messages are logged on standard output; larger
663 values log more messages. The default value for this is 3.
664
666 Deadwood uses a standard ip/netmask formats to specify IPs. An ip is in
667 dotted-decimal format, e.g. "10.1.2.3" (or in IPv6 format when IPv6
668 support is compiled in).
669 The netmask is used to specify a range of IPs. The netmask is a single
671 number between 1 and 32 (128 when IPv6 support is compiled in), which
672 indicates the number of leading "1" bits in the netmask.
673 10.1.1.1/24 indicates that any ip from 10.1.1.0 to 10.1.1.255 will
675 match.
676 10.2.3.4/16 indicates that any ip from 10.2.0.0 to 10.2.255.255 will
678 match.
679 127.0.0.0/8 indicates that any ip with "127" as the first octet
681 (number) will match.
682 The netmask is optional, and, if not present, indicates that only a
684 single IP will match.
685
687 DNS-over-TCP needs to be explicitly enabled by setting tcp_listen to 1.
688 Deadwood extracts useful information from UDP DNS packets marked
690 truncated which almost always removes the need to have DNS-over-TCP.
691 However, Deadwood does not cache DNS packets larger than 512 bytes in
692 size that need to be sent using TCP. In addition, DNS-over-TCP packets
693 which are "incomplete" DNS replies (replies which a stub resolver can
694 not use, which can be either a NS referral or an incomplete CNAME
695 reply) are not handled correctly by Deadwood.
696 Deadwood has support for both DNS-over-UDP and DNS-over-TCP; the same
698 daemon listens on both the UDP and TCP DNS port.
699 Only UDP DNS queries are cached. Deadwood does not support caching over
701 TCP; it handles TCP to resolve the rare truncated reply without any
702 useful information or to work with very uncommon non-RFC-compliant TCP-
703 only DNS resolvers. In the real world, DNS-over-TCP is almost never
704 used.
705
707 It is possible to have Deadwood, while parsing the dwood3rc file, read
708 other files and parse them as if they were dwood3rc files.
709 This is done using execfile. To use execfile, place a line like this
711 in the dwood3rc file:
712 execfile("path/to/filename")
714 Where path/to/filename is the path to the file to be parsed like a
716 dwood3rc file.
717 All files must be in or under the directory /etc/deadwood/execfile.
719 Filenames can only have lower-case letters and the underscore character
720 ("_"). Absolute paths are not allowed as the argument to execfile; the
721 filename can not start with a slash ("/") character.
722 If there is a parse error in the file pointed to by execfile, Deadwood
724 will report the error as being on the line with the execfile command in
725 the main dwood3rc file. To find where a parse error is in the sub-file,
726 use something like "Deadwood -f /etc/deadwood/execfile/filename" to
727 find the parse error in the offending file, where "filename" is the
728 file to to parsed via execfile.
729
731 This server can also be optionally compiled to have IPv6 support. In
732 order to enable IPv6 support, add '-DIPV6' to the compile-time flags.
733 For example, to compile this to make a small binary, and to have IPv6
734 support:
735 export FLAGS='-Os -DIPV6'
737 make
738
740 Deadwood is a program written with security in mind.
741 In addition to use a buffer-overflow resistant string library and a
743 coding style and SQA process that checks for buffer overflows and
744 memory leaks, Deadwood uses a strong pseudo-random number generator
745 (The 32-bit version of RadioGatun) to generate both the query ID and
746 source port. For the random number generator to be secure, Deadwood
747 needs a good source of entropy; by default Deadwood will use
748 /dev/urandom to get this entropy. If you are on a system without
749 /dev/urandom support, it is important to make sure that Deadwood has a
750 good source of entropy so that the query ID and source port are hard to
751 guess (otherwise it is possible to forge DNS packets).
752 The Windows port of Deadwood includes a program called
754 "mkSecretTxt.exe" that creates a 64-byte (512 bit) random file called
755 "secret.txt" that can be used by Deadwood (via the "random_seed_file"
756 parameter); Deadwood also gets entropy from the timestamp when Deadwood
757 is started and Deadwood's process ID number, so it is same to use the
758 same static secret.txt file as the random_seed_file for multiple
759 invocations of Deadwood.
760 Note that Deadwood is not protected from someone on the same network
762 viewing packets sent by Deadwood and sending forged packets as a reply.
763 To protect Deadwood from certain possible denial-of-service attacks, it
765 is best if Deadwood's prime number used for hashing elements in the
766 cache is a random 31-bit prime number. The program RandomPrime.c
767 generates a random prime that is placed in the file DwRandPrime.h that
768 is regenerated whenever either the program is compiled or things are
769 cleaned up with make clean. This program uses /dev/urandom for its
770 entropy; the file DwRandPrime.h will not be regenerated on systems
771 without /dev/urandom.
772 On systems without direct /dev/urandom support, it is suggested to see
774 if there is a possible way to give the system a working /dev/urandom.
775 This way, when Deadwood is compiled, the hash magic number will be
776 suitably random.
777 If using a precompiled binary of Deadwood, please ensure that the
779 system has /dev/urandom support (on Windows system, please ensure that
780 the file with the name secret.txt is generated by the included
781 mkSecretTxt.exe program); Deadwood, at runtime, uses /dev/urandom
782 (secret.txt in Windows) as a hardcoded path to get entropy (along with
783 the timestamp) for the hash algorithm.
784
786 Deadwood's configuration file format supports two kinds of comments:
787 # This is a comment
789 Here, a comment starts with the # character and continues until the end
791 of the line. In some circumstances, a comment can start after a
792 variable is set, for example:
793 bind_address="127.0.0.1" # IP we bind to
795 The second comment type supports multi-line comments. For example:
797 _rem={}
799 _rem={ #_rem --[=[
800 """
801 We are now in a multi-line comment.
802 This allows a long explanation to be
803 in a Deadwood configuration file
804 """ # ]=]
805 }
806 The actual format is _rem={ at the start of a line, which begins a
808 multi-line comment. The comment continues until a } is seen. The reason
809 for this unusual format is that it allows a Deadwood configuration file
810 to have multi-line comments in a form which are compatible with both
811 Lua and Python, as can be seen in the above example.
812
814 Deadwood does not have any built-in daemonization facilities; this is
815 handled by the external program Duende or any other daemonizer.
816
818 Here is an example dwood3rc configuration file:
819 # This is an example deadwood rc file
821 # Note that comments are started by the hash symbol
822 bind_address="127.0.0.1" # IP we bind to
824 # The following line is disabled by being commented out
826 #bind_address="::1" # We have optional IPv6 support
827 # Directory we run program from (not used in Win32)
829 chroot_dir = "/etc/deadwood"
830 # The following upstream DNS servers are Google's
832 # (as of December 2009) public DNS servers. For
833 # more information, see the page at
834 # http://code.google.com/speed/public-dns/
835 #
836 # If neither root_servers nor upstream_servers are set,
837 # Deadwood will use the default ICANN root servers.
838 #upstream_servers = {}
839 #upstream_servers["."]="8.8.8.8, 8.8.4.4"
840 # Who is allowed to use the cache. This line
842 # allows anyone with "127.0" as the first two
843 # digits of their IP to use Deadwood
844 recursive_acl = "127.0.0.1/16"
845 # Maximum number of pending requests
847 maxprocs = 2048
848 # Send SERVER FAIL when overloaded
850 handle_overload = 1
851 maradns_uid = 99 # UID Deadwood runs as
853 maradns_gid = 99 # GID Deadwood runs as
854 maximum_cache_elements = 60000
856 # If you want to read and write the cache from disk,
858 # make sure chroot_dir above is readable and writable
859 # by the maradns_uid/gid above, and uncomment the
860 # following line.
861 #cache_file = "dw_cache"
862 # If your upstream DNS server converts "not there" DNS replies
864 # in to IPs, this parameter allows Deadwood to convert any reply
865 # with a given IP back in to a "not there" IP. If any of the IPs
866 # listed below are in a DNS answer, Deadwood converts the answer
867 # in to a "not there"
868 #ip_blocklist = "10.222.33.44, 10.222.3.55"
869 # By default, for security reasons, Deadwood does not allow IPs in
871 # the 192.168.x.x, 172.[16-31].x.x, 10.x.x.x, 127.x.x.x,
872 # 169.254.x.x, 224.x.x.x, or 0.0.x.x range. If using Deadwood
873 # to resolve names on an internal network, uncomment the
874 # following line:
875 #filter_rfc1918 = 0
876
878 Deadwood does not follow RFC2181's advice to ignore DNS responses with
879 the TC (truncated) bit set, but instead extracts the first RR. If this
880 is not desired, set the undocumented parameter truncation_hack to 0
881 (but read the DNS over TCP section of this man page).
882 Deadwood can not process DNS resource record types with numbers between
884 65392 and 65407. These RR types are marked by the IANA for "private
885 use"; Deadwood reserves these record types for internal use. This is
886 only 16 record types out of the 65536 possible DNS record types (only
887 71 have actually been assigned by IANA, so this is a non-issue in the
888 real world).
889 In addition, Deadwood will, by default, respond to both ANY and HINFO
891 requests with a RFC8482 compliant packet instead of trying to resolve
892 the record.
893 It is not clear whether the DNS RFCs allow ASCII control characters in
895 DNS names. Even if they were, Deadwood does not allow ASCII control
896 characters (bytes with a value less then 32) in DNS names. Other
897 characters (UTF-8, etc.) are allowed.
898 Combining a CNAME record with other records is prohibited in RFC1034
900 section 3.6.2 and RFC1912 section 2.4; it makes an answer ambiguous.
901 Deadwood handles this ambiguity differently than some other DNS
902 servers.
903
905 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR
906 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
907 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
908 DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
909 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
910 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
911 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
912 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
913 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
914 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
915 POSSIBILITY OF SUCH DAMAGE.
916
918 Sam Trenholme (http://www.samiam.org) is responsible for this program
919 and man page. He appreciates all of Jean-Jacques Sarton's help giving
920 this program IPv6 support.
921DEADWOOD August 2009 DEADWOOD(1)