1MARARC(5) MaraDNS reference MARARC(5)
2
6 mararc - Format of the mararc zone file that MaraDNS uses
7
9 Mararc files use a syntax that is a subset of Python 2.2.3 syntax. In
10 particular, Python 2.2.3 (and possibly other versions of Python) can
11 read a properly formatted mararc file without error.
12 Unlike Python, however, a mararc file can only use certain variable
14 names, and the variables can only be declared as described below.
15
17 Comments (lines ignored by the MaraDNS parser) start with the '#'
18 character, like this:
19 # This is a comment
21 The MaraDNS parser also ignores lines which contain only white space.
23
25 The MaraRC file supports two operators: = and +=
26 The = operator can be used to assign both numeric and string values
28 The += operator can only be used on string values, and concatenates the
30 value to the right of the += operator to the string specified to the
31 left of the += operator.
32 Examples:
34 ipv4_bind_addresses = "10.2.19.83"
36 ipv4_bind_addresses += ",10.2.66.74"
37 ipv4_bind_addresses += ",10.3.87.13"
38 ipv4_bind_addresses now has the value
40 "10.2.19.83,10.2.66.74,10.3.87.13"
41 ipv4_alias["icann"] = "198.41.0.4"
43 ipv4_alias["icann"] += ",192.228.79.201"
44 ipv4_alias["icann"] += ",192.33.4.12,128.8.10.90"
45
48 Follows is a listing of variables that can be declared in the mararc
49 file.
50
52 A dictionary variable is an array that can have multiple elements.
53 Unlike a traditional array, these arrays are indexed by strings instead
54 of numbers. These are analogous to associative arrays, or what Perl
55 somewhat inaccurately calls hashes.
56 The syntax of a dictionary variable is in the following form:
58 name["index"] = "value"
60 Where name is the name of the dictionary variable, index is the index
62 of the array, and value is the value stored at that index.
63 Every time we have a dictionary-type variable (such as csv2), we must
65 first initialize it using a line in the following form:
66 csv2 = {}
68 Here, csv2 is the name of the "dictionary" variable that we are
70 initializing.
71
73 Here is a listing of all "dictionary"-style variables that MaraDNS
74 uses:
75 csv2
77 The csv2 dictionary variable stores all of the zone names and file
79 names for the zone files that MaraDNS uses. Note that csv2 files are
80 read after MaraDNS is chrooted. Hence the filename is relative to the
81 chroot_dir. Example:
82 csv2["example.net."] = "db.example.net"
84 See csv2(5) for a description of this file's format.
86 csv1
88 csv1: Used to indicate the filename to use for a given zone stored in
90 the legacy csv1 zone file format. This is primarily for compatibility
91 with people who have maradns-1.0 zone files.
92 csv1["zone"] = "filename"
94 csv1: A pipe-separated-file. See csv1(5).
96 zone: the zone that file in question is authoritative for
98 filename: the file with the CSV1 zone data
100 Note that csv1 files are read after MaraDNS is chrooted, and, hence the
102 filename is relative to the chroot_dir.
103 See the csv1(5) man page for more information on this file format.
105 ipv4_alias
107 ipv4_alias: Used to give nicknames or aliases for ip/netmask pairs for
109 ipv4 (standard 32-bit) IP addresses.
110 ipv4_alias["name"] = "ip1/netmask,ip2/netmask,etc"
112 name: The name of the alias in question
114 ip: The ip portion of an ip/netmask pair
116 netmask: the mask portion of an ip/netmask pair
118 ,: Used to separate ip/netmask pairs. Spaces may be placed before or
120 after this comma.
121 An ip is in dotted-decimal format, e.g. "10.1.2.3".
123 The netmask can be in one of two formats: A single number between 1 and
125 32, which indicates the number of leading "1" bits in the netmask, or a
126 4-digit dotted-decimal netmask.
127 The netmask is used to specify a range of IPs.
129 ipv4_alias examples
131 10.1.1.1/24 indicates that any ip from 10.1.1.0 to 10.1.1.255 will
133 match.
134 10.1.1.1/255.255.255.0 is identical to 10.1.1.1/24
136 10.2.3.4/16 indicates that any ip from 10.2.0.0 to 10.2.255.255 will
138 match.
139 10.2.3.4/255.255.0.0 is identical to 10.2.3.4/16
141 127.0.0.0/8 indicates that any ip with "127" as the first octet
143 (number) will match.
144 127.0.0.0/255.0.0.0 is identical to 127.0.0.0/8
146 The netmask is optional, and, if not present, indicates that only a
148 single IP will "match". e.g:
149 10.9.9.9/32, 10.9.9.9/255.255.255.255, and 10.9.9.9 are all
151 functionally identical, and indicate that only the ip 10.9.9.9 will
152 match.
153 The significance of "match" depends on what we use the ipv4 alias for.
155 ipv4 aliases can nest. E.g:
157 ipv4_alias["susan"] = "10.6.7.8/24"
159 ipv4_alias["office"] = "susan,10.9.9.9"
160 Where "susan" in the "office" alias matches the value of the ipv4_alias
162 susan.
163 Multiple levels of nesting are allowed. Self-referring nests will
165 result in an error.
166 root_servers
168 root_servers: This is a special "dictionary" element that can have
170 multiple elements, where a given element points to either an ip, or a
171 pointer to an ipv4 alias. For example:
172 root_servers["."] = "list_of_servers"
174 In this example, "." indicates that this is a listing of root_servers
176 that will resolve any name not otherwise listed as a root_servers
177 entry.
178 list_of_servers is a list of root name servers in the exact same format
180 as ipv4_aliases.
181 The root_servers dictionary array can have multiple elements. Like csv2
183 elements, the names must be valid domain names that end with the '.'
184 character. When there are multiple root_servers elements, the element
185 with the most domain name labels that matches the end of the hostname
186 one is searching for is used.
187 For exmaple, let us suppose we have the following root_servers entries:
189 root_servers["."] = "198.41.0.4"
191 root_servers["com."] = "192.5.6.30"
192 root_servers["example.net."] = "10.1.2.3,10.2.3.4"
193 In this example, we use use the name server with the IP 10.1.2.3 or
195 10.2.3.4 to start resolving "www.example.net", the name server with the
196 IP 192.5.6.30 to start resolving "www.google.com", and the name server
197 with the IP 198.41.0.4 to start resolving "www.maradns.org".
198 Note that, while ips in a listing of root name servers can have
200 netmasks, the netmask portion is ignored.
201 The root_servers should point to root servers. If one wishes to use
203 MaraDNS as a forwarding name server, which forwards DNS requests on to
204 another server, use the upstream_servers variable instead.
205 upstream_servers
207 This is identical to the root_servers variable (can have multiple
209 elements, the elements are a list of ipv4_addresses, the variable is a
210 dictionary variable, etc.), but is used when one wishes to use MaraDNS
211 to query other recursive servers, instead of querying the actual root
212 name servers for an answer.
213 Note that one can not have both root_servers and upstream_servers set
215 in a given mararc file; MaraDNS will return with a fatal error if one
216 attempts to do this.
217 Like root_servers, this is a dictionary variable that can have multiple
219 elements. For example:
220 upstream_servers["."] = "10.5.6.7"
222 upstream_servers["cl."] = "10.2.19.83"
223 Here, we use 10.2.19.83 to resolve host names that end in "cl", and
225 10.5.6.7 to resolve all other host names.
226
228 Normal variables. These are variables that can only take a single
229 value.
230 The syntax of a normal variable is in the form
232 name = "value"
234 Where name is the name of the normal variable, and value is the value
236 of the variable in question.
237
239 Here is a listing of normal variables that MaraDNS uses:
240 ipv4_bind_addresses
242 ipv4_bind_addresses: The IP addresses to give the MaraDNS server.
244 This accepts one or more ipv4 IPs in dotted-decimal (e.g. "127.0.0.1")
246 notation, and specifies what IP addresses the MaraDNS server will
247 listen on. Multiple bind addresses are separated with a comma, like
248 this: "10.1.2.3, 10.1.2.4, 127.0.0.1"
249 admin_acl
251 This is a list of ip/netmask pairs that are allowed to get certain
253 administrative information about MaraDNS, including:
254 * The version number of MaraDNS running
256 * The number of threads MaraDNS has
258 * MaraDNS' internal timestamp value
260 Note that this information is not available unless the mararc variable
262 debug_msg_level is sufficiently high. See the information on
263 debug_msg_level below for details on this and on the TXT queries sent
264 to get the above information.
265 bind_address
267 bind_address: The IP address to give the MaraDNS server.
269 This accepts a single IP in dotted-decimal (e.g. "127.0.0.1") notation,
271 and specifies what IP address the MaraDNS server will listen on. Note
272 that ipv4_bind_addresses has the same functionality. This name is
273 included so that MaraDNS 1.0 configuration files will continue to work
274 with MaraDNS 1.2.
275 bind_star_handling
277 In the case where there is both a star record for a given name and
279 recordtype, a non-star record with the same name but a different
280 recordtype, and no record for the given name and recordtype, MaraDNS
281 will usually return the star record. BIND, on the other hand, will
282 return a "not there" reply. In other words:
283 * If a non-A record for foo.example.com exists
285 * An A record for *.example.com exists
287 * No A record for foo.example.com exists
289 * And the user asks for the A record for foo.example.com
291 * MaraDNS will usually return the A record attached to *.example.com
293 * BIND, on the other hand, returns a "not there" for foo.example.com
295 If the BIND behavior is desired, set bind_star_handling to 1.
297 Otherwise, set this to 0. In MaraDNS 1.3, this has a default value of
298 1.
299 In addition, if there is a star record that could match any given
301 record type, when bind_star_handling is 1, it makes sure that MaraDNS
302 does not incorrectly return a NXDOMAIN (RFC 4074 section 4.2).
303 Also, if bind_star_handling has a value of 2, MaraDNS will handle the
305 following case exactly as per section 4.3.3 of RFC1034:
306 * If a record for foo.example.com exists
308 * An A record for *.example.com exists
310 * And the user asks for the A record for bar.foo.example.com
312 * MaraDNS will usually return the A record attached to *.example.com
314 * RFC1034 section 4.3.3 says one should return a NXDOMAIN.
316 MaraDNS will exit with a fatal error if bind_star_handling has any
318 value besides 0, 1, or 2.
319 chroot_dir
321 chroot_dir: The directory MaraDNS chroots to
323 This accepts a single value: The full path to the directory to use as a
325 chroot jail.
326 Note that csv1 zone files are read after the chroot operation. Hence,
328 the chroot jail needs to have any and all zone files that MaraDNS will
329 load.
330 csv2_default_zonefile
332 This is a special zone file that allows there to be stars at the end of
334 hostnames. This file is similar to a normal csv2 zone file, but has the
335 following features and limitations:
336 * Stars are allowed at the end of hostnames
338 * A SOA record is mandatory
340 * NS records are mandatory
342 * Neither CNAME nor FQDN4 records are permitted in the zone file
344 * Delegation NS records are not permitted in the zone file
346 * Default zonefiles may not be transferred via zone transfer
348 * Both recursion and default zonefiles may not be enabled at the same
350 time.
351 csv2_synthip_list
353 Sometimes the IP list of nameservers will be different than the
355 nameservers one is bound to. This allows the synthetic nameserver list
356 to have different IPs.
357 Note that this may act in an unexpected manner if routable and non-
359 routable (localhost and RFC1918) addresses are combined; in particular,
360 a list with both routable and non-routable addresses will discard the
361 non-routable IP addresses, and a list with rfc1918 and localhost
362 addresses will discard the localhost addresses.
363 csv2_tilde_handling
365 How the csv2 zone file parser handles tildes (the ~ character) in csv2
367 zone files. This is a numeric record, with a possible value between 0
368 and 3 (four possible values). The way the csv2 parser acts at different
369 csv2_tilde_handling levels:
370 * 0) The csv2 parser behaves the same as it does in MaraDNS 1.2: The
372 tilde has no special significance to the parser.
373 * 1) A tilde is not allowed anywhere in a csv2 zone file.
375 * 2) A tilde is only allowed between records in a csv2 zone file. If a
377 tilde is between the first record and the second record, a tilde is
378 required to be between all records. Otherwise, a tilde is not allowed
379 anywhere in a csv2 zone file. The first record can not be a TXT, WKS,
380 or LOC record.
381 * 3) A tilde is required to be between all records in a csv2 zone file.
383 The default value for csv2_tilde_handling is 2; this allows
385 compatibility with all 1.2 zone files without tildes while allowing
386 zone files to be updated to use the tilde to separate resource records.
387 debug_msg_level
389 This is a number indicating what level of information about a running
391 MaraDNS process should be made public. When set to 0, no information
392 will be made public.
393 When set to one (the default), or higher, a Tversion.maradns. (TXT
395 query for "version.maradns.") query will return the version number of
396 MaraDNS.
397 When set to two or higher, a Tnumthreads.maradns. (TXT query for
399 "numthreads.maradns.") query will return the number of threads that
400 MaraDNS is currently running, and a Tcache-elements.maradns. query
401 will return the number of elements in MaraDNS' cache.
402 If MaraDNS is compiled with debugging information on, a
404 Tmemusage.maradns. query will return the amount of memory MaraDNS has
405 allocated. Note that the overhead for tracking memory usage is
406 considerable and that compiling MaraDNS with "make debug" will greatly
407 slow down MaraDNS. A debug build of MaraDNS is not reccomended for
408 production use.
409 When set to three or higher, a Ttimestamp.maradns. query will return,
411 in seconds since the UNIX epoch, the timestamp for the system MaraDNS
412 is running on.
413 default_rrany_set
416 This variable used to determine what kind of resource records were
418 returned when an ANY query was sent. In MaraDNS 1.2, the data
419 structures have been revised to return any resource record type when an
420 ANY query is sent; this variable does nothing, and is only here so that
421 MaraDNS 1.0 mararc files will continue to work. The only accepted
422 values for this variable were 3 and 15.
423 dns_port
425 This is the port that MaraDNS listens on. This is usually 53 (the
427 default value), but certain unusual MaraDNS setups (such as when
428 resolving dangling CNAME records on but a single IP) may need to have a
429 different value for this.
430 dos_protection_level
432 If this is set to a non-zero value, certain features of MaraDNS will be
434 disabled in order to speed up MaraDNS' response time. This is designed
435 for situtations when a MaraDNS server is receiving a large number of
436 queries, such as during a denial of service attack.
437 This is a numeric variable; its default value is zero, indicating that
439 all of MaraDNS' normal features are enabled. Higher numeric values
440 disable more features:
441 * A dos_protection_level between 1 and 78 (inclusive) disables getting
443 MaraDNS status information remotely.
444 * A dos_protection_level of 8 or above disables CNAME lookups.
446 * A dos_protection_level or 12 or above diables delegation NS records.
448 * A dos_protection_level of 14 or above disables ANY record processing.
450 * A dos_protection_level of 18 or above disables star record processing
452 at the beginning of hostnames (default zonefiles still work,
453 however).
454 * A dos_protection_level of 78 disables all authoritative processing,
456 including default zonefiles; recursive lookups still work.
457 The default level of dos_protection_level is 0 when there are one or
459 more zonefiles; 78 when there are no zone files.
460 ipv6_bind_address
462 If MaraDNS is compiled with as an authoritative server, then this
464 variable will tell MaraDNS which ipv6 address for the UDP server to;
465 for this variable to be set, MaraDNS must be bound to at least one ipv4
466 address.
467 handle_noreply
469 This is a numeric variable which determines how the recursive resolver
471 informs the client that Mara was unable to contact any remote DNS
472 servers when trying to resolve a given domain. If this is set to 0, no
473 reponse will be sent to the DNS client. If this is set to 1, a "server
474 fail" message will be sent to the DNS client. If this is set to 2, a
475 "this host does not exist" message will be sent to the DNS client. The
476 default value for this is 1.
477 hide_disclaimer
479 If this is set to "YES", MaraDNS will not display the legal disclaimer
481 when starting up.
482 long_packet_ipv4
484 This is a list of IPs which we will send UDP packets longer than the
486 512 bytes RFC1035 permits if necessary. This is designed to allow
487 zoneserver, when used send regular DNS packets over TCP, to receive
488 packets with more data than can fit in a 512-byte DNS packet.
489 This variable only functions if MaraDNS is compiled as an authoritative
491 only server.
492 maradns_uid
494 maradns_uid: The numeric UID that MaraDNS will run as
496 This accepts a single numerical value: The UID to run MaraDNS as.
498 MaraDNS, as soon as possible drops root privileges, minimizing the
500 damage a potential attacker can cause should there be a security
501 problem with MaraDNS. This is the UID maradns becomes.
502 The default UID is 99.
504 maradns_gid
506 maradns_gid: The numeric GID that MaraDNS will run as.
508 This accepts a single numerical value: The GID to run MaraDNS as.
510 The default GID is 99.
512 maximum_cache_elements
514 maximum_cache_elements: The maximum number of elements we can have in
516 the cache of recursive queries.
517 This cache of recursive queries is used to store entries we have
519 previously obtained from recursive queries.
520 If we approach this limit, the "custodian" kicks in to effect. The
522 custodian removes elements at random from the cache (8 elements removed
523 per query) until we are at the 99% or so level again.
524 The default value for this variable is 1024.
526 maxprocs
528 maxprocs: The maximum number of threads or processes that MaraDNS is
530 allowed to run at the same time.
531 This variable is used to minimize the impact on the server when MaraDNS
533 is heavily loaded. When this number is reached, it is impossible for
534 MaraDNS to spawn new threads/processes until the number of
535 threads/processes is reduced.
536 The default value for this variable is 64.
538 The maximum value this can have is 500.
540 max_ar_chain
542 max_ar_chain: The maximum number of records to display if a record in
544 the additional section (e.g., the IP of a NS server or the ip of a MX
545 exchange) has more than one value.
546 This is similar to max_chain, but applies to records in the
548 "additional" (or AR) section.
549 Due to limitations in the internal data structures that MaraDNS uses to
551 store RRs, if this has a value besides one, round robin rotates of
552 records are disabled.
553 The default value for this variable is 1.
555 max_chain
557 max_chain: The maximum number of records to display in a chain of
559 records.
560 With DNS, it is possible to have more than one RR for a given domain
562 label. For example, "example.com" can have, as the A record, a list of
563 multiple ip addresses.
564 This sets the maximum number of records MaraDNS will show for a single
566 RR.
567 MaraDNS normally round-robin rotates records. Hence, all records for a
569 given DNS label (e.g. "example.com.") will be visible, although not at
570 the same time if there are more records than the value allowed with
571 max_chain
572 The default value for this variable is 8.
574 max_tcp_procs
576 max_tcp_procs: The (optional) maximum number of processes the zone
578 server is allowed to run.
579 Sometimes, it is desirable to have a different number of maximum
581 allowed tcp processes than maximum allowed threads. If this variable is
582 not set, the maximum number of allowed tcp processes is "maxprocs".
583 max_total
585 max_total: The maximum number of records to show total for a given DNS
587 request.
588 This is the maximum total number of records that MaraDNS will make
590 available in a DNS reply.
591 The default value for this variable is 20.
593 max_mem
595 max_mem is the maximum amount of memory we allow MaraDNS to allocate,
597 in bytes.
598 The default value of this is to allocate 1 megabyte for MaraDNS'
600 general use, and in addition, to allocate 1536 bytes for each element
601 we can have in the cache or DNS record that we are authoritatively
602 serving.
603 min_ttl
605 min_ttl: The minimum amount of time a resource record will stay in
607 MaraDNS' cache, regardless of the TTL the remote server specifies.
608 Setting this value changes the minimum amount of time MaraDNS'
610 recursive server will keep a record in the cache. The value is in
611 seconds.
612 The default value of this is 300 (5 minutes); the minimum value for
614 this is 180 (2 minutes).
615 min_ttl_cname
617 min_ttl_cname: The minimum amount of time a resource record will stay
619 in MaraDNS' cache, regardless of the TTL the remote server specifies.
620 Setting this value changes the amount of time a CNAME record stays in
622 the cache. The value is in seconds.
623 The default value for this is the value min_ttl has; the minimum value
625 for this is 180 (2 minutes).
626 min_visible_ttl
628 min_visible_ttl: The minimum value that we will will show as the TTL
630 (time to live) value for a resource record to other DNS servers and
631 stub resolvers. In other words, this is the minimum value we will ask
632 other DNS server to cache (keep in their memory) a DNS resource record.
633 The value is in seconds. The default value for this is 30; the minimum
635 value this can have is 5. People running highly loaded MaraDNS servers
636 may wish to increase this value to 3600 (one hour) in order to reduce
637 the number of queries recursively processed by MaraDNS.
638 As an aside, RFC1123 section 6.1.2.1 implies that zero-length TTL
640 records should be passed on with a TTL of zero. This, unfortunatly,
641 breaks some stub resolvers (such as Mozilla's stub resolver).
642 random_seed_file
644 randsom_seed_file: The file from which we read 16 bytes from to get the
646 128-bit seed for the secure pseudo random number generator.
647 This localcation of this file is relative to the root of the
649 filesystem, not MaraDNS' chroot directory.
650 This is ideally a file which is a good source of random numbers (e.g.
652 /dev/urandom), but can also be a fixed file if your OS does not have a
653 decent random number generator. In that case, make sure the contents of
654 that file is random and with 600 perms, owned by root. We read the
655 file before dropping root privileges.
656 recurse_delegation
658 recurse_delegation: Whether to recurse in the case of us finding a NS
660 delegation record, but the user/stub resolver sent a query that desires
661 recursion. Before MaraDNS 1.3, this was the default behavior.
662 When recurse_delegation has a value of 1, we recurse in this case.
664 Otherwise, we do not.
665 This parameter has a default value of 0.
667 recurse_min_bind_port
669 MaraDNS, by default, binds to a UDP port with a value between 15000 and
671 19095 when making a recursive query. This variable, and the
672 recurse_number_ports variable, allow this value to be changed.
673 recurse_min_bind_port is the lowest port number that MaraDNS will bind
675 to when making recursive queries. The default value for this is 15000.
676 recurse_number_ports
678 This determines the size of the port range MaraDNS will bind to when
680 making recursive queries. MaraDNS, when making a recursive query, will
681 locally bind to a port number between recurse_min_bin_port and
682 recurse_min_bind_port + recurse_number_ports - 1.
683 This number must be a power of 2 between 256 and 32768. In other words,
685 this must have the value 256, 512, 1024, 2048, 4096, 8192, 16384, or
686 32768. The default value for this is 4096.
687 The sum of the values for recurse_min_bind_port + recurse_number_ports
689 must fit within the 16-bit value used for UDP ports. In other words,
690 these two parameters, added together, can not be greater than 65534.
691 recursive_acl
693 recursive_acl: List of ips allowed to perform recursive queries with
695 the recursive portion of the MaraDNS server
696 The format of this string is identical to the format of an ipv4_alias
698 entry.
699 remote_admin
701 remote_admin: Whether we allow verbose_level to be changed after
703 MaraDNS is started.
704 If remote_admin is set to 1, and admin_acl is set, any and all IPs
706 listed in admin_acl will be able to reset the value of verbose_level
707 from any value between 0 and 9 via a TXT query in the form of
708 5.verbose_level.maradns. What this will do is set verbose_query to the
709 value in the first digit of the query.
710 This is useful when wishing to temporarily increase the verbose_level
712 to find out why a given host name is not resolving, then decreasing
713 verbose_level so as to minimize the size of MaraDNS' log.
714 retry_cycles
716 retry_cycles: The number of times the recursive resolver will try to
718 contact all of the DNS servers to resolve a given name before giving
719 up. This feature was added to MaraDNS 1.2.08, and has a default value
720 of 2.
721 spammers
723 spammers: A list of DNS servers which the recursive resolver will not
725 query.
726 This is mainly used to not allow spam-friendly domains to resolve,
728 since spammers are starting to get in the habit of using spam-friendly
729 DNS servers to resolve their domains, allowing them to hop from ISP to
730 ISP.
731 The format of this string is identical to the format of an ipv4_alias
733 entry.
734 synth_soa_origin
736 When a CSV2 zone file doesn't have a SOA record in it, MaraDNS
738 generates a SOA record on the fly. This variable determines the host
739 name for the "SOA origin" (which is called the MNAME in RFC1035); this
740 is the host name of the DNS server which has the "master copy" of a
741 given DNS zone's file.
742 This host name is in human-readable format without a trailing dot,
744 e.g.:
745 synth_soa_origin = "ns1.example.com"
747 If this is not set, a synthetic SOA record will use the name of the
749 zone for the SOA origin (MNAME) field.
750 synth_soa_serial
752 This determines whether we strictly follow RFC1912 section 2.2 with SOA
754 serial numbers. If this is set to 1 (the default value), we do not
755 strictly follow RFC1912 section 2.2 (the serial is a number, based on
756 the timestamp of the zone file, that is updated every six seconds), but
757 this makes it so that a serial number is guaranteed to be automatically
758 updated every time one edits a zone file.
759 If this is set to 2, the SOA serial number will be in YYYYMMDDHH
761 format, where YYYY is the 4-digit year, MM is the 2-digit month, DD is
762 the 2-digit day, and HH is the 2-digit hour of the time the zone file
763 was last updated (GMT; localtime doesn't work in a chroot()
764 environment). While this format is strictly RFC1912 compliant, the
765 disadvantage is that more than one edit to a zone file in an hour will
766 not update the serial number.
767 I strongly recommend, unless it is extremely important to have a DNS
769 zone that generates no warnings when tested at dnsreport.com, to have
770 this set to 1 (the default value). Having this set to 2 can result in
771 updated zone files not being seen by slave DNS servers.
772 Note that synth_soa_serial can only have a value of 1 on the native
774 Windows port.
775 tcp_convert_acl
777 This only applies to the zoneserver (general DNS-over-TCP) program.
779 This is a list of IPs which are allowed to connect to the zoneserver
781 and send normal TCP DNS requests. The zoneserver will convert TCP DNS
782 requests in to UDP DNS requests, and send the UDP request in question
783 to the server specified in tcp_convert_server. Once it gets a reply
784 from the UDP DNS server, it will convert the reply in to a TCP request
785 and send the reply back to the original TCP client.
786 Whether the RD (recursion desired) flag is set or not when converting a
788 TCP DNS request in to a UDP DNS request is determined by whether the
789 TCP client is on the recursive_acl list.
790 tcp_convert_server
792 This only applies to the zoneserver (general DNS-over-TCP) program.
794 This is the UDP server which we send a query to when converting DNS TCP
796 queries in to DNS UDP servers. Note that, while this value allows
797 multiple IPs, all values except the first one are presently ignored.
798 timeout_seconds
800 This only applies when performing recursive lookups.
802 The amount of time, in seconds, to wait for a reply from a remote DNS
804 server before giving up and trying the next server on this list. The
805 default value is 2 seconds.
806 This is for setups where a recursive MaraDNS server is on a slow
808 network which takes more than two seconds to send and receive a DNS
809 packet.
810 Note that, the larger this value is, the slower MaraDNS will process
812 recursive queries when a DNS server is not responding to DNS queries.
813 timestamp_type
815 timestamp_type: The type of timestamp to display. The main purpose of
817 this option is to supress the output of timestamps. Since duende uses
818 syslog() to output data, and since syslog() adds its own timestamp,
819 this option should be set to 5 when maradns is invoked with the duende
820 tool.
821 This option also allows people who do not use the duende tool to view
823 human-readable timestamps. This option only allows timestamps in GMT,
824 due to issues with showing local times in a chroot() environment.
825 This can have the following values:
827 0 The string "Timestamp" followed by a UNIX timestamp
829 1 Just the bare UNIX timestamp
831 2 A GMT timestamp in the Spanish language
833 3 A (hopefully) local timestamp in the Spanish language
835 4 A timestamp using asctime(gmtime()); usually in the English
837 language
838 5 No timestamp whatsoever is shown (this is the best option when
840 maradns is invoked with the duende tool).
841 6 ISO GMT timestamp is shown
843 7 ISO local timestamp is shown
845 The default value for this variable is 5.
847 upstream_port
849 This is the port that MaraDNS' recursive resolver uses to contact other
851 DNS servers. This is usually 53 (the default value), but certain
852 unusual MaraDNS setups (such as when resolving dangling CNAME records
853 on but a single IP) may need to have a different valur for this.
854 verbose_level
856 verbose_level: The number of messages we log to stdout
858 This can have five values:
860 0 No messages except for the legal disclaimer and fatal parsing
862 errors
863 1 Only startup messages logged (Default level)
865 2 Error queries logged
867 3 All queries logged
869 4 All actions adding and removing records from the cache logged
871 The default value for this variable is 1.
873 verbose_query
875 verbose_query: Whether to verbosely output all DNS queries that the
877 recursive DNS server receives. If this is set to 1, then all recursive
878 queries sent to MaraDNS will be logged.
879 This is mainly used for debugging.
881 zone_transfer_acl
883 zone_transfer_acl: List of ips allowed to perform zone transfers with
885 the zone server
886 The format of this string is identical to the format of an ipv4_alias
888 entry.
889
891 # Example mararc file (unabridged version)
892 # The various zones we support
894 # We must initialize the csv2 hash, or MaraDNS will be unable to
896 # load any csv2 zone files
897 csv2 = {}
898 # This is just to show the format of the file
900 #csv2["example.com."] = "db.example.com"
901 # The address this DNS server runs on. If you want to bind
903 # to multiple addresses, separate them with a comma like this:
904 # "10.1.2.3,10.1.2.4,127.0.0.1"
905 ipv4_bind_addresses = "127.0.0.1"
906 # The directory with all of the zone files
907 chroot_dir = "/etc/maradns"
908 # The numeric UID MaraDNS will run as
909 maradns_uid = 99
910 # The (optional) numeric GID MaraDNS will run as
911 # maradns_gid = 99
912 # The maximum number of threads (or processes, with the zone server)
913 # MaraDNS is allowed to run
914 maxprocs = 96
915 # It is possible to specify a different maximum number of processes that
916 # the zone server can run. If this is not set, the maximum number of
917 # processes that the zone server can have defaults to the 'maxprocs' value
918 # above
919 # max_tcp_procs = 64
920 # Normally, MaraDNS has some MaraDNS-specific features, such as DDIP
922 # synthesizing, a special DNS query ("erre-con-erre-cigarro.maradns.org."
923 # with a TXT query returns the version of MaraDNS that a server is
924 # running), unique handling of multiple QDCOUNTs, etc. Some people
925 # might not like these features, so I have added a switch that lets
926 # a sys admin disable all these features. Just give "no_fingerprint"
927 # a value of one here, and MaraDNS should be more or less
928 # indistinguishable from a tinydns server.
929 no_fingerprint = 0
930 # Normally, MaraDNS only returns A and MX records when given a
932 # QTYPE=* (all RR types) query. Changing the value of default_rrany_set
933 # to 15 causes MaraDNS to also return the NS and SOA records, which
934 # some registars require. The default value of this is 3
935 default_rrany_set = 3
936 # These constants limit the number of records we will display, in order
938 # to help keep packets 512 bytes or smaller. This, combined with round_robin
939 # record rotation, help to use DNS as a crude load-balancer.
940 # The maximum number of records to display in a chain of records (list
942 # of records) for a given host name
943 max_chain = 8
944 # The maximum number of records to display in a list of records in the
945 # additional section of a query. If this is any value besides one,
946 # round robin rotation is disabled (due to limitations in the current
947 # data structure MaraDNS uses)
948 max_ar_chain = 1
949 # The maximum number of records to show total for a given question
950 max_total = 20
951 # The number of messages we log to stdout
953 # 0: No messages except for fatal parsing errors and the legal disclaimer
954 # 1: Only startup messages logged (default)
955 # 2: Error queries logged
956 # 3: All queries logged (but not very verbosely right now)
957 verbose_level = 1
958 # Initialize the IP aliases, which are used by the list of root name servers,
960 # the ACL for zone transfers, and the ACL of who gets to perform recursive
961 # queries
962 ipv4_alias = {}
963 # Various sets of root name servers
965 # Note: Netmasks can exist, but are ignored when specifying root name server
966 # ICANN: the most common and most controversial root name server
968 # http://www.icann.org
969 # This list can be seen at http://www.root-servers.org/
970 ipv4_alias["icann"] = "198.41.0.4, 192.228.79.201, 192.33.4.12, 128.8.10.90,"
971 ipv4_alias["icann"] += "192.203.230.10, 192.5.5.241, 192.112.36.4,"
972 ipv4_alias["icann"] += "128.63.2.53, 192.36.148.17, 192.58.128.30,"
973 ipv4_alias["icann"] += "193.0.14.129, 198.32.64.12, 202.12.27.33"
974 # OpenNIC: http://www.opennic.unrated.net/
976 # Current as of 2005/11/30; these servers change frequently so please
977 # look at their web page
978 ipv4_alias["opennic"] = "157.238.46.24, 209.104.33.250, 209.104.63.249,"
979 ipv4_alias["opennic"] += "130.94.168.216, 209.21.75.53, 64.114.34.119,"
980 ipv4_alias["opennic"] += "207.6.128.246, 167.216.255.199, 62.208.181.95,"
981 ipv4_alias["opennic"] += "216.87.153.98, 216.178.136.116"
982 # End of list of root name server lists
984 # Here is a ACL which restricts who is allowed to perform zone transfer from
986 # the zoneserver program
987 # Simplest form: 10.1.1.1/24 (IP: 10.1.1.1, 24 left bits in IP need to match)
989 # and 10.100.100.100/255.255.255.224 (IP: 10.100.100.100, netmask
990 # 255.255.255.224) are allowed to connect to the zone server
991 # NOTE: The "maradns" program does not serve zones. Zones are served
992 # by the "zoneserver" program.
993 #zone_transfer_acl = "10.1.1.1/24, 10.100.100.100/255.255.255.224"
994 # More complex: We create two aliases: One called "office" and another
996 # called "home". We allow anyone in the office or at home to perform zone
997 # transfers
998 #ipv4_alias["office"] = "10.1.1.1/24"
999 #ipv4_alias["home"] = "10.100.100.100/255.255.255.224"
1000 #zone_transfer_acl = "office, home"
1001 # More complex then the last example. We have three employees,
1003 # Susan, Becca, and Mia, whose computers we give zone transfer rights to.
1004 # Susan and Becca are system administrators, and Mia is a developer.
1005 # They are all part of the company. We give the entire company zone
1006 # transfer access
1007 #ipv4_alias["susan"] = "10.6.7.8/32" # Single IP allowed
1008 #ipv4_alias["becca"] = "10.7.8.9" # also a single IP
1009 #ipv4_alias["mia"] = "10.8.9.10/255.255.255.255" # Also a single IP
1010 #ipv4_alias["sysadmins"] = "susan, becca"
1011 #ipv4_alias["devel"] = "mia"
1012 #ipv4_alias["company"] = "sysadmins, devel"
1013 # This is equivalent to the above line
1014 #ipv4_alias["company"] = "susan, becca, mia"
1015 #zone_transfer_acl = "company"
1016 # If you want to enable recursion on the loopback interface, uncomment
1018 # the relevent lines in the following section
1019 # Recursive ACL: Who is allowd to perform recursive queries. The format
1021 # is identical to that of "zone_transfer_acl", including ipv4_alias support
1022 #ipv4_alias["localhost"] = "127.0.0.0/8"
1024 #recursive_acl = "localhost"
1025 # Random seed file: The file from which we read 16 bytes from to get the
1027 # 128-bit random Rijndael key. This is ideally a file which is a good source
1028 # of random numbers, but can also be a fixed file if your OS does not have
1029 # a decent random number generator (make sure the contents of that file is
1030 # random and with 600 perms, owned by root, since we read the file *before*
1031 # dropping root privileges)
1032 #random_seed_file = "/dev/urandom"
1034 # The maximum number of elements we can have in the cache. If we have more
1036 # elements in the cache than this amount, the "custodian" kicks in to effect,
1037 # removing elements not recently accessed from the cache (8 elements removed
1038 # per query) until we are at the 99% level or so again.
1039 #maximum_cache_elements = 1024
1041 # It is possible to change the minimul "time to live" for entries in the
1043 # cache; this is the minimum time that an entry will stay in the cache.
1044 # Value is in seconds; default is 300 (5 minutes)
1045 #min_ttl = 300
1046 # CNAME records generally take more effort to resolve in MaraDNS than
1047 # non-CNAME records; it is a good idea to make this higher then min_ttl
1048 # default value is to be the same as min_ttl
1049 #min_ttl_cname = 900
1050 # The root servers which we use when making recursive queries.
1052 # The following line must be uncommented to enable custom root servers
1054 # for recursive queries
1055 #root_servers = {}
1056 # You can choose which set of root servers to use. Current values (set above)
1058 # are: icann, osrc, alternic, opennic, pacificroot, irsc, tinc, and
1059 # superroot.
1060 #root_servers["."] = "icann"
1061 # If you prefer to contact other recursive DNS servers instead of the ICANN
1063 # root servers, this is done with the upstream_servers mararc variable:
1064 #upstream_servers["."] = "192.168.0.1, 192.168.0.2"
1065 # You can tell MaraDNS to *not* query certain DNS servers when in recursive
1067 # mode. This is mainly used to not allow spam-friendly domains to resolve,
1068 # since spammers are starting to get in the habit of using spam-friendly
1069 # DNS servers to resolve their domains, allowing them to hop from ISP to
1070 # ISP. The format of this is the same as for zone_transfer_acl and
1071 # recursive_acl
1072 # For example, at the time of this document (August 12, 2001), azmalink.net
1074 # is a known spam-friendly DNS provider (see doc/detailed/spammers/azmalink.net
1075 # for details.) Note that this is based on IPs, and azmalink.net constantly
1076 # changes IPs (as they constantly have to change ISPs)
1077 # 2002/10/12: Azmalink changed ISP again, this reflect their current ISP
1078 ipv4_alias["azmalink"] = "12.164.194.0/24"
1079 # As of September 20, 2001, hiddenonline.net is a known spam-friendly
1081 # DNS provider (see doc/detailed/spammers/hiddenonline for details).
1082 ipv4_alias["hiddenonline"] = "65.107.225.0/24"
1083 spammers = "azmalink,hiddenonline"
1084 # It is also possible to change the maximum number of times MaraDNS will
1086 # follow a CNAME record or a NS record with a glue A record. The default
1087 # value for this is ten.
1088 #max_glueless_level = 10
1089 # In addition, one can change the maximum number of total queries that
1090 # MaraDNS will perform to look up a host name. The default value is 32.
1091 #max_queries_total = 32
1092 # In addition, one can change the amount of time that MaraDNS will wait
1093 # for a DNS server to respond before giving up and trying the next DNS
1094 # server on a list. Note that, the larger this value is, the slower
1095 # MaraDNS will process recursive queries when a DNS server is not
1096 # responding to DNS queries. The default value is two seconds.
1097 #timeout_seconds = 2
1098 # And that does it for the caching at this point
1101
1106 If one should declare the same the same index twice with a dictionary
1107 variable, MaraDNS will exit with a fatal error. This is because earlier
1108 versions of MaraDNS acted in a different manner than Python 2.3.3. With
1109 Python 2.3.3, the last declaration is used, while MaraDNS used to use
1110 the first declaration.
1111
1113 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR
1114 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1115 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1116 DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
1117 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
1118 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
1119 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1120 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
1121 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
1122 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1123 POSSIBILITY OF SUCH DAMAGE.
1124MARADNS January 2002 MARARC(5)