1MARADNS(8) MaraDNS reference MARADNS(8)
2Erre con erre cigarro
6Erre con erre barril
7Rápido ruedan los carros
8En el ferrocarril
9
12 maradns - DNS server
13
15 maradns [ -v | -f mararc_file_location ]
16
18 This man page has the following sections:
19 Name
21 Synopsis
22 Table of Contents
23 Description
24 Usage
25 Firewall Configuration
26 Frequently Asked Questions
27 Bugs
28 Unimplemented Features
29 Legal Disclaimer
30 Authors
31
34 maradns is a DNS server written with security, simplicity, and
35 performance in mind.
36 maradns has two forms of arguments, both of which are optional.
38 The first is the location of a mararc file which MaraDNS obtains all
40 configuration information from. The default location of this file is
41 /etc/mararc. This is specified in the form maradns -f
42 mararc_file_location; mararc_file_location is the location of the
43 mararc file.
44 It is also possible to have MaraDNS display the version number and
46 exit. This is specified by invoking maradns in the form maradns -v or
47 maradns --version
48
50 If MaraDNS is functioning only as a recursive nameserver, just one file
51 needs to be set up: The mararc file.
52 In order for MaraDNS to function as an authoritative nameserver, two or
54 more files need to be set up: the mararc file and one or more "csv1"
55 zone files.
56 The configuration formation of a csv1 zone file can be obtained from
58 the csv1(5) manual page. The configuration format of the mararc file
59 can be obtained from the mararc(5) manual page.
60 In order to have MaraDNS run as a daemon, the duende program is used to
62 daemonize MaraDNS. See the duende(8) manual page for details.
63
65 If MaraDNS is being used as an authoritative nameserver, allow UDP
66 connections from all hosts on the internet to UDP port 53 for the IP
67 that the authoritative nameserver uses.
68 If MaraDNS is being used as a recursive nameserver, the firewall needs
70 to allow the following packets to go to and from the IP the recursive
71 nameserver uses:
72 * Allow UDP connections from the MaraDNS-running server to any machine
74 on the internet where the UDP destination port is 53
75 * Allow UDP connections from any machine on the internet to the IP of
77 the recursive server, where the source port from the remote server is
78 53, and the destination port is between 15000 and 19095 (inclusive)
79 * Allow UDP connections from IPs that use MaraDNS as a recursive DNS
81 server to port 53 of the MaraDNS server
82 MaraDNS uses a strong secure RNG for both the query (16 bits of
84 entropy) and the source port of the query (12 bits of entropy). This
85 makes spoofing replies to a MaraDNS server more difficult, since the
86 attacker has only a one in 250 million chance that a given spoofed
87 reply will be considered valid.
88
90 INDEX
91 1. I'm still using version 1.0 of MaraDNS
93 2. How do I try out MaraDNS?
95 3. What license is MaraDNS released under?
97 4. How do I report bugs in MaraDNS?
99 5. Some of the postings to the mailing list do not talk about
101 MaraDNS!
102 6. How do I get off the mailing list?
104 7. How do I set up reverse DNS on MaraDNS?
106 8. I am on a slow network, and MaraDNS can not process recursive
108 queries
109 9. When I try to run MaraDNS, I get a cryptic error message.
111 10. After I start MaraDNS, I can not see the process when I run
113 netstat -na
114 11. What string library does MaraDNS use?
116 12. Why does MaraDNS use a multi-threaded model?
118 13. I feel that XXX feature should be added to MaraDNS
120 14. I feel that MaraDNS should use another documentation format
122 15. Is there any process I need to follow to add a patch to
124 MaraDNS?
125 16. Can MaraDNS act as a primary nameserver?
127 17. Can MaraDNS act as a secondary nameserver?
129 18. What is the difference between an authoritative and a recursive
131 DNS server?
132 19. The getzone client isn't allowing me to add certain hostnames
134 to my zone
135 20. Is MaraDNS portable?
137 21. Can I use MaraDNS in Windows?
139 22. MaraDNS freezes up after being used for a while
141 23. What kind of Python integration does MaraDNS have
143 24. Doesn't "kvar" mean "four" in Esperanto?
145 25. How scalable is MaraDNS?
147 26. I am having problems setting upstream_servers
149 27. Why doesn't the MaraDNS.org web page validate?
151 28. How do MX records work?
153 29. Does MaraDNS have support for SPF?
155 30. I'm having problems resolving CNAMES I have set up.
157 31. I have a NS delegation, and MaraDNS is doing strange things.
159 32. I am transferring a zone from another server, but the NS
161 records are these strange "synth-ip" records.
162 33. Where is the root.hints file?
164 34. Are there any plans to use autoconf to build MaraDNS?
166 35. How do I change the compiler or compile-time flags with
168 MaraDNS' build process?
169 36. Will you make a package for the particular Linux distribution I
171 am using?
172 37. I am using the native Windows port of MaraDNS, and some
174 features are not working.
175 38. MaraDNS isn't starting up
177 39. You make a lot of releases of MaraDNS; at our ISP/IT
179 department, updating software is non-trivial.
180 ANSWERS
182 1. I'm still using version 1.0 of MaraDNS
184 MaraDNS 1.0 will continue to be supported until December 21, 2007; this
186 means that MaraDNS 1.0 bug fixes will still be applied. After
187 2007/12/21, MaraDNS 1.0 will no longer be fully supported; the only
188 updates, at that point, would be bugtraq-worthy critical security
189 fixes. Not even these security updates will be applied after December
190 21, 2010.
191 People who wish to run MaraDNS 1.0 unsupported after 2010/12/21 need to
193 keep in mind that MaraDNS 1.0 is not Y2038 compliant, and will have
194 problems starting in 2036 or so. MaraDNS 1.2, on the other hand, is
195 fully Y2038 compliant.
196 There is still a FAQ for version 1.0 of MaraDNS available here.
198 Updating from 1.0 to 1.2 requires a minimum number of changes; with
200 most configurations, MaraDNS 1.2 is fully compatible with MaraDNS 1.0
201 data files. Details are in the updating document in the tutorial.
202 While csv1 zone files are fully supported in MaraDNS 1.2, there is a
204 Perl script for updating from CSV1 to CSV2 zone files in the tools/
205 directory of MaraDNS 1.2.
206 2. How do I try out MaraDNS?
208 Read the quick start guide, which is the file named 0QuickStart in the
210 MaraDNS distribution.
211 3. What license is MaraDNS released under?
213 MaraDNS 1.2 is released with the following two-clause BSD-type license:
215 Copyright (c) 2002-2007 Sam Trenholme
217 TERMS
219 Redistribution and use in source and binary forms, with or without
221 modification, are permitted provided that the following conditions
222 are met:
223 1. Redistributions of source code must retain the above copyright
225 notice, this list of conditions and the following disclaimer.
226 2. Redistributions in binary form must reproduce the above
228 copyright notice, this list of conditions and the following
229 disclaimer in the documentation and/or other materials provided
230 with the distribution.
231 This software is provided 'as is' with no guarantees of correctness
233 or fitness for purpose.
234 4. How do I report bugs in MaraDNS?
236 Please contact me; my email address is at
238 http://www.maradns.org/contact.html. Please be sure to include all
239 information requested there, including the operating system you are
240 using, the version of MaraDNS you are using, your mararc configuration
241 file, and all relevant zone files.
242 5. Some of the postings to the mailing list do not talk about MaraDNS!
244 In cases where I post something to the mailing list which does not
246 directly talk about MaraDNS, the subject line will not have [MARA] in
247 it, but will have some form of the word CHATTER in it.
248 This way, people who do not like this can set up mail filters to filter
250 out anything that comes from this list and doesn't have [MARA] in the
251 subject line, or simply unsubscribe from the list and read the list
252 from the archives; if one needs to report a bug, they can subscribe to
253 the list again, post their bug, then unsubscribe after a week.
254 Another option is to set up one's Freshmeat preferences to be notified
256 in email every time I update MaraDNS at Freshmeat. This will give one
257 email notice of any critical bug fixes without needing to be subscribed
258 to the mailing list.
259 The web page http://www.maradns.org/ has a link to the mailing list
261 archives.
262 6. How do I get off the mailing list?
264 Send an email to list-request@maradns.org with "unsubscribe" as the
266 subject line.
267 7. How do I set up reverse DNS on MaraDNS?
269 Reverse DNS (sometimes called "reverse mapping") is set up by using PTR
271 (pointer) records. For example, the PTR record which performs the
272 reverse DNS lookup for the ip 10.2.3.4 looks like this in a CSV2 zone
273 file:
274 4.3.2.10.in-addr.arpa. PTR www.example.com. ~
276 It is also possible, on MaraDNS 1.2.05 and more recent releases, to use
278 a special "FQDN4" which automatically sets up the reverse mapping of a
279 given record:
280 www.example.com. FQDN6 10.2.3.4 ~
282 If you wish to have a PTR (reverse DNS lookup; getting a DNS name from
284 a numeric IP) record work on the internet at large, it is not a simple
285 matter of just adding a record like this to a MaraDNS zonefile. One
286 also needs control of the appropriate in-addr.arpa. domain.
287 While it can make logical sense to contact the IP 10.11.12.13 when
289 trying to get the reverse DNS lookup (fully qualified domain name) for
290 a given IP, DNS servers don't do this. DNS server, instead, contact the
291 root DNS servers for a given in-addr.arpa name to get the reverse DNS
292 lookup, just like they do with any other record type.
293 When an internet service provider is given a block of IPs, they are
295 also given control of the DNS zones which allow them to control reverse
296 DNS lookups for those IPs. While it is possible to obtain a domain and
297 run a DNS server without the knowledge or intervention of an ISP, being
298 able to control reverse DNS lookups for those IPs requires ISP
299 intervention.
300 8. I am on a slow network, and MaraDNS can not process recursive queries
302 MaraDNS, by default, only waits two seconds for a reply from a remote
304 DNS server. This default can be increased by adding a line like this in
305 the mararc file:
306 timeout_seconds = 5
308 Note that making this too high will slow MaraDNS down when DNS servers
311 are down, which is, alas, all too common on today's internet.
312 9. When I try to run MaraDNS, I get a cryptic error message.
314 There is usually some context of where there is a syntax error in a
316 data file before the cryptic error message. For example, when there is
317 a syntax error in a csv2 zone file, MaraDNS will tell you exactly at
318 what point it had to terminate parsing of the zone file.
319 If MaraDNS does return a cryptic error message without letting you know
321 what is wrong, let me know so that I can fix the bug. MaraDNS is
322 designed to be easy to use; cryptic error messages go against this
323 spirit.
324 10. After I start MaraDNS, I can not see the process when I run netstat
326 -na
327 Udp services do not have a prominent "LISTEN" when netstat is run.
329 When MaraDNS is up, the relevant line in the netstat output looks like
331 this: udp 0 0 127.0.0.1:53 0.0.0.0:*
332 While on the topic of netstat, if you run netstat -nap as root on Linux
334 and some other *nix operating systems, you can see the names of the
335 processes which are providing internet services.
336 11. What string library does MaraDNS use?
338 MaraDNS uses its own string library, which is called the "js_string"
340 library. Man pages for most of the functions in the js_string library
341 are in the folder doc/man of the MaraDNS distribution
342 12. Why does MaraDNS use a multi-threaded model?
344 The multi-threaded model is, plain and simple, the simplest way to
346 write a functioning recursive DNS server. There is a reason why
347 MaraDNS, pdnsd, and BIND 9 all use the multi-threaded model.
348 I am planning on improving MaraDNS' threaded model to not spawn a
350 thread for each and every uncached request.
351 13. I feel that XXX feature should be added to MaraDNS
353 The only thing that will convince me to implement a given feature for
355 MaraDNS is cold, hard cash. If you want me to keep a given feature
356 proprietary, you better have lots of cold hard cash. If you're willing
357 to opensource your feature, less cash should be sufficient.
358 Keep in mind that both the BIND and NSD name servers were developed by
360 having the programmers paid to work on the programs. PowerDNS was
361 originally commercial software with the author only reluctantly made
362 GPL after seeing that the market for a commercial DNS server is very
363 small. All of the other DNS servers which have been developed as
364 hobbyist projects (Posadis, Pdnsd, and djbdns) are no longer being
365 actively worked on by the primary developer.
366 My current plans for MaraDNS are visible on the roadmap page for
368 MaraDNS.
369 If I see a large MaraDNS community and a strong demand for new features
371 from that community, I will consider their wishes. Especially if some
372 of the members of the community have large bank accounts. Should ipv6
373 start to become dominant, I will update MaraDNS to have full ipv6
374 support. Should some other technology come along that will require an
375 update to MaraDNS for MaraDNS to continue to function as a DNS server,
376 I may very well update MaraDNS to use that technology.
377 14. I feel that MaraDNS should use another documentation format
379 The reason that MaraDNS uses its own documentation format is to satisfy
381 both the needs of translators to have a unified document format and my
382 own need to use a documentation format that is simple enough to be
383 readily understood and which I can add features on an as needed basis.
384 The documentation format is essentially simplified HTML with some
386 special tags added to meet MaraDNS' special needs.
387 This gives me more flexibility to adapt the documentation format to
389 changing needs. For example, when someone pointed out that it's not a
390 good idea to have man pages with hi-bit characters, it was a simple
391 matter to add a new HIBIT tag which allows man pages to be without hi-
392 bit characters, and other document formats to retain hi-bit characters.
393 Having a given program have its own documentation format is not without
395 precedent; Perl uses its own "pod" documentation format.
396 15. Is there any process I need to follow to add a patch to MaraDNS?
398 Yes.
400 Here is the procedure for making a proper patch:
402 * Enter the directory that the file is in, for example
404 maradns-1.2.00/server
405 * Copy over the file that you wish to modify to another file name. For
407 example: cp MaraDNS.c MaraDNS.c.orig
408 * Edit the file in question, e.g: vi MaraDNS.c
410 * After editing, do something like this:
412 diff -u MaraDNS.c.orig MaraDNS.c > maradns.patch
413 * Make sure the modified version compiles cleanly
415 Send a patch to me in email, along with a statement that you place the
417 contents of the patch under MaraDNS' BSD license. If I find that the
418 patch works well, I will integrate it in to MaraDNS.
419 16. Can MaraDNS act as a primary nameserver?
421 Yes.
423 The zoneserver program serves zones so that other DNS servers can be
425 secondaries for zones which MaraDNS serves. This is a separate program
426 from the maradns server, which processes both authoritative and
427 recursive UDP DNS queries.
428 See the DNS master document in the MaraDNS tutorial for details.
430 17. Can MaraDNS act as a secondary nameserver?
432 Yes.
434 Please read the DNS slave document, which is part of the MaraDNS
436 tutorial.
437 18. What is the difference between an authoritative and a recursive DNS
439 server?
440 A recursive DNS server is a DNS server that is able to contact other
442 DNS servers in order to resolve a given domain name label. This is the
443 kind of DNS server one points to in /etc/resolve.conf
444 An authoritative DNS server is a DNS server that a recursive server
446 contacts in order to find out the answer to a given DNS query.
447 19. The fetchzone client isn't allowing me to add certain hostnames to my
449 zone
450 For security reasons, MaraDNS' fetchzone client does not add records
452 which are not part of the zone in question. For example, if someone has
453 a zone for example.com, and this record in the zone:
454 1.1.1.10.in-addr.arpa. PTR dns.example.com.
456 MaraDNS will not add the record, since the record is out-of-bailiwick.
458 In other words, it is a host name that does not end in .example.com.
459 There are two workarounds for this issue:
461 * Create a zone file for 1.1.10.in-addr.arpa., and put the PTR records
463 there.
464 * Use rcp, rsync, or another method to copy over the zone files in
466 question.
467 20. Is MaraDNS portable?
469 MaraDNS is developed on a CentOS 3 and Windows XP dual boot laptop.
471 MaraDNS may compile or run on other systems--there are official MaraDNS
472 ports for Debian/Ubuntu, Slackware, FreeBSD, and NetBSD. Note that
473 MaraDNS needs a system with a robust threading library, which some
474 systems do not have.
475 21. Can I use MaraDNS in Windows?
477 Yes. There is both a partial mingw32 (native win32 binary) port and a
479 full Cygwin port of MaraDNS; both of these ports are part of the native
480 build of MaraDNS.
481 22. MaraDNS freezes up after being used for a while
483 If you are using MaraDNS 1.2.03.1 (or any 1.1 release, for that matter)
485 on Linux, upgrade to version 1.2.03.2. There is a bug with the Linux
486 kernel which causes UDP clients to freeze unless code is written to
487 work around the kernel bug. This workaround was first introduced in
488 MaraDNS 1.0.28 and 1.1.35 and accidently disabled in 1.2.03.1.
489 If using your ISP's name servers or some other name servers which are
491 not, in fact, root name servers, please make sure that you are using
492 the upstream_servers dictionary variable instead of the root_servers
493 dictionary variable.
494 If you still see MaraDNS freeze up after making this correction, please
496 send a bug report to the mailing list.
497 23. What kind of Python integration does MaraDNS have
499 The mararc file uses the same syntax that Python uses; in fact, Python
501 can parse a properly formatted mararc file.
502 There is currently no other integration with Python.
504 24. Doesn't "kvar" mean "four" in Esperanto?
506 Indeed, it does. However the use of "kvar" in the MaraDNS source code
508 only coincidentally is an Esperanto word. "kvar" is short for "Kiwi
509 variable"; a lot of the parsing code comes from the code used in the
510 Kiwi spam filter project.
511 25. How scalable is MaraDNS?
513 MaraDNS is optimized for serving a small number of domains as quickly
515 as possible. That said, MaraDNS is remarkably efficnent for serving a
516 large number of domains, as long as the server MaraDNS is on has the
517 memory to fit all of the domains, and as long as the startup time for
518 loading a large number of domains can be worked around.
519 The "big-O" or "theta" growth rates for various MaraDNS functions are
521 as follows, where N is the number of authoritative host names being
522 served:
523 Startup time N
525 Memory usage N
526 Processing incoming DNS requests 1
527 As can be seen, MaraDNS will process 1 or 100000 domains in the same
529 amount of time, once the domain names are loaded in to memory.
530 26. I am having problems setting upstream_servers
532 The upstream_servers mararc variable is set thusly:
534 upstream_servers["."] = "10.3.28.79, 10.2.19.83"
536 Note the ["."]. The reason for this is so future versions of MaraDNS
538 may have more fine-grained control over the upstream_servers and
539 root_servers values.
540 Note that the upstream_servers variable needs to be initialized before
542 being used via upstream_servers = {} (the reason for this is so that a
543 mararc file has 100% Python-compatible syntax). A complete mararc file
544 that uses upstream_servers may look like this:
545 ipv4_bind_addresses = "127.0.0.1"
547 chroot_dir = "/etc/maradns"
548 recursive_acl = "127.0.0.1/8"
549 upstream_servers = {}
550 upstream_servers["."] = "10.1.2.3, 10.2.4.6"
551 27. Why doesn't the MaraDNS.org web page validate?
553 HTML pages on the MaraDNS.org web site should validate as HTML 4.0
555 Transitional. However, the CSS will not validate.
556 I have designed MaraDNS' web page to be usable and as attractive as
558 possible in any major browser released in the last ten years. Cross-
559 browser support is more important than strict W3 validation. The reason
560 why the CSS does not validate is because I need a way to make sure
561 there is always a scrollbar on the web page, even if the content is not
562 big enough to merit one; this is to avoid the content jumping from page
563 to page. There is no standard CSS tag that lets me do this. I'm using a
564 non-standard tag to enable this in Gecko (Firefox's rendering engine);
565 this is enabled by default in Trident (Internet Explorer's rendering
566 engine). The standards are deficient and blind adherence to them would
567 result in an inferior web site.
568 There are also two validation warnings generated by redefinitions which
570 are needed as part of the CSS filters used to make the site attractive
571 on older browsers with limited CSS support.
572 On a related note, the reason why I use tables instead of CSS for some
574 of the layout is because Microsoft Internet Explorer 6 and other
575 browsers do not have support for the max-width CSS property. Without
576 this property, the web page will not scale down correctly without using
577 tables. Additionally, tables allow a reasonably attractive header in
578 browsers without CSS support.
579 28. How do MX records work?
581 How MX records work:
583 * The mail transport agent (Sendmail, Postfix, Qmail, MS Exchange,
585 etc.) looks up the MX record for the domain
586 * For each of the records returned, the MTA (mail transport agent)
588 looks up the IP for the names.
589 * It will choose, at random, any of the MXes with the lowest priority
591 number.
592 * Should that server fail, it will try another server with the same
594 priority number.
595 * Should all MX records with a given priority number fail, the MTA will
597 try sending email to any of the MX records with the second-lowest
598 priority value.
599 As an aside, do not have MX records point to CNAMEs.
601 29. Does MaraDNS have support for SPF?
603 SPF, or sender policy framework, is method of using DNS that makes it
605 more difficult to forge email. MaraDNS has full support for SPF, both
606 via TXT records and, starting with MaraDNS 1.2.08, via RFC4408 SPF
607 records.
608 SPF configuration is beyond the scope of MaraDNS' documentation.
610 However, at the time of this FAQ entry being written (June, 2006),
611 information and documentation concerning SPF is available at
612 http://openspf.org. The BIND examples will work in MaraDNS csv2 zone
613 files as long as the double quotes (") are replaced by single quotes
614 ('). For example, a SPF TXT record that looks like example.net. IN TXT
615 "v=spf1 +mx a:colo.example.com/28 -all" in a BIND zone file will look
616 like example.net. TXT 'v=spf1 +mx a:colo.example.com/28 -all' in a
617 MaraDNS zone file. MaraDNS version 1.2.08 and higher can also make the
618 corresponding SPF record, which will have the syntax example.net. SPF
619 'v=spf1 +mx a:colo.example.com/28 -all'.
620 30. I'm having problems resolving CNAMES I have set up.
622 This is probably because you have set up what MaraDNS calls a dangling
624 CNAME record.
625 Let us suppose we have a CNAME record without an A record in the local
627 DNS server's database, such as:
628 google.example.com. CNAME www.google.com. ~
630 This record, which is a CNAME record for "google.example.com", points
632 to "www.google.com". Some DNS servers will recursively look up
633 www.google.com, and render the above record like this:
634 google.example.com. CNAME www.google.com. ~
636 www.google.com. CNAME 66.102.7.104 ~
637 For security reasons, MaraDNS doesn't do this. Instead, MaraDNS will
639 simply output:
640 google.example.com. CNAME www.google.com. ~
642 Some stub resolvers will be unable to resolve google.example.com as a
644 consequence.
645 If you set up MaraDNS to resolve CNAMEs thusly, you will get a warning
647 in your logs about having a dangling CNAME record.
648 If you want to remove these warnings, add the following to your mararc
650 file:
651 no_cname_warnings = 1
653 Information about how to get MaraDNS to resolve dangling CNAME records
655 is in the tutorial file dangling.html
656 I have a NS delegation, and MaraDNS is doing strange things.
658 In the case of there being a NS delegation, MaraDNS handles recursive
660 queries and non-recursive DNS queries differently. Basically, unless
661 you use askmara with the -n option, dig with the +norecuse option, or
662 nslookup with the -norec option, MaraDNS will try to recursively
663 resolve the record that is delegated.
664 The thinking is this: A normal recursive DNS query is usually one where
666 one wants to know the final DNS output. So, if MaraDNS delegates a
667 given record to another DNS server, and gets a recursive request for
668 said query, MaraDNS will recursively resolve the query for you.
669 For example, let us suppose we have a mararc file that looks like this:
671 chroot_dir = "/etc/maradns"
673 ipv4_bind_addresses = "10.1.2.3"
674 chroot_dir = "/etc/maradns"
675 recursive_acl = "127.0.0.1/8, 10.0.0.0/8"
676 csv2 = {}
677 csv2["example.com."] = "db.example.com"
678 And a db.example.com file that looks like this:
680 www.example.com. 10.1.2.3 ~
682 joe.example.com. NS ns.joe.example.com. ~
683 ns.joe.example.com. A 10.1.2.4 ~
684 Next, you are trying to find out why www.joe.example.com is not
686 resolving. If you naively send a query to 10.1.2.3 for
687 www.joe.example.com as askmara Awww.joe.example.com. 10.1.2.3 or as dig
688 @10.1.2.3 www.joe.example.com. or as nslookup www.joe.example.com.
689 10.1.2.3, you will not get any information that will help you solve the
690 problem, since 10.1.2.3 will try to contact 10.1.2.4 to resolve
691 www.joe.example.com.
692 The solution is to run your DNS query client thusly:
694 * Askmara would be run thusly:
696 askmara -n Awww.joe.example.com. 10.1.2.3
698 * Dig would be run thusly:
700 dig +norecurse @10.1.2.3 www.joe.example.com
702 * Nslookup would be run thusly:
704 nslookup -norec www.joe.example.com 10.1.2.3
706 This will allow you to see that packets MaraDNS actually sends to a
708 recursive DNS server.
709 As an aside, this particular problem will not happen if MaraDNS is run
711 only as an authoritative nameserver.
712 I am transferring a zone from another server, but the NS records are these
714 strange "synth-ip" records.
715 MaraDNS expects, in csv2 zone files, for all delegation NS records to
717 be between the SOA record and the first non-NS record.
718 If a zone looks like this:
720 example.net. +600 soa ns1.example.net. hostmaster@example.net
722 10 10800 3600 604800 1080 ~
723 example.net. +600 mx 10 mail.example.net. ~
724 example.net. +600 a 10.2.3.5 ~
725 example.net. +600 ns ns1.example.net. ~
726 example.net. +600 ns ns3.example.net. ~
727 mail.example.net. +600 a 10.2.3.7 ~
728 www.example.net. +600 a 10.2.3.11 ~
729 Then the NS records will be "synth-ip" records.
731 The zone should look like this:
733 example.net. +600 soa ns1.example.net. hostmaster@example.net
735 10 10800 3600 604800 1080 ~
736 example.net. +600 ns ns1.example.net. ~
737 example.net. +600 ns ns3.example.net. ~
738 example.net. +600 mx 10 mail.example.net. ~
739 example.net. +600 a 10.2.3.5 ~
740 mail.example.net. +600 a 10.2.3.7 ~
741 www.example.net. +600 a 10.2.3.11 ~
742 This will remove the "synth-ip" records.
744 To automate this process, this awk script is useful:
746 fetchzone whatever.zone.foo 10.1.2.3 | awk '
748 {if($3 ~ /ns/ || $3 ~ /soa/){print}
749 else{a = a "\n" $0}}
750 END{print a}' > zonefile.csv2
751 Replace "whatever.zone.foo" with the name of the zone you are fetchin
753 10.1.2.3 with the IP address of the DNS master, and zonefile.csv2 with
754 the name of the zone file MaraDNS loads.
755 Where is the root.hints file?
757 MaraDNS, unlike BIND, does not need a complicated root.hints file in
759 order to have custom root servers. In order to change the root.hints
760 file, add something like this to your mararc file:
761 root_servers["."] = "131.161.247.232,"
763 root_servers["."] += "208.185.249.250,"
764 root_servers["."] += "66.227.42.140,"
765 root_servers["."] += "66.227.42.149,"
766 root_servers["."] += "65.243.92.254"
767 Note that there is no "+=" in the first line, and the last line does
769 not have a comma at the end. Read the recursive tutorial document for
770 more information.
771 Are there any plans to use autoconf to build MaraDNS?
773 No. OK, let me qualify that: I won't do it unless you pay me enough
775 money.
776 In more detail, MaraDNS does not use autoconf for the following
778 reasons:
779 * Autoconf is designed to solve a problem that existed in the mid 1990s
781 but does not exist today: A large number of different incompatible C
782 compilers and libc implementations. These days, most systems are
783 using gcc as the compiler and some version of glibc as the libc.
784 There is no longer a need, for example, to figure out whether a given
785 implementation of getopt() allows '--' options. MaraDNS's
786 ./configure script can be run in only a second or two; compare this
787 to the 3-5 minute process autoconf's ./configure needs.
788 * Autoconf leaves GPL-tained files in a program's build tree. MaraDNS
790 is licensed under a BSD license that is not GPL-compatible, so
791 MaraDNS can not be distributed with these GPL-licensed files.
792 This leads us to the next question:
794 How do I change the compiler or compile-time flags with MaraDNS' build
796 process?
797 To change the compiler used by MaraDNS:
799 * Run the ./configure script
801 * Open up the file Makefile with an editor
803 * Look for a line that starts with CC
805 * If there is no line that starts with CC, create one just before the
807 line that starts with FLAGS
808 * Change (or create) that line to look something like CC=gcc296 In this
810 example, the 2.96 version of gcc is used to compile MaraDNS.
811 * Note that it is important to not remove anything from this line you
813 do not understand; doing so will make MaraDNS unable to compile or
814 run. So, if the CC line looks like
815 CC=gcc $(LDFLAGS) -DNO_FLOCK and you want to compile with
816 gcc 2.96, change the line to look like
817 CC=gcc296 $(LDFLAGS) -DNO_FLOCK retaining the flags added
818 by the configuration script.
819 Changing compile-time flags is a similar process:
821 * Run the ./configure script
823 * Open up the file Makefile with an editor
825 * Look for a line that starts with FLAGS
827 * Change (or create) that line to look something like FLAGS=-O3 In this
829 example, MaraDNS is compiled with the -O3 option.
830 * Note that it is important to not remove anything from this line you
832 do not understand; doing so will make MaraDNS unable to compile or
833 run. So, if the FLAGS line looks like
834 FLAGS=-O2 -Wall -DSELECT_PROBLEM and you want to compile at
835 optimization level three, change this line to look like
836 FLAGS=-O2 -Wall -DSELECT_PROBLEM retaining the flags added
837 by the configuration script. -DSELECT_PROBLEM for example, is needed
838 in the Linux compile or MaraDNS will have problems with freezing up.
839 Will you make a package for the particular Linux distribution I am using?
841 No. OK, let me qualify that: I won't do it unless you pay me enough
843 money.
844 There are MaraDNS packages for a number of different distributions of
846 Linux and other operating systems. On the MaraDNS site, there is a
847 MaraDNS package for CentOS/Red Hat Enterprise Linux available. There is
848 also usually an up-to-date Slackware package available. In addition,
849 there is a Debian package in the Debian packages collection, a FreeBSD
850 port of MaraDNS, a Ubuntu package which is derived from the Debian
851 package, and undoubtably other MaraDNS packages floating around the
852 internet.
853 If you wish to have a package for your particular version of Linux (or
855 MacOS X or BSD or...), you can use one of the above packages as a
856 starting point for making your package. For example, other RPM-based
857 distributions can use the CentOS RPM package as a baseline (the .spec
858 file is in the build/ directory). I can not help you with any problems
859 you may encounter making this package since I do not have your
860 particular version of Linux installed on my computer.
861 As an aside, some of the MaraDNS packages floating around on the
863 internet are out of date (*cough*, Debian, *cough*)<sup><font
864 size=-2>1</font></sup>. Please make sure, that if you get a third-party
865 package from the internet, the package is for either MaraDNS 1.0.41,
866 MaraDNS 1.2.12.08, or MaraDNS 1.3.07.05. Older versions of MaraDNS are
867 not supported.
868 Footnote 1: Debian has a somewhat silly policy that, once a package is
870 declared "stable", they will basically not update it unless there is a
871 Bugtraq security advisory for the package in question. This policy is a
872 good policy for programs made by pimply-faced 16-year-olds who don't
873 know how to manage a release cycle nor a bugfix-only branch, but
874 doesn't make sense for MaraDNS. As I write this, the Debian's "stable"
875 version of MaraDNS is 1.2.12.04, which is about a year behind in terms
876 of bugfixes. I, annoyingly enough, get bug reports from Debian users
877 telling me about bugs I have already fixed in the 1.2 branch of
878 MaraDNS.
879 Now, to be fair to Debian, their policies do allow me to backport
881 bugfixes to the 1.2.12.04 release of MaraDNS, and the patches do get
882 reviewed by somone else, which minimizes bugfixes introducing new bugs
883 (Yes, I have done that), but there are not enough volunteers to review
884 all of the bugfixes I have made since 1.2.12.04. So, Debian users get
885 stuck with an old, buggy version of MaraDNS. The policy would work if
886 there were enough volunteers to actually review all of my
887 post-1.2.12.04 bugfixes, but the people who created the policy did not
888 take in to account the logistics of volunteer work.
889 I am using the native Windows port of MaraDNS, and some features are not
891 working.
892 Since Windows 32 does not have some features that *NIX OSes have, the
894 native Windows port does not have all of the features of the *NIX
895 version of MaraDNS. In particular, the following features are disabled:
896 * ipv6 (this is actually a mingw32, not a Windows deficiency)
898 * The chroot_dir mararc variable
900 * The maradns_gid and maradns_uid mararc variables
902 * The maxprocs mararc variable
904 * The synth_soa_serial variable can not have a value of 2
906 If any of the above features are desired, try compiling MaraDNS using
908 Cygwin. Note that the Cygwin port of MaraDNS does not have ipv6
909 support, and that while chroot_dir works in Cygwin, it does not have
910 the security that the *NIX chroot() call has.
911 MaraDNS isn't starting up
913 This is usually caused by a syntax error in one's mararc file, or by
915 another MaraDNS process already running. To see what is happening, look
916 at your system log (/var/log/messages in Centos 3) to see what errors
917 MaraDNS reports. If you do not know how to look at a system log, you
918 can also invoke MaraDNS from the command line as root; any errors will
919 be visible when starting MaraDNS.
920 You make a lot of releases of MaraDNS; at our ISP/IT department, updating
922 software is non-trivial.
923 The number of releases seen in the changelog is not an accurate
925 reflection of how often someone using a stable branch of MaraDNS will
926 need to update.
927 There were only three updates to the 1.0 legacy branch in 2006, and (so
929 far) only two updates to the 1.0 branch in 2007. The 1.2 branch was
930 updated frequently in the first half of 2006, since I felt MaraDNS 1.2
931 needed some features that didn't make it in to 1.2.00. During this
932 update cycle, there was always a stable bugfix-only branch of MaraDNS.
933 In August of 2006, I stabilized the 1.2 branch and only five updates
935 have been done since then. Unless there is a critical bug, I only will
936 update the 1.2 branch approximately once every six months or so.
937 I go to a great deal of effort to make sure MaraDNS releases are as
939 painless to update as possible. I ensure configuration file format
940 compatibility, even between major versions of MaraDNS. With the
941 exception of configuration file parser bugfixes, MaraDNS 1.0
942 configuration files are compatible with MaraDNS 1.2 and 1.3.
943 It is impossible to make code that is bug-free or without security
945 problems. This is especially true with code that runs on the public
946 internet.<sup><font size=-2>1</font></sup> Code has to be updated from
947 time to time. What I do in order to minimize the disruption caused by
948 an update is to always have a stable bugfix-only branch of MaraDNS
949 (right now I have three bugfix-only branches), and to, as much as
950 possible, evenly space out the bugfix updates.
951 Footnote 1: Even DJB's code has security problems. Both Qmail and
953 DjbDNS have known security problems, and need to be patched before put
954 on a public internet server.
955
957 In the unusual case of having a csv2 zone file with Macintosh-style
958 newlines (as opposed to DOS or UNIX newlines), while the file will
959 parse, any errors in the file will be reported as being on line 1.
960 The maximum allowed number of threads is 5000.
962 The system startup script included with MaraDNS assumes that the only
964 MaraDNS processes running are started by the script; it stops all
965 MaraDNS processes running on the server when asked to stop MaraDNS.
966 When a resolver asks for an A record, and the A record is a CNAME which
968 points to a list of IPs, MaraDNS' recursive resolver only returns the
969 first IP listed along with the CNAME. This is somewhat worked around by
970 having a CNAME record only stay in the recursive cache for 15 minutes.
971 When a resolver asks for an A record, and the A record is a CNAME that
973 points to another CNAME (and possibly a longer CNAME chain), while
974 MaraDNS returns the correct IP (as long as the glueless level is not
975 exceeded), MaraDNS will incorrectly state that the first CNAME in the
976 chain directly points to the IP.
977 If a NS record points to a list of IPs, and the NS record in question
979 is a "glueless" record (MaraDNS had to go back to the root servers to
980 find out the IP of the machine in question), MaraDNS' recursive
981 resolver only uses the first listed IP as a name server.
982 When MaraDNS' recursive resolver receives a "host not there" reply,
984 instead of using the SOA minimum of the "host not there" reply as the
985 TTL (Look at RFC1034 section 4.3.4), MaraDNS uses the TTL of the SOA
986 reply.
987 MaraDNS keeps referral NS records in the cache for one day instead of
989 the TTL specified by the remote server.
990 MaraDNS needs to use the zoneserver program to serve DNS records over
992 TCP. See zoneserver(8) for usage information.
993 MaraDNS does not use the zone file ("master file") format specified in
995 chapter 5 of RFC1035.
996 MaraDNS default behavior with star records is not RFC-compliant. In
998 more detail, if a wildcard MX record exists in the form
999 "*.example.com", and there is an A record for "www.example.com", but no
1000 MX record for "www.example.com", the correct behavior (based on RFC1034
1001 section 4.3.3) is to return "no host" (nothing in the answer section,
1002 SOA in the authority section, 0 result code) for a MX request to
1003 "www.example.com". Instead, MaraDNS returns the MX record attached to
1004 "*.example.com". This can be changed by setting bind_star_handling to
1005 1.
1006 Star records (what RFC1034 calls "wildcards") can not be attached to NS
1008 records.
1009 MaraDNS recursive resolver treats any TTL shorter than min_ttl seconds
1011 (min_ttl_cname seconds when the record is a CNAME record) as if the TTL
1012 in question was min_ttl (or min_ttl_cname) seconds long when
1013 determining when to expire a record from MaraDNS' cache.
1014 TTLs which are shorter than 20 seconds long are given a TTL of 20
1016 seconds; TTLs which are more than 63072000 (2 years) long are given a
1017 TTL of 2 years.
1018 MaraDNS' recursive resolver's method of deleting not recently accessed
1020 records from the cache when the cache starts to fill up can deleted
1021 records from the cache before they expire. Some people consider this
1022 undesirable behavior; I feel it is necessary behavior if one wishes to
1023 place a limit on the memory resources a DNS server may use.
1024 MaraDNS' recursive resolver stops resolving when it finds an answer in
1026 the AR section. This is a problem in the case where a given host name
1027 and IP is registered with the root name servers, and the registered IP
1028 is out of date. When this happens, a server "closer" to the root server
1029 will give an out-of-date IP, even though the authoritative DNS servers
1030 for the host in question have the correct IP. Note that resolving this
1031 will result in increased DNS traffic.
1032 MaraDNS, like every other known DNS implementation, only supports a
1034 QDCOUNT of 0 or 1.
1035 MaraDNS spawns a new thread for every single recursive DNS request when
1037 the data in question is not in MaraDNS' cache; this makes MaraDNS an
1038 excellent stress tester for pthread implementations. Many pthread
1039 implementations can not handle this kind of load; symptoms include high
1040 memory usage and termination of the MaraDNS process.
1041 MaraDNS does not handle the case of a glueless in-bailiwick NS referral
1043 very gracefully; this usually causes the zone pointed to by the
1044 offending NS record to be unreachable by MaraDNS, even if other DNS
1045 servers for the domain have correct NS referrals.
1046
1048 These are features which will not be implemented in the 1.2 release of
1049 MaraDNS:
1050 MaraDNS does not have a disk-based caching scheme for authoritative
1052 zones.
1053 MaraDNS' UDP server only loads zone files while MaraDNS is first
1055 started. UDP Zone information can only be updated by stopping MaraDNS,
1056 and restarting MaraDNS again. Note that TCP zone files are loaded from
1057 the filesystem at the time the client requests a zone.
1058 MaraDNS does not have support for allowing given host names to only
1060 resolve for a limited range of IPs querying the DNS server, or for host
1061 names to resolve differently, depending on the IP querying the host
1062 name.
1063 MaraDNS only has limited authoritative-only support for IPv6.
1065 MaraDNS only allows wildcards at the beginning or end of a host name.
1067 E.g. names with wildcards like "foo.*.example.com". "www.*" will work,
1068 however, if a default zonefile is set up.
1069 MaraDNS does not have support for MRTG or any other SNMP-based logging
1071 mechanism.
1072
1074 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR
1075 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1076 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1077 DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
1078 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
1079 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
1080 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1081 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
1082 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
1083 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1084 POSSIBILITY OF SUCH DAMAGE.
1085
1087 Sam Trenholme (http://www.samiam.org) is responsible for this man page.
1088 MaraDNS is written by me, Sam Trenholme, with a little help from my
1090 friends. Naturally, all errors in MaraDNS are my own (but read the
1091 disclaimer above).
1092 Here is a partial list of people who have provided assistance:
1094 Floh has generously set up a FreeBSD 4, FreeBSD 6, and Mac OS X system
1096 so that I can port MaraDNS to more platforms.
1097 Albert Lee has provided countless bug reports, and, nicely enough,
1099 patches to fix said bugs. He has also made improvements to the code in
1100 the tcp "zoneserver".
1101 Franky Van Liedekerke has provided much invaluable assistance. As just
1103 one example, he provided invaluable assistance in getting MaraDNS to
1104 compile on Solaris. In addition, he has provided much valuable SQA
1105 help.
1106 Christian Kurz, who has provided invaluable bug reports, especially
1108 when I had to re-implement the core hashing algorithm.
1109 Remmy, who is providing both the web space and a mailing list for
1111 maradns.org.
1112 Phil Homewood, who provided invaluable assistance with finding and
1114 fixing bugs in the authoritative portion of the MaraDNS server. He
1115 helped me plug memory leaks, find uninitialized variables being used,
1116 and found a number of bugs I was unable to find.
1117 Albert Prats kindly provided Spanish translations for various text
1119 files.
1120 Shin Zukeran provided a patch to recursive.c which properly makes a
1122 normal null-terminated string from a js_string object, to send as an
1123 argument to open() so we can get the rijndael key for the PRNG.
1124 D Richard Felker III has provided invaluable bug reports. By looking at
1126 his bug reports, I have been able to hunt down and fix many problems
1127 that the recursive nameserver had, in addition to at least one problem
1128 with the authoritative nameserver.
1129 Ole Tange has also given me many valuable MaraDNS bug reports.
1131 Florin Iucha provided a tip in the FAQ for how to compile MaraDNS on
1133 OpenBSD.
1134 Roy Arends (one of the BIND developers, as it turns out) found a
1136 serious security problem with MaraDNS, where MaraDNS would answer
1137 answers, and pointed it out to me.
1138 Code used as the basis for the psudo-random-number generator was
1140 written by Vincent Rijmen, Antoon Bosselaers, and Paulo Barreto. I
1141 appreciate these programmers making the code public domain, which is
1142 the only license under which I can add code to MaraDNS under.
1143 Ross Johnson and others have made a Win32 port of the Pthreads library;
1145 this has made a native win32 port of MaraDNS possible.
1146 I also appreciate the work of Dr. Brian Gladman and Fritz Schneider,
1148 who have both written independent implementations of AES from which I
1149 obtained test vectors. With the help of their hard work, I was able to
1150 discover a subtle security problem that previous releases of MaraDNS
1151 had.
1152MARADNS January 2002 MARADNS(8)