1CSV2(5) MaraDNS reference CSV2(5)
2
6 csv2 - Description of the csv2 zone file that MaraDNS uses
7
9 The csv2 zone file format is the zone file format introduced in MaraDNS
10 1.2. This zone file format uses any kind of whitespace (space, tab,
11 and carriage return), or the '|' character, to deliminate fields.
12 Tilde delimination
14 In MaraDNS 1.3, the tilde ('~') character is used to deliminate records
16 in csv2 zone files; in order to maintain maximum compatibility with
17 MaraDNS 1.2 zone files, this feature is only enabled if a tilde is
18 placed between the first and second record. Otherwise, tildes are not
19 allowed in zone files (except in comments).
20 Most MaraDNS 1.2 csv2 zone files without the tilde character are
22 compatible with the 1.3 csv2 parser, unless csv2_tilde_handling is set
23 to 3. All MaraDNS 1.2 csv2 zone files will parse in MaraDNS 1.3 if
24 csv2_tilde_handling has a value of 0. MaraDNS 1.2, starting with
25 1.2.12.04, also supports the csv2_tilde_handling variable (as long as
26 it has a value of 0); this allows the same configuration and zone files
27 to be used in both MaraDNS 1.2 and MaraDNS 1.3.
28 Resource record format
30 This zone file format has records in the following form:
32 name [+ttl] [rtype] rdata ~
34 The name is the name of the record we will add, such as
36 "www.example.net.". This must be placed at the beginning of a line.
37 The rtype is the record type for the record, such as "A" (ipv4 IP
38 address), "MX" (mail exchanger), or "AAAA" (ipv6 IP address). The ttl
39 is how long other DNS servers should store this data in their memory
40 (in seconds); this field needs a '+' as its initial character. The
41 rdata is the actual data for this record; the format for the rdata is
42 type-specific.
43 Anything in square brackets is an optional field. If the ttl is not
45 specified, the ttl is set to the default ttl value (see "Default TTL"
46 below). If the rtype is not specified, it is set to be an "A" (ipv4
47 address) record.
48 The zone file supports comments; comments are specified by having a '#'
50 anywhere between fields or records; when a '#' is seen, the csv2 parser
51 ignores any character it sees (with the exception of the '{', which is
52 not allowed in comments) until a newline. A '#' can usually be placed
53 inside a field, and indicates the end of a field when placed there.
54 A '{' character can never be placed in a comment. A '~' character is
56 always allowed in a comment, and has no special meaning when placed in
57 a comment.
58 The following record types are supported; a description of the record
60 data format accommodates the record type:
61 A
63 An A record stores an ipv4 address. This is the default record type
65 should the record type not be specified. The record type has one field
66 in it: the IP for the record. Examples:
67 a.example.net. 10.11.12.13 ~
69 b.example.net. A 10.11.12.14 ~
70 c.example.net. +64000 A 10.11.12.15 ~
71 PTR
73 A PTR record stores the name for a given ipv4 or ipv6 address, and is
75 used for reverse DNS lookups. This record type has one field in it: The
76 name for the record in question. Examples:
77 13.12.11.10.in-addr.arpa. PTR a.example.net. ~
79 14.12.11.10.in-addr.arpa. PTR b.example.net. ~
80 15.12.11.10.in-addr.arpa. +64000 PTR c.example.net. ~
81 MX
83 A MX record stores a mail exchange record, and is used for mail
85 delivery. This record type has two fields in it: The priority (or
86 "preference" in traditional DNS parlance) of the MX record (lower
87 numbers get higher priority), and the name of the mail exchanger.
88 Example of mail for example.net being mailed to mail.example.net, which
89 has the IP "10.11.12.16":
90 example.net. MX 10 mail.example.net. ~
92 mail.example.net. 10.11.12.16 ~
93 AAAA
95 An AAAA record stores the ipv6 address for a given name. The IP is in
97 standard ipv6 "colon delimited" format: eight 16-bit hexadecimal
98 numbers are separated by colons. Two colons together indicate multiple
99 streams of all-zero hex numbers. This record has only one field, the v6
100 IP. Example:
101 a.example.net. AAAA 3ffe:ffff:ffe:501:ffff::b:c:d ~
103 SRV
105 An SRV record stores a "service" definition. This record has four
107 fields: Priority, weight, port, and target. For more information,
108 please refer to RFC 2782. Example:
109 _http._tcp.% SRV 0 0 80 a.% ~
111 NS
113 An NS record specifies the name servers for a given zone. If the name
115 servers are not delegation name servers (in other words, if the the
116 name servers are the authoritative name servers for the zone), they
117 need to be at the beginning of the zone, either as the first records in
118 the zone, or right after the SOA record. The NS records are optional;
119 if not present, MaraDNS will make an educated guess of that NS records
120 should be there, based on the IPs the MaraDNS process is bound to. This
121 record has one field: The name of the name server machine. Example:
122 example.net. NS ns1.example.net. ~
124 example.net. NS ns2.example.net. ~
125 SOA
127 An SOA record stores the start of authority for a given zone file.
129 This record is optional in a CSV2 zone file; should the record not be
130 in the zone file, MaraDNS will synthesize an appropriate SOA record.
131 This record can only exist once in a zone file: As the first record of
132 the zone file. This record has seven fields: The name of the zone, the
133 email address of the person responsible for the zone, and five numeric
134 fields (serial, refresh, retry, expire, and minimum). Note that the
135 SOA minimum does not affect other TTLs in MaraDNS. Example:
136 x.org. SOA x.org. email@x.org. 1 7200 3600 604800 1800 ~
138 The serial numeric field may be replaced by the string '/serial'; this
140 string tells the CSV2 zone parser to synthesize a serial number for the
141 zone based on the timestamp for the zone file. This allows one to have
142 the serial number be automatically updated whenever the zone file is
143 edited. Here is how this special field looks in a SOA record:
144 x.org. SOA x.org. email@x.org. /serial 7200 3600 604800 1800 ~
146 The '/serial' string is case-sensitive; only '/serial' in all lower
148 case will parse.
149 TXT
151 A TXT record stores arbitrary text and/or binary data for a given host
153 name. This record has one field: The text data for the record.
154 A basic text record can be stored by placing ASCII data between two
156 single quotes, as follows:
157 example.com. TXT 'This is an example text field' ~
159 Any binary data can be specified; see the csv2_txt(5) manual page for
161 full details.
162 If tildes are used to separate records, a TXT record can not contain a
164 '|' (pipe) character, a '#' character, nor any ASCII control character;
165 these characters can be added to a TXT record via the use of escape
166 sequences; read the csv2_txt man page for details.
167 SPF
169 A SPF record is, with the exception of the numeric rtype, identical to
171 a TXT record. SPF records are designed to make it more difficult to
172 forge email. More information about SPF records can be found in
173 RFC4408, or by performing a web search for 'sender policy framework'.
174 RAW
176 The RAW record is a special meta-record that allows any otherwise
178 unsupported record type to be stored in a csv2 zone file. The syntax
179 is:
180 RAW [numeric rtype] [data] ~
182 The numeric rtype is a decimal number.
184 The data field can, among other thing, have backslashed hex sequences
186 outside of quotes, concatenated by ASCII data inside quotes, such as
187 the following example:
188 example.com. RAW 40 \x10\x01\x02'Kitchen sink'\x40' data' ~
190 The above example is a "Kitchen Sink" RR with a "meaning" of 16, a
192 "coding" of 1, a "subcoding" of 2, and a data string of "Kitchen sink@
193 data" (since hex code 40 corresponds to a @ in ASCII). Note that
194 unquoted hex sequences are concatenated with quoted ASCII data, and
195 that spaces are only inside quoted data.
196 The format for a data field in a RAW record is almost identical to the
198 format for a TXT data field. Both formats are described in full in the
199 csv2_txt(5) manual page.
200 FQDN4
202 The FQDN4 (short for "Fully Qualified Domain Name for IPv4") record is
204 a special form of the "A" record (see above) that instructs MaraDNS to
205 automatically create the corresponding PTR record. For example, the
206 following is one way of setting up the reverse DNS lookup for
207 x.example.net:
208 x.example.net. A 10.3.28.79 ~
210 79.28.3.10.in-addr.arpa. PTR x.example.net. ~
211 But the above two lines in a zone file can also be represented thusly:
213 x.example.net. FQDN4 10.3.28.79 ~
215 Note that the csv2 parser does not bother to check that any given IP
217 only has a single FQDN4 record; it is up to the DNS administrator to
218 ensure that a given IP has only one FQDN4 record. In the case of there
219 being multiple FQDN4 records with the same IP, MaraDNS will have
220 multiple entries in the corresponding PTR record, which is usually not
221 the desired behavior.
222 FQDN4 records are not permitted in a csv2_default_zonefile. If you do
224 not know what a csv2_default_zonefile is, you do not have to worry
225 about this limitation.
226 CNAME
228 A CNAME record is a pointer to another host name. The CNAME record, in
230 MaraDNS, affects any record type not already specified for a given host
231 name. While MaraDNS allows CNAME and non-CNAME records to share the
232 same host name, this is considered bad practice and is not compatible
233 with some other DNS servers.
234 CNAME records are not permitted in a csv2_default_zonefile. If you do
236 not know what a csv2_default_zonefile is, this fact is of no relevance.
237
239 The following resource records are mainly of historical interest, or
240 are not commonly used.
241 HINFO
243 An HINFO record is a description of the CPU (processor) and OS that a
245 given host is using. The format for this record is identical to a TXT
246 record, except that the field must have precisely two chunks.
247 The first chunk of a HINFO record is the CPU the host is running; the
249 second chunk is the OS the host is running.
250 Example:
252 example.com. HINFO 'Intel Pentium III';'CentOS Linux 3.7' ~
254 This resource record is not actively used--the IANA has a list of CPUs
256 and OSes that this record is supposed to have. However, this list has
257 not been updated since 2002.
258 WKS
260 WKS records are historical records which have been superseded by SRV
262 records. The format of the record is an IP, followed by a protocol
263 number (6 means TCP), followed by a list of ports that a given server
264 has available for services.
265 For example, to advertise that example.net has the IP 10.1.2.3, and has
267 a SSH, HTTP (web), and NNTP server:
268 example.net. WKS 10.1.2.3 6 22,80,119 ~
270 MaraDNS only allows up to 10 different port numbers in a WKS record,
272 and requires that the listed port numbers are not be higher than 1023.
273 MD and MF
275 MD and MF records are RR types that existed before MX records, and were
277 made obsolete by MX records. RFC1035 says that a DNS server can either
278 reject these records or convert these records in to MX records. BIND
279 rejects these records; MaraDNS converts them.
280 Example:
282 example.net. MD a.example.net. ~
284 example.net. MF b.example.net. ~
285 Is equivalent to:
287 example.net. MX 0 a.example.net. ~
289 example.net. MX 10 b.example.net. ~
290 MB, MG, MINFO, and MR
292 In the late 1980s, an alternative to MX records was proposed. This
294 alternative utilized MB, MG, MINFO, and MR records. This alternative
295 failed to gather popularity. However, these records were codified in
296 RFC1035, and are supported by MaraDNS. Here is what the records look
297 like:
298 example.net. MB mail.example.net. ~
300 example.net. MG mg@example.net. ~
301 example.net. MINFO rm@example.net. re@example.net. ~
302 example.net. MR mr@example.net. ~
303 More information about these records can be found in RFC1035.
305 AFSDB, RP, X25, ISDN, and RT
307 AFSDB, RP, X25, ISDN, and RT are resource records which were proposed
309 in RFC1183. None of these resource records are widely used.
310 With the exception of the ISDN record, the format of these records is
312 identical to the examples in RFC1183. The format of the ISDN record is
313 identical unless the record has a subaddress (SA). If an ISDN record
314 has a subaddress, it is separated from the ISDN-address by a ';'
315 instead of whitespace.
316 If used, here is how the records would look in a csv2 zone file:
318 example.net. AFSDB 1 afsdb.example.net. ~
320 example.net. RP rp@example.net. rp.example.net. ~
321 example.net. RP rp2@example.net. . ~
322 example.net. X25 311061700956 ~
323 example.net. ISDN 150862028003217 ~
324 example.net. ISDN 150862028003217;004 ~
325 example.net. RT 10 relay.example.net. ~
326 NSAP and NSAP-PTR
328 NSAP and NSAP-PTR records were proposed in RFC1706. A NSAP record is a
330 hexadecimal number preceeded by the string "0x" and with optional dots
331 between bytes. This hexadecimal number is converted in to a binary
332 number by MaraDNS. A NSAP-PTR record is idenical to a PTR record, but
333 has a different RTYPE.
334 More information about these records can be obtained from RFC1706.
336 If used, here is how the records would look in a csv2 zone file:
338 example.net. NSAP 0x47.0005.80.005a00.0000.0001.e133.ffffff000162.00 ~
340 example.net. NSAP-PTR nsap.example.net. ~
341 PX
343 The PX RR is an obscure RR described in RFC2163. A PX record looks like
345 this in a CSV2 zone file:
346 example.net. PX 15 px1.example.net. px2.example.net. ~
348 GPOS
350 An GPOS record is a description of the location of a given server. The
352 format for this record is identical to a TXT record, except that the
353 field must have precisely three chunks.
354 The first chunk of a GPOS record is the longitude; the second chunk is
356 the latitude; the third chunk is the altitude (in meters).
357 Example:
359 example.net. GPOS '-98.6502';'19.283';'2134' ~
361 More information about this record can be found in RFC1712.
363 This resource record is not actively used; for the relatively few
365 people who encode their position in DNS, the LOC record is far more
366 common.
367 LOC
369 The LOC recource record is an uncommonly used resource record that
371 describes the position of a given server. LOC records are described in
372 RFC1876.
373 Note that MaraDNS' LOC parser assumes that the altitude, size,
375 horizontal, and vertical precision numbers are always expressed in
376 meters. Also note that that sub-meter values for size, horizontal, and
377 vertical precision are not allowed. Additionally, the altitude can not
378 be greater than 21374836.47 meters.
379 Example:
381 example.net. LOC 19 31 2.123 N 98 3 4 W 2000m 2m 4m 567m ~
383
386 In addition to being able to have resource records and comments, csv2
387 zone files can also have special slash commands. These slash commands,
388 with the exception of the '/serial' slash command (see "SOA" above),
389 can only be placed where the name for a record would be placed. Like
390 resource records, a tilde is to be placed after the slash command. Note
391 also that slash commands are case-sensitive, and the command in
392 question must be in all-lower-case.
393 These commands are as follows:
395 Default TTL
397 The default TTL is the TTL for a resource record without a TTL
399 specified. This can be changed with the '/ttl' slash command. This
400 command takes only a single argument: The time, in seconds, for the new
401 default TTL. The '/ttl' slash command only affects the TTL of records
402 that follow the command. A zone file can have multiple '/ttl' slash
403 commands.
404 The default TTL is 86400 seconds (one day) until changed by the '/ttl'
406 slash command.
407 In the following example, a.ttl.example.com will have a TTL of 86400
409 seconds (as long as the zone file with this record has not previously
410 used the '/ttl' slash command), b.ttl.example.com and d.ttl.example.com
411 will have a TTL of 3600 seconds, c.ttl.example.com will have a TTL of
412 9600 seconds, and e.ttl.example.com will have a TTL of 7200 seconds:
413 a.ttl.example.com. 10.0.0.1 ~
415 /ttl 3600 ~
416 b.ttl.example.com. 10.0.0.2 ~
417 c.ttl.example.com. +9600 10.0.0.3 ~
418 d.ttl.example.com. 10.0.0.4 ~
419 /ttl 7200 ~
420 e.ttl.example.com. 10.0.0.5 ~
421 Origin
423 It is possible to change the host name suffix that is used to
425 substitute the percent in a csv2 zone file. This suffix is called, for
426 historical and compatibility reasons, "origin". This is done as the
427 slash command '/origin', taking the new origin as the one argument to
428 this function. Note that changing the origin does not change the
429 domain suffix used to determine whether a given domain name is
430 authoritative.
431 Here is one example usage of the '/origin' slash command:
433 /origin example.com. ~
435 www.% 10.1.0.1 ~
436 % MX 10 mail.% ~
437 mail.% 10.1.0.2 ~
438 /origin example.org. ~
439 www.% 10.2.0.1 ~
440 % MX 10 mail.% ~
441 mail.% 10.2.0.2 ~
442 Which is equivalent to:
444 www.example.com. 10.1.0.1 ~
446 example.com. MX 10 mail.example.com. ~
447 mail.example.com. 10.1.0.2 ~
448 www.example.org. 10.2.0.1 ~
449 example.org. MX 10 mail.example.org. ~
450 mail.example.org. 10.2.0.2 ~
451 It is also possible to make the current origin be part of the new
453 origin:
454 /origin example.com. ~
456 % 10.3.2.1 ~ # example.com now has IP 10.3.2.1
457 /origin mail.% ~
458 % 10.3.2.2 ~ # mail.example.com now has IP 10.3.2.2
459 Opush and Opop
461 The '/opush' and '/opop' slash commands use a stack to remember and
463 later recall values for the origin (see origin above). The '/opush'
464 command is used just like the '/origin' command; however, the current
465 origin is placed on a stack instead of discarded. The '/opop' command
466 removes ("pops") the top element from this stack and makes the element
467 the origin.
468 For example:
470 /origin example.com. ~
472 /opush mail.% ~ # origin is now mail.example.com; example.com is on stack
473 a.% 10.4.0.1 ~ # a.mail.example.com has IP 10.4.0.1
474 /opush web.example.com. ~ # mail.example.com and example.com are on stack
475 a.% 10.5.0.1 ~ # a.web.example.com has IP 10.5.0.1
476 b.% 10.5.0.2 ~ # b.web.example.com has IP 10.5.0.2
477 /opop ~ # origin is now mail.example.com again
478 b.% 10.4.0.2 ~ # b.mail.example.com has IP 10.4.0.2
479 /opop ~ # origin is now example.com
480 % MX 10 a.mail.% ~ # example.com. MX 10 a.mail.example.com.
481 % MX 20 b.mail.% ~ # example.com. MX 20 b.mail.example.com.
482 The opush/opop stack can have up to seven elements on it.
484 Read
486 The '/read' slash commands allows one to have the contents of another
488 file in a zone. The '/read' command takes a single argument: A filename
489 that one wishes to read. The filename is only allowed to have letters,
490 numbers, the '-' character, the '_' character, and the '.' character in
491 it.
492 The file needs to be in the same directory as the zone file. The file
494 will be read with the same privileges as the zone file; content in the
495 file should come from a trusted source or be controlled by the system
496 administrator.
497 Let us suppose that we have the following in a zone file:
499 mail.foo.example.com. 10.3.2.1 ~
501 /read foo ~
502 foo.example.com. MX 10 mail.foo.example.com. ~
503 And a file foo with the following contents:
505 foo.example.com. 10.1.2.3 ~
507 foo.example.com. TXT 'Foomatic!' ~
508 Then foo.example.com will have an A record with the value 10.1.2.3, a
510 TXT value of 'Foomatic!', and a MX record with priority 10 pointing to
511 mail.foo.example.com. mail.foo.example.com will have the IP 10.3.2.1.
512 Note that no pre-processing nor post-processing of the origin is done
514 by the '/read' command; should the file read change the origin, this
515 changed value will affect any records after the '/read' command. For
516 example, let us suppose db.example.com looks like this:
517 /origin foo.example.com. ~
519 % TXT 'Foomatic!' ~
520 /read foo ~
521 % MX 10 mail.foo.example.com. ~
522 And the file foo looks like this:
524 % 10.1.2.3 ~
526 /origin mail.% ~
527 % 10.3.2.1 ~
528 Then the following records will be created:
530 foo.example.com. TXT 'Foomatic!' ~
532 foo.example.com. A 10.1.2.3 ~
533 mail.foo.example.com. A 10.3.2.1 ~
534 mail.foo.example.com. MX 10 mail.foo.example.com. ~
535 To have something that works like '$INCLUDE filename' in a RFC1035
537 master file, do the following:
538 /opush % ~
540 /read filename ~
541 /opop ~
542 Or, for that matter, the equivalent of '$INCLUDE filename neworigin':
544 /opush neworigin. ~
546 /read filename ~
547 /opop ~
548
551 # This is an example csv2 zone file
552 # First of all, csv2 zone files do not need an SOA record; however, if
554 # one is provided, we will make it the SOA record for our zone
555 # The SOA record needs to be the first record in the zone if provided
556 # This is a commented out record and disabled.
557 #% SOA % email@% 1 7200 3600 604800 1800 ~
559 # Second of all, csv2 zone files do not need authoritative NS records.
561 # If they aren't there, MaraDNS will synthesize them, based on the IP
562 # addresses MaraDNS is bound to. (She's pretty smart about this; if
563 # Mara is bound to both public and private IPs, only the public IPs will
564 # be synthesized as NS records)
565 #% NS a.% ~
568 #% NS b.% ~
569 # Here are some A (ipv4 address) records; since this is the most
571 # common field, the zone file format allows a compact representation
572 # of it.
573 a.example.net. 10.10.10.10 ~
574 # Here, you can see that a single name, "b.example.net." has multiple IPs
575 # This can be used as a primitive form of load balancing; MaraDNS will
576 # rotate the IPs so that first IP seen by a DNS client changes every time
577 # a query for "b.example.net." is made
578 b.example.net. 10.10.10.11 ~
579 b.example.net. 10.10.10.12 ~
580 # We can have the label in either case; it makes no difference
582 Z.EXAMPLE.NET. 10.2.3.4 ~
583 Y.EXAMPLE.net. 10.3.4.5 ~
584 # We can use the percent shortcut. When the percent shortcut is present,
586 # it indicates that the name in question should terminate with the name
587 # of the zone we are processing.
588 percent.% a 10.9.8.7 ~
589 # And we can have star records
591 #*.example.net. A 10.11.12.13 ~
592 # We can have a ttl in a record; however the ttl needs a '+' before it:
594 # Note that the ttl has to be in seconds, and is before the RTYPE
595 d.example.net. +86400 A 10.11.12.13 ~
596 f.example.net. # As you can see, records can span multiple lines
598 A 10.2.19.83 ~
599 # This allows well-commented records, like this:
601 c.example.net. # Our C class machine
602 +86400 # This record is stored for one day
603 A # A record
604 10.1.1.1 # Where we are
605 ~ # End of record
606 # We can even have something similiar to csv1 if we want...
608 e.example.net.|+86400|a|10.2.3.4|~
609 h.example.net.|a|10.9.8.7|~
610 # Here, we see we can specify the ttl but not the rtype if desired
611 g.example.net.|+86400|10.11.9.8|~
612 # Here is a MX record
614 % mx 10 mail.% ~
615 mail.% +86400 IN A 10.22.23.24 ~
616 # We even have a bit of ipv6 support
618 a.example.net. aaaa 3ffe:ffff:1:2:3::4:f ~
619 # Not to mention support for SRV records
621 _http._tcp.% srv 0 0 80 a.% ~
622 # TXT records, naturally
624 example.net. txt 'This is some text' ~
625 # Starting with MaraDNS 1.2.08, there is also support for SPF records,
627 # which are identical to TXT records. See RFC4408 for more details.
628 example.net. spf 'v=spf1 +mx a:colo.example.com/28 -all' ~
629
635 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR
636 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
637 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
638 DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
639 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
640 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
641 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
642 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
643 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
644 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
645 POSSIBILITY OF SUCH DAMAGE.
646
648 Sam Trenholme http://www.samiam.org/
649MARADNS January 2007 CSV2(5)