1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915
|
.\" Do *not* edit this file; it was automatically generated by ej2man
.\" Look for a name.ej file with the same name as this filename
.\"
.\" Process this file with the following
.\" nroff -man -Tutf8 maradns.8 | tr '\020' ' '
.\"
.\" Last updated Tue Aug 18 21:44:50 2015
.\"
.TH CSV2 5 "January 2007" MARADNS "MaraDNS reference"
.\" We don't want hyphenation (it's too ugly)
.\" We also disable justification when using nroff
.\" Due to the way the -mandoc macro works, this needs to be placed
.\" after the .TH heading
.hy 0
.if n .na
.\"
.\" We need the following stuff so that we can have single quotes
.\" In both groff and other UNIX *roff processors
.if \n(.g .mso www.tmac
.ds aq \(aq
.if !\n(.g .if '\(aq'' .ds aq \'
.SH "NAME"
.PP
csv2 - Description of the csv2 zone file that MaraDNS uses
.SH "DESCRIPTION"
.PP
The csv2 zone file format is MaraDNS\(aq standard zone file format.
This zone file format uses any kind of whitespace (space, tab, and
carriage
return), or the \(aq|\(aq character, to delimit fields.
.PP
.in -3
\fBTilde delimitation\fR
.PP
In newer MaraDNS releases, the tilde (\(aq~\(aq) character is used to
delimit
records in csv2 zone files; in order to maintain maximum compatibility
with older MaraDNS zone files, this feature is only enabled if a tilde
is
placed between the first and second record. Otherwise, tildes are not
allowed in zone files (except in comments).
.PP
Most older MaraDNS csv2 zone files without the tilde character are
compatible with the updated csv2 parser, unless csv2_tilde_handling
is set to 3. All older MaraDNS csv2 zone files will parse in MaraDNS
if csv2_tilde_handling has a value of 0. Older MaraDNS releases
also supported the csv2_tilde_handling variable (as long as it
had a value of 0); this allowed the same configuration and zone files
to
be used in older and newer MaraDNS releases.
.PP
.in -3
\fBResource record format\fR
.PP
This zone file format has records in the following form:
.PP
.RS 4
name [+ttl] [rtype] rdata ~
.RE
.PP
The name is the name of the record we will add, such as
"www.example.net.".
This must be placed at the beginning of a line.
The rtype is the record type for the record, such as "A" (ipv4 IP
address),
"MX" (mail exchanger), or "AAAA" (ipv6 IP address). The ttl is how long
other DNS servers should store this data in their memory (in seconds);
this field needs a \(aq+\(aq as its initial character. The rdata is
the actual data for this record; the format for the rdata is
type-specific.
.PP
Anything in square brackets is an optional field. If the ttl is not
specified, the ttl is set to the default ttl value (see "Default TTL"
below).
If the rtype is not specified, it is set to be an "A" (ipv4 address)
record.
.PP
The zone file supports comments; comments are specified by having a
\(aq#\(aq
anywhere between fields or records; when a \(aq#\(aq is seen, the csv2
parser
ignores any character it sees (with the exception of the \(aq{\(aq,
which
is not allowed in comments) until a newline. A \(aq#\(aq can usually be
placed inside a field, and indicates the end of a field when placed
there.
.PP
A \(aq{\(aq character can never be placed in a comment. A \(aq~\(aq
character is always
allowed in a comment, and has no special meaning when placed in a
comment.
.PP
The following record types are supported; a description of the record
data
format accommodates the record type:
.PP
.in -3
\fBA\fR
.PP
An A record stores an ipv4 address. This is the default record type
should
the record type not be specified. The record type has one field in it:
the IP for the record. Examples:
.nf
a.example.net. 10.11.12.13 ~
b.example.net. A 10.11.12.14 ~
c.example.net. +64000 A 10.11.12.15 ~
.fi
.PP
.in -3
\fBPTR\fR
.PP
A PTR record stores the name for a given ipv4 or ipv6 address, and is
used
for reverse DNS lookups. This record type has one field in it: The name
for the record in question. Examples:
.nf
13.12.11.10.in-addr.arpa. PTR a.example.net. ~
14.12.11.10.in-addr.arpa. PTR b.example.net. ~
15.12.11.10.in-addr.arpa. +64000 PTR c.example.net. ~
.fi
.PP
.in -3
\fBMX\fR
.PP
A MX record stores a mail exchange record, and is used for mail
delivery.
This record type has two fields in it: The priority (or "preference" in
traditional DNS parlance) of the MX record (lower numbers get higher
priority), and the name of the mail exchanger. Example of mail
for example.net being mailed to mail.example.net, which has the IP
"10.11.12.16":
.nf
example.net. MX 10 mail.example.net. ~
mail.example.net. 10.11.12.16 ~
.fi
.PP
.in -3
\fBAAAA\fR
.PP
An AAAA record stores the ipv6 address for a given name. The IP is
in standard ipv6 "colon delimited" format: eight 16-bit hexadecimal
numbers are separated by colons. Two colons together indicate multiple
streams of all-zero hex numbers. This record has only one field,
the v6 IP. Example:
.nf
a.example.net. AAAA fd4d:6172:6144:4e53:ffe::f ~
.fi
.PP
.in -3
\fBSRV\fR
.PP
An SRV record stores a "service" definition. This record has four
fields: Priority, weight, port, and target. For more information,
please refer to RFC 2782. Example:
.nf
_http._tcp.% SRV 0 0 80 a.% ~
.fi
.PP
.in -3
\fBNAPTR\fR
.PP
A NAPTR record is described in RFC 2915. Example:
.nf
www.example.com. NAPTR 100 100 \(aqs\(aq;\(aqhttp+I2R\(aq;\(aq\(aq _http._tcp.example.com. ~
.fi
Note the semicolons. Because of a bug in MaraDNS 1.4.03 and earlier
releases, NAPTR records will not parse unless a ~ is
.I "not"
used to
separate records; a patch to fix this bug is available
here.
.PP
.in -3
\fBNS\fR
.PP
An NS record specifies the name servers for a given zone. If the name
servers are not delegation name servers (in other words, if the name
servers are the authoritative name servers for the zone), they need to
be
at the beginning of the zone, either as the first records in the zone,
or
right after the SOA record. The NS records are optional; if not
present,
MaraDNS will make an educated guess of that NS records should be there,
based on the IPs the MaraDNS process is bound to. This record has one
field: The name of the name server machine. Example:
.nf
example.net. NS ns1.example.net. ~
example.net. NS ns2.example.net. ~
.fi
.PP
.in -3
\fBSOA\fR
.PP
An SOA record stores the start of authority for a given zone file.
This record is optional in a CSV2 zone file; should the record not
be in the zone file, MaraDNS will synthesize an appropriate SOA
record. This record can only exist once in a zone file: As the first
record of the zone file. This record has seven fields: The name of
the zone, the email address of the person responsible for the zone,
and five numeric fields (serial, refresh, retry, expire, and minimum).
Note that the SOA minimum does
.I "not"
affect other TTLs in MaraDNS.
Example:
.nf
x.org. SOA x.org. email@x.org. 1 7200 3600 604800 1800 ~
.fi
If there is a \(aq.\(aq (dot) character in the part of the email
address before
the \(aq@\(aq, it needs to be escaped thusly:
.nf
x.org. SOA x.org. john\\.doe@x.org. 1 7200 3600 604800 1800 ~
.fi
Note that the csv2 parser will not allow more than one dot in a row;
\(aqjohn\\.\\.doe@x.org\(aq will cause a parse error. In addition, the
dot character must be escaped with a backslash.
.PP
The serial numeric field may be replaced by the string \(aq/serial\(aq;
this
string tells the CSV2 zone parser to synthesize a serial number for the
zone based on the timestamp for the zone file. This allows one to
have the serial number be automatically updated whenever the zone file
is
edited. Here is how this special field looks in a SOA record:
.nf
x.org. SOA x.org. email@x.org. /serial 7200 3600 604800 1800 ~
.fi
The \(aq/serial\(aq string is case-sensitive; only \(aq/serial\(aq in
all lower
case will parse.
.PP
.in -3
\fBTXT\fR
.PP
A TXT record stores arbitrary text and/or binary data for a given
host name. This record has one field: The text data for the record.
.PP
A basic text record can be stored by placing ASCII data between two
single
quotes, as follows:
.nf
example.com. TXT \(aqThis is an example text field\(aq ~
.fi
Any binary data can be specified; see the
.B "csv2_txt(5)"
manual page
for full details.
.PP
If tildes are used to separate records, a TXT record can not contain
a literal \(aq|\(aq (pipe) character, a \(aq#\(aq literal, a \(aq~\(aq
literal, nor any
ASCII control literal; these characters can be added to a TXT record
via the use of escape sequences; read the
csv2_txt man page for details.
.PP
.in -3
\fBSPF\fR
.PP
A SPF record is, with the exception of the numeric rtype, identical to
a TXT record. SPF records are designed to make it more difficult to
forge email.
Here is one example SPF record:
.nf
example.com. SPF \(aqv=spf1 +mx a:colo.example.com/28 -all\(aq
.fi
Use \(aq\\x7e\(aq to put a tilde ("~" character) in a SPF record:
.nf
example.com. SPF \(aqv=spf1 +mx a:colo.example.com/28 \(aq\\x7e\(aqall\(aq
.fi
More information about SPF records can be found in
RFC4408, or by performing a web search for \(aqsender policy
framework\(aq.
.PP
.in -3
\fBRAW\fR
.PP
The RAW record is a special meta-record that allows any otherwise
unsupported record type to be stored in a csv2 zone file. The
syntax is:
.nf
RAW [numeric rtype] [data] ~
.fi
The numeric rtype is a decimal number.
.PP
The data field can, among other thing, have backslashed hex sequences
outside of quotes, concatenated by ASCII data inside quotes, such as
the following example:
.nf
example.com. RAW 40 \\x10\\x01\\x02\(aqKitchen sink\(aq\\x40\(aq data\(aq ~
.fi
The above example is a "Kitchen Sink" RR with a "meaning" of 16, a
"coding"
of 1, a "subcoding" of 2, and a data string of "Kitchen sink@ data"
(since
hex code 40 corresponds to a @ in ASCII). Note that unquoted hex
sequences are concatenated with quoted ASCII data, and that spaces are
.I "only"
inside quoted data.
.PP
The format for a data field in a RAW record is almost identical to the
format for a TXT data field. Both formats are described in full in the
.B "csv2_txt(5)"
manual page.
.PP
.in -3
\fBFQDN4\fR
.PP
The FQDN4 (short for "Fully Qualified Domain Name for IPv4") record is
a special form of the "A" record (see above) that instructs MaraDNS
to automatically create the corresponding PTR record. For example,
the following is one way of setting up the reverse DNS lookup for
x.example.net:
.nf
x.example.net. A 10.3.28.79 ~
79.28.3.10.in-addr.arpa. PTR x.example.net. ~
.fi
But the above two lines in a zone file can also be represented thusly:
.nf
x.example.net. FQDN4 10.3.28.79 ~
.fi
Note that the csv2 parser does not bother to check that any given IP
only has a single FQDN4 record; it is up to the DNS administrator to
ensure that a given IP has only one FQDN4 record. In the case of
there being multiple FQDN4 records with the same IP, MaraDNS will
have multiple entries in the corresponding PTR record, which is
usually not the desired behavior.
.PP
FQDN4 records are not permitted in a csv2_default_zonefile. If you
do not know what a csv2_default_zonefile is, you do not have to worry
about this limitation.
.PP
.in -3
\fBFQDN6\fR
.PP
The FQDN6 (short for "Fully Qualified Domain Name for IPv6") record is
the ipv6 form for the FQDN4 record. Like the FQDN4 record, this
record creates both a "forward" and "reverse" DNS record for a given
host name. For example, onoe may have:
.nf
x.example.net. AAAA fd4d:6172:6144:4e53::b:c:d ~
d.0.0.0.c.0.0.0.b.0.0.0.0.0.0.0.3.5.e.4.4.4.1.6.2.7.1.6.d.4.d.f PTR
x.example.net. ~
.fi
But the above two lines in a zone file can also be represented thusly:
.nf
x.example.net. FQDN6 fd4d:6172:6144:4e53::b:c:d ~
.fi
Like FQDN4 records, it is the DNS administrator\(aqs duty to make sure
only a single IP has a FQDN6 record.
.PP
FQDN6 records are, like FQDN4 records, not permitted in a
csv2_default_zonefile. If you do not know what a csv2_default_zonefile
is, you do not have to worry about this limitation.
.PP
FQDN6 records were implemented by Jean-Jacques Sarton.
.PP
.in -3
\fBCNAME\fR
.PP
A CNAME record is a pointer to another host name. The CNAME record, in
MaraDNS, affects any record type not already specified for a given host
name. While MaraDNS allows CNAME and non-CNAME records to share the
same host name, this is considered bad practice and is not compatible
with some other DNS servers.
.PP
CNAME records are not permitted in a csv2_default_zonefile. If you
do not know what a csv2_default_zonefile is, this fact is of no
relevance.
.SH "Historical and uncommon resource records"
.PP
The following resource records are mainly of historical interest, or
are not commonly used.
.PP
.in -3
\fBHINFO\fR
.PP
An HINFO record is a description of the CPU (processor) and OS that
a given host is using. The format for this record is identical to a
TXT record, except that the field must have precisely two chunks.
.PP
The first chunk of a HINFO record is the CPU the host is running; the
second chunk is the OS the host is running.
.PP
Example:
.nf
example.com. HINFO \(aqIntel Pentium III\(aq;\(aqCentOS Linux 3.7\(aq ~
.fi
This resource record is not actively used--the IANA
has a list of CPUs and OSes that this record is supposed to have.
However,
this list has not been updated since 2002.
.PP
.in -3
\fBWKS\fR
.PP
WKS records are historical records which have been superseded by SRV
records. The format of the record is an IP, followed by a protocol
number (6 means TCP), followed by a list of ports that a given server
has available for services.
.PP
For example, to advertise that example.net has the IP 10.1.2.3, and has
a
SSH, HTTP (web), and NNTP server:
.nf
example.net. WKS 10.1.2.3 6 22,80,119 ~
.fi
MaraDNS only allows up to 10 different port numbers in a WKS record,
and requires that the listed port numbers are not be higher than 1023.
.PP
.in -3
\fBMD and MF\fR
.PP
MD and MF records are RR types that existed before MX records, and were
made obsolete by MX records. RFC1035 says that a DNS server can either
reject these records or convert these records in to MX records. BIND
rejects these records; MaraDNS converts them.
.PP
Example:
.nf
example.net. MD a.example.net. ~
example.net. MF b.example.net. ~
.fi
Is equivalent to:
.nf
example.net. MX 0 a.example.net. ~
example.net. MX 10 b.example.net. ~
.fi
.PP
.in -3
\fBMB, MG, MINFO, and MR\fR
.PP
In the late 1980s, an alternative to MX records was proposed. This
alternative utilized MB, MG, MINFO, and MR records. This alternative
failed to gather popularity. However, these records were codified in
RFC1035, and are supported by MaraDNS. Here is what the records look
like:
.nf
example.net. MB mail.example.net. ~
example.net. MG mg@example.net. ~
example.net. MINFO rm@example.net. re@example.net. ~
example.net. MR mr@example.net. ~
.fi
More information about these records can be found in RFC1035.
.PP
.in -3
\fBAFSDB, RP, X25, ISDN, and RT\fR
.PP
AFSDB, RP, X25, ISDN, and RT are resource records which were
proposed in RFC1183. None of these resource records are widely
used.
.PP
With the exception of the ISDN record, the format of these records
is identical to the examples in RFC1183. The format of the ISDN
record is identical unless the record has a subaddress (SA). If
an ISDN record has a subaddress, it is separated from the ISDN-address
by a \(aq;\(aq instead of whitespace.
.PP
If used, here is how the records would look in a csv2 zone file:
.nf
example.net. AFSDB 1 afsdb.example.net. ~
example.net. RP rp@example.net. rp.example.net. ~
example.net. RP rp2@example.net. . ~
example.net. X25 311061700956 ~
example.net. ISDN 150862028003217 ~
example.net. ISDN 150862028003217;004 ~
example.net. RT 10 relay.example.net. ~
.fi
.PP
.in -3
\fBNSAP and NSAP-PTR\fR
.PP
NSAP and NSAP-PTR records were proposed in RFC1706. A NSAP record is
a hexadecimal number preceded by the string "0x" and with optional dots
between bytes. This hexadecimal number is converted in to a binary
number
by MaraDNS. A NSAP-PTR record is identical to a PTR record, but has a
different RTYPE.
.PP
More information about these records can be obtained from RFC1706.
.PP
If used, here is how the records would look in a csv2 zone file:
.nf
example.net. NSAP 0x47.0005.80.005a00.0000.0001.e133.ffffff000162.00 ~
example.net. NSAP-PTR nsap.example.net. ~
.fi
.PP
.in -3
\fBPX\fR
.PP
The PX RR is an obscure RR described in RFC2163. A PX record looks like
this in a CSV2 zone file:
.nf
example.net. PX 15 px1.example.net. px2.example.net. ~
.fi
.PP
.in -3
\fBGPOS\fR
.PP
An GPOS record is a description of the location of a given server.
The format for this record is identical to a
TXT record, except that the field must have precisely three chunks.
.PP
The first chunk of a GPOS record is the longitude; the second chunk is
the latitude; the third chunk is the altitude (in meters).
.PP
Example:
.nf
example.net. GPOS \(aq-98.6502\(aq;\(aq19.283\(aq;\(aq2134\(aq ~
.fi
More information about this record can be found in RFC1712.
.PP
This resource record is not actively used; for the relatively few
people
who encode their position in DNS, the LOC record is far more common.
.PP
.in -3
\fBLOC\fR
.PP
The LOC resource record is an uncommonly used resource record that
describes the position of a given server. LOC records are described
in RFC1876.
.PP
Note that MaraDNS\(aq LOC parser assumes that the altitude,
size, horizontal, and vertical precision numbers are always expressed
in meters. Also note that that sub-meter values for size, horizontal,
and
vertical precision are not allowed. Additionally, the altitude can not
be greater than 21374836.47 meters.
.PP
Example:
.nf
example.net. LOC 19 31 2.123 N 98 3 4 W 2000m 2m 4m 567m ~
.fi
.SH "SLASH COMMANDS"
.PP
In addition to being able to have resource records and comments, csv2
zone files can also have special slash commands. These slash commands,
with the exception of the \(aq/serial\(aq slash command (see "SOA"
above),
can only be placed where the name for a record would be placed.
Like resource records, a tilde is to be placed after the
slash command. Note also that slash commands are case-sensitive, and
the command in question must be in all-lower-case.
.PP
These commands are as follows:
.PP
.in -3
\fBDefault TTL\fR
.PP
The default TTL is the TTL for a resource record without a TTL
specified.
This can be changed with the \(aq/ttl\(aq slash command. This command
takes only a single argument: The time, in seconds, for the new default
TTL.
The \(aq/ttl\(aq slash command only affects the TTL of records that
follow the
command. A zone file can have multiple \(aq/ttl\(aq slash commands.
.PP
The default TTL is 86400 seconds (one day) until changed by the
\(aq/ttl\(aq
slash command.
.PP
In the following example, a.ttl.example.com will have a TTL of 86400
seconds (as long as the zone file with this record has not previously
used
the \(aq/ttl\(aq slash command), b.ttl.example.com and
d.ttl.example.com will
have a TTL of 3600 seconds, c.ttl.example.com will have a TTL of 9600
seconds, and e.ttl.example.com will have a TTL of 7200 seconds:
.nf
a.ttl.example.com. 10.0.0.1 ~
/ttl 3600 ~
b.ttl.example.com. 10.0.0.2 ~
c.ttl.example.com. +9600 10.0.0.3 ~
d.ttl.example.com. 10.0.0.4 ~
/ttl 7200 ~
e.ttl.example.com. 10.0.0.5 ~
.fi
.PP
.in -3
\fBOrigin\fR
.PP
It is possible to change the host name suffix that is used to
substitute the
percent in a csv2 zone file. This suffix is called, for historical and
compatibility reasons, "origin". This is done as the slash command
\(aq/origin\(aq, taking the new origin as the one argument to this
function.
Note that changing the origin does
.I "not"
change the domain suffix
used to determine whether a given domain name is authoritative.
.PP
Here is one example usage of the \(aq/origin\(aq slash command:
.nf
/origin example.com. ~
www.% 10.1.0.1 ~
% MX 10 mail.% ~
mail.% 10.1.0.2 ~
/origin example.org. ~
www.% 10.2.0.1 ~
% MX 10 mail.% ~
mail.% 10.2.0.2 ~
.fi
Which is equivalent to:
.nf
www.example.com. 10.1.0.1 ~
example.com. MX 10 mail.example.com. ~
mail.example.com. 10.1.0.2 ~
www.example.org. 10.2.0.1 ~
example.org. MX 10 mail.example.org. ~
mail.example.org. 10.2.0.2 ~
.fi
It is also possible to make the current origin be part of the new
origin:
.nf
/origin example.com. ~
% 10.3.2.1 ~ # example.com now has IP 10.3.2.1
/origin mail.% ~
% 10.3.2.2 ~ # mail.example.com now has IP 10.3.2.2
.fi
.PP
.in -3
\fBOpush and Opop\fR
.PP
The \(aq/opush\(aq and \(aq/opop\(aq slash commands use a stack to
remember and later
recall values for the origin (see origin above). The \(aq/opush\(aq
command
is used just like the \(aq/origin\(aq command; however, the current
origin is
placed on a stack instead of discarded. The \(aq/opop\(aq command
removes
("pops") the top element from this stack and makes the element the
origin.
.PP
For example:
.nf
/origin example.com. ~
/opush mail.% ~ # origin is now mail.example.com; example.com is on stack
a.% 10.4.0.1 ~ # a.mail.example.com has IP 10.4.0.1
/opush web.example.com. ~ # mail.example.com and example.com are on stack
a.% 10.5.0.1 ~ # a.web.example.com has IP 10.5.0.1
b.% 10.5.0.2 ~ # b.web.example.com has IP 10.5.0.2
/opop ~ # origin is now mail.example.com again
b.% 10.4.0.2 ~ # b.mail.example.com has IP 10.4.0.2
/opop ~ # origin is now example.com
% MX 10 a.mail.% ~ # example.com. MX 10 a.mail.example.com.
% MX 20 b.mail.% ~ # example.com. MX 20 b.mail.example.com.
.fi
The opush/opop stack can have up to seven elements on it.
.PP
.in -3
\fBRead\fR
.PP
The \(aq/read\(aq slash commands allows one to have the contents of
another
file in a zone. The \(aq/read\(aq command takes a single argument: A
filename
that one wishes to read. The filename is only allowed to have letters,
numbers, the \(aq-\(aq character, the \(aq_\(aq character, and the
\(aq.\(aq character in it.
.PP
The file needs to be in the same directory as the zone file. The file
will
be read with the same privileges as the zone file; content in the file
should come from a trusted source or be controlled by the system
administrator.
.PP
Let us suppose that we have the following in a zone file:
.nf
mail.foo.example.com. 10.3.2.1 ~
/read foo ~
foo.example.com. MX 10 mail.foo.example.com. ~
.fi
And a file foo with the following contents:
.nf
foo.example.com. 10.1.2.3 ~
foo.example.com. TXT \(aqFoomatic!\(aq ~
.fi
Then foo.example.com will have an A record with the value 10.1.2.3, a
TXT value of \(aqFoomatic!\(aq, and a MX record with priority 10
pointing to
mail.foo.example.com. mail.foo.example.com will have the IP 10.3.2.1.
.PP
Note that no pre-processing nor post-processing of the origin is done
by the \(aq/read\(aq command; should the file read change the origin,
this
changed value will affect any records after the \(aq/read\(aq command.
For
example, let us suppose db.example.com looks like this:
.nf
/origin foo.example.com. ~
% TXT \(aqFoomatic!\(aq ~
/read foo ~
% MX 10 mail.foo.example.com. ~
.fi
And the file foo looks like this:
.nf
% 10.1.2.3 ~
/origin mail.% ~
% 10.3.2.1 ~
.fi
Then the following records will be created:
.nf
foo.example.com. TXT \(aqFoomatic!\(aq ~
foo.example.com. A 10.1.2.3 ~
mail.foo.example.com. A 10.3.2.1 ~
mail.foo.example.com. MX 10 mail.foo.example.com. ~
.fi
To have something that works like \(aq$INCLUDE filename\(aq in a
RFC1035
master file, do the following:
.nf
/opush % ~
/read filename ~
/opop ~
.fi
Or, for that matter, the equivalent of \(aq$INCLUDE filename
neworigin\(aq:
.nf
/opush neworigin. ~
/read filename ~
/opop ~
.fi
.SH "EXAMPLE ZONE FILE"
.PP
.nf
# This is an example csv2 zone file
# First of all, csv2 zone files do not need an SOA record; however, if
# one is provided, we will make it the SOA record for our zone
# The SOA record needs to be the first record in the zone if provided
# This is a commented out record and disabled.
#% SOA % email@% 1 7200 3600 604800 1800 ~
# Second of all, csv2 zone files do not need authoritative NS records.
# If they aren\(aqt there, MaraDNS will synthesize them, based on the IP
# addresses MaraDNS is bound to. (She\(aqs pretty smart about this; if
# Mara is bound to both public and private IPs, only the public IPs will
# be synthesized as NS records)
#% NS a.% ~
#% NS b.% ~
# Here are some A (ipv4 address) records; since this is the most
# common field, the zone file format allows a compact representation
# of it.
a.example.net. 10.10.10.10 ~
# Here, you can see that a single name, "b.example.net." has multiple IPs
# This can be used as a primitive form of load balancing; MaraDNS will
# rotate the IPs so that first IP seen by a DNS client changes every time
# a query for "b.example.net." is made
b.example.net. 10.10.10.11 ~
b.example.net. 10.10.10.12 ~
# We can have the label in either case; it makes no difference
Z.EXAMPLE.NET. 10.2.3.4 ~
Y.EXAMPLE.net. 10.3.4.5 ~
# We can use the percent shortcut. When the percent shortcut is present,
# it indicates that the name in question should terminate with the name
# of the zone we are processing.
percent.% a 10.9.8.7 ~
# And we can have star records
#*.example.net. A 10.11.12.13 ~
# We can have a ttl in a record; however the ttl needs a \(aq+\(aq before it:
# Note that the ttl has to be in seconds, and is before the RTYPE
d.example.net. +86400 A 10.11.12.13 ~
f.example.net. # As you can see, records can span multiple lines
A 10.2.19.83 ~
# This allows well-commented records, like this:
c.example.net. # Our C class machine
+86400 # This record is stored for one day
A # A record
10.1.1.1 # Where we are
~ # End of record
# We can even have something similar to csv1 if we want...
e.example.net.|+86400|a|10.2.3.4|~
h.example.net.|a|10.9.8.7|~
# Here, we see we can specify the ttl but not the rtype if desired
g.example.net.|+86400|10.11.9.8|~
# Here is a MX record
% mx 10 mail.% ~
mail.% +86400 IN A 10.22.23.24 ~
# We even have a bit of ipv6 support
a.example.net. aaaa fd4d:6172:6144:4e53:1:2:3::4:f ~
# Not to mention support for SRV records
_http._tcp.% srv 0 0 80 a.% ~
# TXT records, naturally
example.net. txt \(aqThis is some text\(aq ~
# Starting with MaraDNS 1.2.08, there is also support for SPF records,
# which are identical to TXT records. See RFC4408 for more details.
example.net. spf \(aqv=spf1 +mx a:colo.example.com/28 \-all\(aq ~
.fi
.SH "LEGAL DISCLAIMER"
.PP
THIS SOFTWARE IS PROVIDED BY THE AUTHORS \(aq\(aqAS IS\(aq\(aq AND ANY
EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.SH "AUTHOR"
.PP
Sam Trenholme
http://www.samiam.org/
|