NAME

csv2 - Description of the csv2 zone file that MaraDNS uses

DESCRIPTION

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.

This zone file format has records in the following form:

name [+ttl] [rtype] rdata
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.

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.

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.

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

A

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:
a.example.net.              10.11.12.13
b.example.net.        A     10.11.12.14
c.example.net. +64000 A     10.11.12.15

PTR

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

MX

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":
example.net.      MX   10 mail.example.net.
mail.example.net.      10.11.12.16

AAAA

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:
a.example.net.   AAAA    3ffe:ffff:ffe:501:ffff::b:c:d

SRV

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:
_http._tcp.% srv 0 0 80 a.%

NS

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:
example.net.    NS    ns1.example.net.
example.net.    NS    ns2.example.net.

SOA

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 not affect other TTLs in MaraDNS. Example:
x.org. SOA x.org. email@x.org. 1 7200 3600 604800 1800

TXT

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.

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

example.com. TXT 'This is an example text field'
Any binary data can be specified; see the csv2_txt(5) manual page for full details.

SPF

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'.

RAW

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:
RAW [numeric rtype] [data] 
The numeric rtype is a decimal number.

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:

example.com. RAW 40 \x10\x01\x02'Kitchen sink'\x40' data'
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 only inside quoted data.

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 csv2_txt(5) manual page.

FQDN4

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:
x.example.net. A 10.2.28.79
79.28.3.10.in-addr.arpa. PTR x.example.net.
But the above two lines in a zone file can also be represented thusly:
x.example.net. FQDN4 10.2.28.79
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.

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.

CNAME

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.

CNAME records are not permitted in a csv2_default_zonefile.

EXAMPLE ZONE FILE

# 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

#% 	SOA	% email@% 1 7200 3600 604800 1800

# Second of all, csv2 zone files do not need authoritative NS records.
# If they aren't there, MaraDNS will synthesize them, based on the IP
# addresses MaraDNS is bound to.  (She's 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
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 '+' 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

# We can even have something similiar 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 	3ffe:ffff:1:2:3::4:f

# Not to mention support for SRV records
_http._tcp.% srv 0 0 80 a.%

# And, of course, TXT records
example.net.    txt 'This is some text'


LEGAL DISCLAIMER

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.

AUTHOR

Sam Trenholme http://www.samiam.org/