<HEAD>
<TH>CSV2 5 "June 2004" MARADNS "MaraDNS reference"</TH>
<DTWIDTH>3</DTWIDTH>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=utf-8">
</HEAD>
<BODY>
<h1>NAME</h1>
csv2 - Description of the csv2 zone file that MaraDNS uses
<h1>DESCRIPTION</h1>
The csv2 zone file format is the new zone file format for MaraDNS 1.2.
This zone file format uses any kind of whitespace (space, tab, and carriage
return), or the '|' character, to deliminate fields.  The zone file parser
is smart enough to know how many fields the record data for a given record
type needs; once all the fields for a given record type is processed,
the parser parses the next entry it sees as the name for the next
record to process.
<p>

This zone file format has records in the following form:

<blockquote>
name [+ttl] [rtype] rdata
</blockquote>

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 '+' as its initial character.  The rdata is
the actual data for this record; the format for the rdata is type-specific.
<p>

Anything in square brackets is an optional field.  If the ttl is not 
specified, the ttl is set to be 86400 seconds long (one day).  If the rtype
is not specified, it is set to be an "A" (ipv4 address) record.  
<p>

The zone file supports comments; comments are specified by having a '#' 
anywhere between fields or records; when a '#' is seen, the csv2 parser 
ignores any character it sees (with the exception of the '{' character,
which is not currently allowed in csv2 zone files) until a newline.  
A '#' can usually be placed inside a field, and indicates the end of a 
field when placed there.
<p>

The following record types are supported; a description of the record data
format accommodates the record type:

<h2>A</h2>

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:

<pre>
a.example.net.              10.11.12.13
b.example.net.        A     10.11.12.14
c.example.net. +64000 A     10.11.12.15
</pre>

<h2>PTR</h2>

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:

<pre>
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.
</pre>

<h2>MX</h2>

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":

<pre>
example.net.      MX   10 mail.example.net.
mail.example.net.      10.11.12.16
</pre>

<h2>AAAA</h2>

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:

<pre>
a.example.net.   AAAA    3ffe:ffff:ffe:501:ffff::b:c:d
</pre>

<h2>SRV</h2>

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:

<pre>
_http._tcp.% SRV 0 0 80 a.%
</pre>

<h2>NS</h2>

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 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:

<pre>
example.net.    NS    ns1.example.net.
example.net.    NS    ns2.example.net.
</pre>

<h2>SOA</h2>

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</i> affect other TTLs in MaraDNS.
Example:

<pre>
x.org. SOA x.org. email@x.org. 1 7200 3600 604800 1800
</pre>

The serial numeric field may be replaced by the string '/serial'; 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:

<pre>
x.org. SOA x.org. email@x.org. /serial 7200 3600 604800 1800
</pre>

The '/serial' string is case-sensitive; only '/serial' in all lower
case will parse.  

<h2>TXT</h2>

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.

<p>

A basic text record can be stored by placing ASCII data between two single
quotes, as follows:

<pre>
example.com. TXT 'This is an example text field'
</pre>

Any binary data can be specified; see the <b>csv2_txt(5)</b> manual page
for full details.

<h2>SPF</h2>

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.  More information about SPF records can be found in 
RFC4408, or by performing a web search for 'sender policy framework'.

<h2>RAW</h2>

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:

<pre>
RAW [numeric rtype] [data] 
</pre>

The numeric rtype is a decimal number.

<p>

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:

<pre>
example.com. RAW 40 \x10\x01\x02'Kitchen sink'\x40' data'
</pre>

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</i> inside quoted data.

<p>

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)</b> manual page.

<h2>FQDN4</h2>

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:

<pre>
x.example.net. A 10.3.28.79
79.28.3.10.in-addr.arpa. PTR x.example.net.
</pre>

But the above two lines in a zone file can also be represented thusly:

<pre>
x.example.net. FQDN4 10.3.28.79
</pre>

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.

<p>

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.

<h2>CNAME</h2>

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.

<p>

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.

<h1>Historical and uncommon resource records</h1>

The following resource records are mainly of historical interest, or
are not commonly used.

<h2>HINFO</h2>

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.

<p>

The first chunk of a HINFO record is the CPU the host is running; the
second chunk is the OS the host is running.

<p>

Example:

<pre>
example.com. HINFO 'Intel Pentium III';'CentOS Linux 3.7'
</pre>

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.

<h2>WKS</h2>

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.

<p>

For example, to advertise that example.net has the IP 10.1.2.3, and has a
SSH, HTTP (web), and NNTP server:

<pre>
example.net. WKS 10.1.2.3 6 22,80,119
</pre>

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.

<h2>MD and MF</h2>

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.

<p>

Example:

<pre>
example.net. MD a.example.net.
example.net. MF b.example.net.
</pre>

Is equivalent to:

<pre>
example.net. MX 0 a.example.net.
example.net. MX 10 b.example.net.
</pre>

<h2>MB, MG, MINFO, and MR</h2>

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:

<pre>
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.
</pre>

More information about these records can be found in RFC1035.

<h2>AFSDB, RP, X25, ISDN, and RT</h2>

AFSDB, RP, X25, ISDN, and RT are resource records which were 
proposed in RFC1183.  None of these resource records are widely
used.

<p>

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 ';' instead of whitespace.

<p>

If used, here is how the records would look in a csv2 zone file:

<pre>
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.
</pre>

<h2>NSAP and NSAP-PTR</h2>

NSAP and NSAP-PTR records were proposed in RFC1706.  A NSAP record is
a hexadecimal number preceeded 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 idenical to a PTR record, but has a 
different RTYPE.

<p>

More information about these records can be obtained from RFC1706.

<p>

If used, here is how the records would look in a csv2 zone file:

<pre>
example.net. NSAP 0x47.0005.80.005a00.0000.0001.e133.ffffff000162.00
example.net. NSAP-PTR nsap.example.net.
</pre>

<h2>PX</h2>

The PX RR is an obscure RR described in RFC2163.  A PX record looks like
this in a CSV2 zone file:

<pre>
example.net. PX 15 px1.example.net. px2.example.net.
</pre>

<h2>GPOS</h2>

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.

<p>

The first chunk of a GPOS record is the longitude; the second chunk is
the latitude; the third chunk is the altitude (in meters).

<p>

Example:

<pre>
example.net. GPOS '-98.6502';'19.283';'2134'
</pre>

More information about this record can be found in RFC1712.

<p>

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.

<h2>LOC</h2>

The LOC recource record is an uncommonly used resource record that 
describes the position of a given server.  LOC records are described
in RFC1876.  

<p>

Note that MaraDNS' 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.

<p>

Example:

<pre>
example.net. LOC 19 31 2.123 N 98 3 4 W 2000m 2m 4m 567m
</pre>

<h1>EXAMPLE ZONE FILE</h1>

<pre>
<include "../examples/example_csv2">
</pre>
<h1>LEGAL DISCLAIMER</h1>
THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' 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. 

<h1>AUTHOR</h1>
Sam Trenholme 
<A href=http://www.samiam.org/>http://www.samiam.org/</a>
</body>

