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