« back to all changes in this revision
Viewing changes to doc/en/source/mararc.ej.orig
- browse files at revision 12
- compare with another revision
- download diff
- download tarball
- view history from revision 12
- Committer: Bazaar Package Importer
- Author(s): Kai Hendry
- Date: 2007-05-19 22:00:19 UTC
- mfrom: (1.1.9 upstream)
- Revision ID: james.westby@ubuntu.com-20070519220019-5sfo6wjbeqecn6lb
Tags: 1.2.12.06-1
* New upstream release
* A couple of memory leaks fixed
* Upstream considers these bugs important, hence medium urgency
* A couple of memory leaks fixed
* Upstream considers these bugs important, hence medium urgency
- files added:
- build/maradns-1.2.12.06.spec
- update/1.2.12.06
- files removed:
- build/maradns-1.2.12.05.spec
- files modified:
- debian/changelog
added
removed
doc/en/source/mararc.ej.orig
1
<HEAD>
2
<TH>MARARC 5 "January 2002" MARADNS "MaraDNS reference"</TH>
3
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=utf-8">
4
</HEAD>
5
<BODY>
6
7
<h1>NAME</h1>
8
mararc - Format of the mararc zone file that MaraDNS uses
9
10
<h1>MARARC FILE FORMAT</h1>
11
Mararc files use a syntax that is a subset of Python 2.2.3 syntax. In
12
particular, Python 2.2.3 (and possibly other versions of Python) can read
13
a properly formatted mararc file without error.
14
<p>
15
Unlike Python, however, a mararc file can only use certain variable names,
16
and the variables can only be declared as described below.
17
<p>
18
<h1>COMMENTS</h1>
19
Comments (lines ignored by the MaraDNS parser) start with the '#'
20
character, like this:
21
<pre>
22
# This is a comment
23
</pre>
24
The MaraDNS parser also ignores lines which contain only white space.
25
26
<h1>OPERATORS</h1>
27
The MaraRC file supports two operators: = and +=
28
<p>
29
The = operator can be used to assign both numeric and string values
30
<p>
31
The += operator can only be used on string values, and concatenates the
32
value to the right of the += operator to the string specified to the
33
left of the += operator.
34
<p>
35
Examples:
36
<pre>
37
ipv4_bind_addresses = "10.2.19.83"
38
ipv4_bind_addresses += ",10.2.66.74"
39
ipv4_bind_addresses += ",10.3.87.13"
40
</pre>
41
42
ipv4_bind_addresses now has the value "10.2.19.83,10.2.66.74,10.3.87.13"
43
44
<pre>
45
ipv4_alias["icann"] = "198.41.0.4"
46
ipv4_alias["icann"] += ",192.228.79.201"
47
ipv4_alias["icann"] += ",192.33.4.12,128.8.10.90"
48
</pre>
49
50
<h1>MARARC VARIABLES</h1>
51
Follows is a listing of variables that can be declared in the mararc file.
52
53
<h1>DICTIONARY VARIABLE FORMAT</h1>
54
55
A <b>dictionary variable</b>
56
is an array that can have multiple elements. Unlike a traditional
57
array, these arrays are indexed by strings instead of numbers. These
58
are analogous to associative arrays, or what Perl somewhat inaccurately
59
calls hashes.
60
<p>
61
The syntax of a dictionary variable is in the following form:
62
<pre>
63
name["index"] = "value"
64
</pre>
65
Where <b>name</b> is the name of the dictionary variable,
66
<b>index</b> is the index of the array, and
67
<b>value</b> is the value stored at that index.
68
<p>
69
Every time we have a dictionary-type variable (such as csv2),
70
we must first initialize it using a line in the following form:
71
<pre>
72
csv2 = {}
73
</pre>
74
Here, csv2 is the name of the "dictionary" variable that we are
75
initializing.
76
77
<h1>DICTIONARY VARIABLES</h1>
78
79
Here is a listing of all "dictionary"-style variables that MaraDNS
80
uses:
81
82
<h2>csv2</h2>
83
84
The csv2 dictionary variable stores all of the zone names and file names
85
for the zone files that MaraDNS uses. Note that csv2 files are read
86
after MaraDNS is chrooted. Hence the filename is relative to the
87
chroot_dir.
88
89
Example:
90
91
<pre>
92
csv2["example.net."] = "db.example.net"
93
</pre>
94
95
See
96
<b>csv2(5)</b>
97
for a description of this file's format.
98
99
<h2>csv1</h2>
100
101
csv1: Used to indicate the filename to use for a given zone stored in
102
the legacy csv1 zone file format. This is primarily for compatibility
103
with people who have maradns-1.0 zone files.
104
<pre>
105
csv1["zone"] = "filename"
106
</pre>
107
<b>csv1</b>:
108
A pipe-separated-file. See
109
<b>csv1(5)</b>.
110
<p>
111
<b>zone</b>:
112
the zone that file in question is authoritative for
113
<p>
114
<b>filename</b>:
115
the file with the CSV1 zone data
116
<p>
117
Note that csv1 files are read after MaraDNS is chrooted, and,
118
hence the filename is relative to the chroot_dir.
119
<p>
120
See the <b>csv1(5)</b> man page for more information on this file format.
121
122
<h2>ipv4_alias</h2>
123
124
ipv4_alias: Used to give nicknames or aliases for ip/netmask
125
pairs for ipv4 (standard 32-bit) IP addresses.
126
127
<pre>
128
ipv4_alias["name"] = "ip1/netmask,ip2/netmask,etc"
129
</pre>
130
131
<b>name</b>: The name of the alias in question
132
<p>
133
134
<b>ip</b>: The ip portion of an ip/netmask pair
135
<p>
136
137
<b>netmask</b>: the mask portion of an ip/netmask pair
138
<p>
139
140
<b>,</b>: Used to separate ip/netmask pairs. Spaces may be placed before or
141
after this comma.
142
<p>
143
144
An ip is in dotted-decimal format, e.g. "10.1.2.3".
145
<p>
146
147
The netmask can be in one of two formats: A single number between
148
1 and 32, which indicates the number of leading "1" bits in the
149
netmask, or a 4-digit dotted-decimal netmask.
150
<p>
151
152
The netmask is used to specify a range of IPs.
153
<p>
154
155
<h2>ipv4_alias examples</h2>
156
157
<b>10.1.1.1/24</b> indicates that any ip from 10.1.1.0 to 10.1.1.255
158
will match.
159
<p>
160
161
<b>10.1.1.1/255.255.255.0</b> is identical to 10.1.1.1/24
162
<p>
163
164
<b>10.2.3.4/16</b> indicates that any ip from 10.2.0.0 to 10.2.255.255
165
will match.
166
<p>
167
168
<b>10.2.3.4/255.255.0.0</b> is identical to 10.2.3.4/16
169
<p>
170
171
<b>127.0.0.0/8</b> indicates that any ip with "127" as the first
172
octet (number) will match.
173
<p>
174
175
<b>127.0.0.0/255.0.0.0</b> is identical to 127.0.0.0/8
176
<p>
177
178
The netmask is optional, and, if not present, indicates that only
179
a single IP will "match". e.g:
180
<p>
181
182
<b>10.9.9.9/32</b>, <b>10.9.9.9/255.255.255.255</b>, and <b>10.9.9.9</b>
183
are all functionally identical, and indicate that only the ip 10.9.9.9
184
will match.
185
<p>
186
187
The significance of "match" depends on what we use the ipv4
188
alias for.
189
<p>
190
191
ipv4 aliases can nest. E.g:
192
<pre>
193
ipv4_alias["susan"] = "10.6.7.8/24"
194
ipv4_alias["office"] = "susan,10.9.9.9"
195
</pre>
196
197
Where "susan" in the "office" alias matches the value of the
198
ipv4_alias susan.
199
<p>
200
201
Multiple levels of nesting are allowed. Self-referring nests will
202
result in an error.
203
<p>
204
205
<h2>root_servers</h2>
206
207
root_servers: This is a special "dictionary" element that can
208
(currently) only have one element: ".", which points to either
209
an ip, or a pointer to an ipv4 alias which is a listing of root name
210
servers.
211
212
<pre>
213
root_servers["."] = "list_of_servers"
214
</pre>
215
216
Where "." is the only allowed array reference for the root servers
217
(this format is used to allow potential future expansion), and
218
list_of_servers is a list of root name servers in the exact same
219
format as ipv4_aliases.
220
<p>
221
222
Note that, while ips in the list of root name servers can have
223
netmasks, the netmask portion is ignored.
224
<p>
225
226
The root_servers should only point to root servers. If one wishes to use
227
MaraDNS as a forwarding name server, which forwards DNS requests on to
228
another server, use the upstream_servers variable instead.
229
230
<h2>upstream_servers</h2>
231
232
This is identical to the root_servers variable (can have only one
233
element, the element is a list of ipv4_addresses, the variable is a
234
dictionary variable, etc.), but is used
235
when one wishes to use MaraDNS to query other recursive servers, instead
236
of querying the actual root name servers for an answer.
237
<p>
238
239
Note that one can not have both root_servers and upstream_servers set
240
in a given mararc file; MaraDNS will return with a fatal error if one
241
attempts to do this.
242
<p>
243
244
If you get a syntax error when trying to use upstream_servers, please
245
search for upstream_servers in the
246
MaraDNS FAQ and read this entry, or look for upstream_servers
247
in the example mararc file below for an example of correct usage
248
of this variable.
249
250
<h2>Final note on dictionary variables</h2>
251
252
csv1, csv2, ipv4_alias, and root_servers are currently the only existing
253
dictionary variables.
254
255
<h1>NORMAL VARIABLE FORMAT</h1>
256
257
Normal variables. These are variables that can only take
258
a single value.
259
<p>
260
261
The syntax of a normal variable is in the form
262
<pre>
263
name = "value"
264
</pre>
265
266
Where <b>name</b> is the name of the normal variable, and <b>value</b>
267
is the value of the variable in question.
268
269
<h1>NORMAL VARIABLES</h1>
270
271
Here is a listing of normal variables that MaraDNS
272
uses:
273
274
<h2>ipv4_bind_addresses</h2>
275
276
ipv4_bind_addresses: The IP addresses to give the MaraDNS server.
277
<p>
278
279
This accepts one or more ipv4 IPs in dotted-decimal (e.g. "127.0.0.1")
280
notation, and specifies what IP addresses the MaraDNS server will
281
listen on. Multiple bind addresses are separated with a comma, like
282
this: "10.1.2.3, 10.1.2.4, 127.0.0.1"
283
<p>
284
285
<h2>admin_acl</h2>
286
287
This is a list of ip/netmask pairs that are allowed to get certain
288
administrative information about MaraDNS, including:
289
<ul>
290
<li>The version number of MaraDNS running
291
<li>The number of threads MaraDNS has
292
<li>MaraDNS' internal timestamp value
293
</ul>
294
295
Note that this information is not available unless
296
the mararc variable debug_msg_level is sufficiently high.
297
See the information on debug_msg_level below for details on this
298
and on the TXT queries sent to get the above information.
299
300
<h2>bind_address</h2>
301
302
bind_address: The IP address to give the MaraDNS server.
303
<p>
304
305
This accepts a single IP in dotted-decimal (e.g. "127.0.0.1")
306
notation, and specifies what IP address the MaraDNS server will
307
listen on. Note that ipv4_bind_addresses has the same functionality.
308
This name is included so that MaraDNS 1.0 configuration files will
309
continue to work with MaraDNS 1.2.
310
<p>
311
312
<h2>bind_star_handling</h2>
313
314
In the case where there is both a star record for a given name and recordtype,
315
a non-star record with the same name but a different recordtype, and no record
316
for the given name and recordtype, MaraDNS will usually return the
317
star record. BIND, on the other hand, will return a "not there" reply.
318
319
In other words:
320
321
<ul>
322
<li>If a non-A record for <tt>foo.example.com</tt> exists
323
<li>An A record for <tt>*.example.com</tt> exists
324
<li>No A record for <tt>foo.example.com</tt> exists
325
<li>And the user asks for the A record for <tt>foo.example.com</tt>
326
<li>MaraDNS will usually return the A record attached to <tt>*.example.com</tt>
327
<li>BIND, on the other hand, returns a "not there" for <tt>foo.example.com</tt>
328
</ul>
329
330
If the BIND behavior is desired, set <tt>bind_star_handling</tt> to 1.
331
Otherwise, set this to 0 (the default value if this is not set at all
332
in the <tt>mararc</tt> file).
333
334
<p>
335
336
MaraDNS will exit with a fatal error if <tt>bind_star_handling</tt> has
337
any value besides 0 or 1.
338
339
<h2>chroot_dir</h2>
340
chroot_dir: The directory MaraDNS chroots to
341
<p>
342
343
This accepts a single value: The full path to the directory to
344
use as a chroot jail.
345
<p>
346
347
Note that csv1 zone files are read after the chroot operation.
348
Hence, the chroot jail needs to have any and all zone files that
349
MaraDNS will load.
350
351
<h2>csv2_default_zonefile</h2>
352
This is a special zone file that allows there to be stars at the <i>end</i>
353
of hostnames. This file is similar to a normal csv2 zone file, but has
354
the following features and limitations:
355
356
<ul>
357
<li>Stars are allowed at the end of hostnames
358
<li>A SOA record is mandatory
359
<li>NS records are mandatory
360
<li>Neither CNAME nor FQDN4 records are permitted in the zone file
361
<li>Delegation NS records are not permitted in the zone file
362
<li>Default zonefiles may not be transferred via zone transfer
363
<li>Both recursion and default zonefiles may not be enabled at the same
364
time.
365
</ul>
366
367
<h2>csv2_synthip_list</h2>
368
Sometimes the IP list of nameservers will be different than the
369
nameservers one is bound to. This allows the synthetic nameserver list
370
to have different IPs.
371
372
<p>
373
374
Note that this may act in an unexpected manner
375
if routable and non-routable (localhost and RFC1918) addresses are
376
combined; in particular, a list with both routable and non-routable
377
addresses will discard the non-routable IP addresses, and a list with
378
rfc1918 and localhost addresses will discard the localhost addresses.
379
380
<h2>debug_msg_level</h2>
381
382
This is a number indicating what level of information about a running
383
MaraDNS process should be made public. When set to 0, no information
384
will be made public.
385
<p>
386
When set to one (the default), or higher, a
387
Tversion.maradns. (TXT query for
388
"version.maradns.") query will return the version
389
number of MaraDNS.
390
<p>
391
When set to two or higher, a Tnumthreads.maradns.
392
(TXT query for "numthreads.maradns.")
393
query will return the
394
number of threads that MaraDNS is currently running, and a
395
Tcache-elements.maradns.
396
query will return the number of elements in MaraDNS' cache.
397
<p>
398
If MaraDNS is compiled with debugging information on, a
399
Tmemusage.maradns. query will return the amount of memory MaraDNS has
400
allocated. Note that the overhead for tracking memory usage is considerable
401
and that compiling MaraDNS with "make debug" will greatly slow down MaraDNS.
402
A debug build of MaraDNS is <b>not</b> reccomended for production use.
403
<p>
404
When set to three or higher, a Ttimestamp.maradns. query will return, in
405
seconds since the UNIX epoch, the timestamp for the system MaraDNS
406
is running on.
407
<br>
408
409
<h2>default_rrany_set</h2>
410
This variable used to determine what kind of resource records were returned
411
when an ANY query was sent. In MaraDNS 1.2, the data structures have been
412
revised to return any resource record type when an ANY query is sent; this
413
variable does nothing, and is only here so that MaraDNS 1.0 mararc files
414
will continue to work.
415
416
The only accepted values for this variable were 3 and 15.
417
418
<h2>dos_protection_level</h2>
419
If this is set to a non-zero value, certain features of MaraDNS will be
420
disabled in order to speed up MaraDNS' response time. This is designed for
421
situtations when a MaraDNS server is receiving a large number of queries,
422
such as during a denial of service attack.
423
424
<p>
425
426
This is a numeric variable; its default value is zero, indicating that all
427
of MaraDNS' normal features are enabled. Higher numeric values
428
disable more features:
429
430
<ul>
431
432
<li>A dos_protection_level of 1 or above disables getting MaraDNS status
433
information remotely
434
435
<li>A dos_protection_level of 8 or above disables CNAME lookups.
436
437
<li>A dos_protection_level or 12 or above diables delegation NS records.
438
439
<li>A dos_protection_level of 14 or above disables ANY record processing
440
441
<li>A dos_protection_level of 18 or above disables star record processing
442
at the beginning of hostnames (default_zonefiles still work, however)
443
444
</ul>
445
446
<h2>ipv6_bind_address</h2>
447
If MaraDNS is compiled with as an authoritative server, then this
448
variable will tell MaraDNS which ipv6 address for the UDP server to;
449
for this variable to be set, MaraDNS must be bound to at least one
450
ipv4 address.
451
452
<h2>handle_noreply</h2>
453
This is a numeric variable which determines how the recursive resolver
454
informs the client that Mara was unable to contact any remote DNS servers
455
when trying to resolve a given domain.
456
457
If this is set to 0, no reponse will be sent to the DNS client.
458
459
If this is set to 1, a "server fail" message will be sent to the DNS client.
460
461
If this is set to 2, a "this host does not exist" message will be sent
462
to the DNS client.
463
464
The default value for this is 1.
465
466
<h2>hide_disclaimer</h2>
467
If this is set to "YES", MaraDNS will not display the legal disclaimer when
468
starting up.
469
470
<h2>long_packet_ipv4</h2>
471
This is a list of IPs which we will send UDP packets longer than the 512 bytes
472
RFC1035 permits if necessary. This is designed to allow <tt>zoneserver</tt>,
473
when used send regular DNS packets over TCP, to receive packets with more
474
data than can fit in a 512-byte DNS packet.
475
<p>
476
477
This variable only functions if MaraDNS is compiled as an authoritative
478
only server.
479
480
<h2>maradns_uid</h2>
481
maradns_uid: The numeric UID that MaraDNS will run as
482
<p>
483
484
This accepts a single numerical value: The UID to run MaraDNS as.
485
<p>
486
487
MaraDNS, as soon as possible drops root privileges, minimizing the
488
damage a potential attacker can cause should there be a security
489
problem with MaraDNS. This is the UID maradns becomes.
490
<p>
491
The default UID is 99.
492
493
<h2>maradns_gid</h2>
494
maradns_gid: The numeric GID that MaraDNS will run as.
495
<p>
496
497
This accepts a single numerical value: The GID to run MaraDNS as.
498
<p>
499
500
The default GID is 99.
501
502
<h2>maximum_cache_elements</h2>
503
maximum_cache_elements: The maximum number of elements we can have
504
in the cache of recursive queries.
505
<p>
506
507
This cache of recursive queries is used to store entries we have
508
previously obtained from recursive queries.
509
<p>
510
511
If we approach this limit, the "custodian" kicks in to effect.
512
The custodian removes elements at random from the cache (8 elements
513
removed per query) until we are at the 99% or so level again.
514
515
<p> The default value for this variable is 1024.
516
<h2>maxprocs</h2>
517
maxprocs: The maximum number of threads or processes that MaraDNS
518
is allowed to run at the same time.
519
<p>
520
521
This variable is used to minimize the impact on the server when
522
MaraDNS is heavily loaded. When this number is reached, it is
523
impossible for MaraDNS to spawn new threads/processes until the
524
number of threads/processes is reduced.
525
<p> The default value for this variable is 64.
526
<p>
527
The maximum value this can have is 500.
528
<h2>max_ar_chain</h2>
529
max_ar_chain: The maximum number of records to display if a record in
530
the additional section (e.g., the IP of a NS server
531
or the ip of a MX exchange) has more than one value.
532
<p>
533
534
This is similar to max_chain, but applies to records in the
535
"additional" (or AR) section.
536
<p>
537
538
Due to limitations in the internal data structures that MaraDNS
539
uses to store RRs, if this has a value besides one, round robin
540
rotates of records are disabled.
541
542
<p> The default value for this variable is 1.
543
544
<h2>max_chain</h2>
545
max_chain: The maximum number of records to display in a chain
546
of records.
547
<p>
548
549
With DNS, it is possible to have more than one RR for a given
550
domain label. For example, "example.com" can have, as the A record,
551
a list of multiple ip addresses.
552
<p>
553
554
This sets the maximum number of records MaraDNS will show for a
555
single RR.
556
<p>
557
558
MaraDNS normally round-robin rotates records. Hence, all records
559
for a given DNS label (e.g. "example.com.") will be visible,
560
although not at the same time if there are more records than the
561
value allowed with max_chain
562
563
<p> The default value for this variable is 8.
564
565
<h2>max_glueless_level</h2>
566
Maximum glueless level allowed when performing recursive lookups. The
567
default value is 10.
568
<p>
569
570
This is the maximum number of times MaraDNS will "go back to the root
571
servers" in order to find out the IP of a name server for which we do
572
not have a glue IP for, or to find out the A value for a given CNAME
573
record.
574
575
<h2>max_queries_total</h2>
576
Maximum number of queries to perform when performing recursive lookups. The
577
default value is 32.
578
<p>
579
580
This is the maximum number of times MaraDNS will send a query to
581
nameservers in order to find out the answer to a DNS question.
582
583
<h2>max_tcp_procs</h2>
584
max_tcp_procs: The (optional) maximum number of processes the zone
585
server is allowed to run.
586
<p>
587
588
Sometimes, it is desirable to have a different number of maximum
589
allowed tcp processes than maximum allowed threads. If this
590
variable is not set, the maximum number of allowed tcp processes is
591
"maxprocs".
592
593
<h2>max_total</h2>
594
max_total: The maximum number of records to show total for a given
595
DNS request.
596
<p>
597
598
This is the maximum total number of records that MaraDNS will make
599
available in a DNS reply.
600
601
<p> The default value for this variable is 20.
602
<h2>min_ttl</h2>
603
min_ttl: The minimum amount of time a resource record will stay in
604
MaraDNS' cache, regardless of the TTL the remote server specifies.
605
<p>
606
607
Setting this value changes the minimum amount of time MaraDNS'
608
recursive server will keep a record in the cache. The value is
609
in seconds.
610
611
<p>
612
The default value of this is 300 (5 minutes); the minimum value
613
for this is 180 (2 minutes).
614
615
<h2>min_ttl_cname</h2>
616
min_ttl_cname: The minimum amount of time a resource record
617
will stay in MaraDNS' cache, regardless of the TTL the remote server
618
specifies.
619
<p>
620
621
Setting this value changes the amount of time a CNAME record stays
622
in the cache. The value is in seconds.
623
624
<p>
625
The default value for this is the value min_ttl has; the minimum value
626
for this is 180 (2 minutes).
627
628
<h2>min_visible_ttl</h2>
629
min_visible_ttl: The minimum value that we will will show as the TTL (time
630
to live) value for a resource record to other DNS servers and stub resolvers.
631
In other words, this is the minimum value we will ask other DNS server to
632
cache (keep in their memory) a DNS resource record.
633
<p>
634
635
The value is in seconds. The default value for this is 30; the minimum
636
value this can have is 5. People running highly loaded MaraDNS servers
637
may wish to increase this value to 3600 (one hour) in order to reduce the
638
number of queries recursively processed by MaraDNS.
639
<p>
640
641
As an aside, RFC1123 section 6.1.2.1 implies that zero-length TTL records
642
should be passed on with a TTL of zero. This, unfortunatly, breaks some
643
stub resolvers (such as Mozilla's stub resolver).
644
645
<h2>no_fingerprint</h2>
646
no_fingerprint: Flag that allows MaraDNS to be harder to detect.
647
<p>
648
649
Some people do not feel it is appropriate to have some information,
650
such as the version number of MaraDNS being run, be publicly
651
available.
652
<p>
653
654
The default value is 0.
655
<p>
656
657
By setting no_fingerprint to 1, it is possible to have MaraDNS not
658
reveal this information publicly.
659
660
<h2>random_seed_file</h2>
661
randsom_seed_file: The file from which we read 16 bytes from to
662
get the 128-bit seed for the secure pseudo random number generator.
663
<p>
664
665
This localcation of this file is relative to the root of the
666
filesystem, not MaraDNS' chroot directory.
667
<p>
668
669
This is ideally a file which is a good source of random numbers
670
(e.g. /dev/urandom), but can also be a fixed file if your OS does not
671
have a decent random number generator. In that case, make sure the
672
contents of that file is random and with 600 perms, owned by root.
673
We read the file <b>before</b> dropping root privileges.
674
675
<h2>recursive_acl</h2>
676
recursive_acl: List of ips allowed to perform recursive queries with
677
the recursive portion of the MaraDNS server
678
<p>
679
680
The format of this string is identical to the format of an ipv4_alias
681
entry.
682
683
<h2>remote_admin</h2>
684
remote_admin: Whether we allow <tt>verbose_level</tt> to be changed
685
after MaraDNS is started.
686
<p>
687
688
If <tt>remote_admin</tt> is set to 1, and <tt>admin_acl</tt> is set,
689
any and all IPs listed in <tt>admin_acl</tt> will be able to
690
reset the value of <tt>verbose_level</tt> from any value between 0
691
and 9 via a TXT query in the form of <tt>5.verbose_level.maradns.</tt>
692
What this will do is set <tt>verbose_query</tt> to the value in the
693
first digit of the query.
694
<p>
695
696
This is useful when wishing to temporarily increase the
697
<tt>verbose_level</tt> to find out why a given host name is not
698
resolving, then decreasing <tt>verbose_level</tt> so as to minimize
699
the size of MaraDNS' log.
700
701
<h2>retry_cycles</h2>
702
retry_cycles: The number of times the recursive resolver will try to contact
703
all of the DNS servers to resolve a given name before giving up. This
704
feature was added to MaraDNS 1.2.08, and has a default value of 2.
705
706
<h2>spammers</h2>
707
spammers: A list of DNS servers which the recursive resolver will
708
not query.
709
<p>
710
711
This is mainly used to not allow spam-friendly domains to
712
resolve, since spammers are starting to get in the habit of using
713
spam-friendly DNS servers to resolve their domains, allowing them
714
to hop from ISP to ISP.
715
<p>
716
717
The format of this string is identical to the format of an ipv4_alias
718
entry.
719
720
<h2>synth_soa_origin</h2>
721
When a CSV2 zone file doesn't have a SOA record in it, MaraDNS generates
722
a SOA record on the fly. This variable determines the host name for
723
the "SOA origin" (which is called the MNAME in RFC1035); this is the
724
host name of the DNS server which has the "master copy" of a given
725
DNS zone's file.
726
<p>
727
This host name is in human-readable format without a trailing dot,
728
e.g.:
729
<pre>
730
synth_soa_origin = "ns1.example.com"
731
</pre>
732
If this is not set, a synthetic SOA record will use the name of the
733
zone for the SOA origin (MNAME) field.
734
735
<p>
736
737
<h2>synth_soa_serial</h2>
738
This determines whether we strictly follow RFC1912 section 2.2 with
739
SOA serial numbers. If this is set to 1 (the default value), we do
740
not strictly follow RFC1912 section 2.2 (the serial is a number, based
741
on the timestamp of the zone file, that is updated every six seconds), but
742
this makes it so that a serial number is guaranteed to be automatically
743
updated every time one edits a zone file.
744
745
<p>
746
If this is set to 2, the SOA serial number will be in YYYYMMDDHH format,
747
where YYYY is the 4-digit year, MM is the 2-digit month, DD is the 2-digit
748
day, and HH is the 2-digit hour of the time the zone file was last updated
749
(GMT; localtime doesn't work in a chroot() environment). While this
750
format is strictly RFC1912 compliant, the disadvantage is that more than
751
one edit to a zone file in an hour will not update the serial number.
752
753
<p>
754
I strongly recommend, unless it is extremely important to have a
755
DNS zone that generates no warnings when tested at dnsreport.com, to have
756
this set to 1 (the default value). Having this set to 2 can result in
757
updated zone files not being seen by slave DNS servers.
758
759
<p>
760
Note that synth_soa_serial can only have a value of 1 on the native
761
Windows port.
762
763
<h2>tcp_convert_acl</h2>
764
This only applies to the zoneserver (general DNS-over-TCP) program.
765
<p>
766
767
This is a list of IPs which are allowed to connect to the zoneserver and
768
send normal TCP DNS requests. The zoneserver will convert TCP DNS
769
requests in to UDP DNS requests, and send the UDP request in question
770
to the server specified in <b>tcp_convert_server</b>. Once it gets a
771
reply from the UDP DNS server, it will convert the reply in to a TCP
772
request and send the reply back to the original TCP client.
773
774
<p>
775
Whether the RD (recursion desired) flag is set or not when converting a TCP
776
DNS request in to a UDP DNS request is determined by whether the TCP client
777
is on the <b>recursive_acl</b> list.
778
779
<h2>tcp_convert_server</h2>
780
This only applies to the zoneserver (general DNS-over-TCP) program.
781
<p>
782
783
This is the UDP server which we send a query to when converting DNS TCP
784
queries in to DNS UDP servers. Note that, while this value allows
785
multiple IPs, all values except the first one are presently
786
ignored.
787
788
<h2>timeout_seconds</h2>
789
This only applies when performing recursive lookups.
790
<p>
791
792
The amount of time, in seconds, to wait for a reply from a remote DNS
793
server before giving up and trying the next server on this list. The
794
default value is 2 seconds.
795
<p>
796
This is for setups where a recursive MaraDNS server is on a slow
797
network which takes more than two seconds to send and receive a DNS
798
packet.
799
<p>
800
801
Note that, the larger this value is, the slower MaraDNS will process
802
recursive queries when a DNS server is not responding to DNS queries.
803
804
<h2>timestamp_type</h2>
805
timestamp_type: The type of timestamp to display. The main purpose of
806
this option is to supress the output of timestamps. Since duende uses
807
syslog() to output data, and since syslog() adds its own timestamp, this
808
option should be set to 5 when maradns is invoked with the duende tool.
809
810
<p>
811
812
This option also allows people who do not use the duende tool to view
813
human-readable timestamps. This option only allows timestamps in GMT,
814
due to issues with showing local times in a chroot() environment.
815
816
<p>
817
818
This can have the following values:
819
<dl>
820
<dt>0
821
<dd>The string "Timestamp" followed by a UNIX timestamp
822
<dt>1
823
<dd>Just the bare UNIX timestamp
824
<dt>2
825
<dd>A GMT timestamp in the Spanish language
826
<dt>3
827
<dd>A (hopefully) local timestamp in the Spanish language
828
<dt>4
829
<dd>A timestamp using asctime(gmtime()); usually in the English language
830
<dt>5
831
<dd>No timestamp whatsoever is shown (this is the best option when
832
maradns is invoked with the <tt>duende</tt> tool).
833
<dt>6
834
<dd>ISO GMT timestamp is shown
835
<dt>7
836
<dd>ISO local timestamp is shown
837
</dl>
838
839
<p> The default value for this variable is 5.
840
841
<h2>verbose_level</h2>
842
verbose_level: The number of messages we log to stdout
843
<P>
844
845
This can have five values:
846
<dl>
847
<dt>0
848
<dd>No messages except for the legal disclaimer and fatal parsing errors
849
<dt>1
850
<dd>Only startup messages logged (Default level)
851
<dt>2
852
<dd>Error queries logged
853
<dt>3
854
<dd>All queries logged
855
<dt>4
856
<dd>All actions adding and removing records from the cache logged
857
</dl>
858
859
<p> The default value for this variable is 1.
860
861
<h2>verbose_query</h2>
862
verbose_query: Whether to verbosely output all DNS queries that the
863
recursive DNS server receives. If this is set to 1, then all recursive
864
queries sent to MaraDNS will be logged.
865
866
<p>
867
868
This is mainly used for debugging.
869
870
<h2>zone_transfer_acl</h2>
871
zone_transfer_acl: List of ips allowed to perform zone transfers
872
with the zone server
873
<p>
874
875
The format of this string is identical to the format of an ipv4_alias
876
entry.
877
878
<h1>EXAMPLE MARARC FILE</h1>
879
880
<pre>
881
<include "../source/example_full_mararc">
882
</pre>
883
884
<h1>BUGS</h1>
885
If one should declare the same the same index twice with
886
a dictionary variable, MaraDNS will exit with a fatal error. This is
887
because earlier versions of MaraDNS acted in a different manner than
888
Python 2.3.3. With Python 2.3.3, the last declaration is used, while
889
MaraDNS used to use the first declaration.
890
891
<h1>LEGAL DISCLAIMER</h1>
892
THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS
893
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
894
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
895
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE
896
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
897
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
898
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
899
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
900
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
901
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
902
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
903
</body>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1