Provided by: maradns_2.0.13-1.4build2_amd64 bug


       csv2 - Description of the csv2 zone file that MaraDNS uses


       The csv2 zone file format is MaraDNS' standard zone file format.  This zone file format
       uses any kind of whitespace (space, tab, and carriage return), or the '|' character, to
       delimit fields.

    Tilde delimitation

       In newer MaraDNS releases, the tilde ('~') 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).

       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

    Resource record format

       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 "".  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 the default ttl value (see "Default TTL" below).  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 '{', which is not allowed in comments) until a newline. A '#' can
       usually be placed inside a field, and indicates the end of a field when placed there.

       A '{' character can never be placed in a comment. A '~' character is always allowed in a
       comment, and has no special meaning when placed in a comment.

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


       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 ~ +64000 A ~


       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:        PTR ~        PTR ~ +64000 PTR ~


       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 being mailed to, which has the IP
       "":      MX   10 ~ ~


       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:   AAAA    fd4d:6172:6144:4e53:ffe::f ~


       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.% ~


       A NAPTR record is described in RFC 2915. Example: NAPTR 100 100 's';'http+I2R';'' ~

       Note the semicolons. Because of a bug in MaraDNS 1.4.03 and earlier releases, NAPTR
       records will not parse unless a ~ is not used to separate records; a patch to fix this bug
       is available here.


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


       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: SOA 1 7200 3600 604800 1800 ~

       If there is a '.' (dot) character in the part of the email address before the '@', it
       needs to be escaped thusly: SOA john\ 1 7200 3600 604800 1800 ~

       Note that the csv2 parser will not allow more than one dot in a row; 'john\.\'
       will cause a parse error. In addition, the dot character must be escaped with a backslash.

       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: SOA /serial 7200 3600 604800 1800 ~

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


       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: TXT 'This is an example text field' ~

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

       If tildes are used to separate records, a TXT record can not contain a literal '|' (pipe)
       character, a '#' literal, a '~' 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.


       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: SPF 'v=spf1 +mx -all'

       Use '\x7e' to put a tilde ("~" character) in a SPF record: SPF 'v=spf1 +mx '\x7e'all'

       More information about SPF records can be found in RFC4408, or by performing a web search
       for 'sender policy framework'.


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


       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 A ~ PTR ~

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

       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.


       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: AAAA fd4d:6172:6144:4e53::b:c:d ~
       d.0.0.0.c.0.0.0.b. PTR ~

       But the above two lines in a zone file can also be represented thusly: FQDN6 fd4d:6172:6144:4e53::b:c:d ~

       Like FQDN4 records, it is the DNS administrator's duty to make sure only a single IP has a
       FQDN6 record.

       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.

       FQDN6 records were implemented by Jean-Jacques Sarton.


       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. If you do not know what a
       csv2_default_zonefile is, this fact is of no relevance.

Historical and uncommon resource records

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


       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.

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

       Example: HINFO 'Intel Pentium III';'CentOS Linux 3.7' ~

       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.


       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.

       For example, to advertise that has the IP, and has a SSH, HTTP (web),
       and NNTP server: WKS 6 22,80,119 ~

       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.

    MD and MF

       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.

       Example: MD ~ MF ~

       Is equivalent to: MX 0 ~ MX 10 ~

    MB, MG, MINFO, and MR

       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: MB ~ MG ~ MINFO ~ MR ~

       More information about these records can be found in RFC1035.

    AFSDB, RP, X25, ISDN, and RT

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

       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.

       If used, here is how the records would look in a csv2 zone file: AFSDB 1 ~ RP ~ RP . ~ X25 311061700956 ~ ISDN 150862028003217 ~ ISDN 150862028003217;004 ~ RT 10 ~


       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.

       More information about these records can be obtained from RFC1706.

       If used, here is how the records would look in a csv2 zone file: NSAP 0x47.0005.80.005a00.0000.0001.e133.ffffff000162.00 ~ NSAP-PTR ~


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


       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

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

       Example: GPOS '-98.6502';'19.283';'2134' ~

       More information about this record can be found in RFC1712.

       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.


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

       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.

       Example: LOC 19 31 2.123 N 98 3 4 W 2000m 2m 4m 567m ~


       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 '/serial'
       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-

       These commands are as follows:

    Default TTL

       The default TTL is the TTL for a resource record without a TTL specified.  This can be
       changed with the '/ttl' slash command. This command takes only a single argument: The
       time, in seconds, for the new default TTL.  The '/ttl' slash command only affects the TTL
       of records that follow the command. A zone file can have multiple '/ttl' slash commands.

       The default TTL is 86400 seconds (one day) until changed by the '/ttl' slash command.

       In the following example, will have a TTL of 86400 seconds (as long as
       the zone file with this record has not previously used the '/ttl' slash command), and will have a TTL of 3600 seconds,
       will have a TTL of 9600 seconds, and will have a TTL of 7200 seconds: ~
       /ttl 3600 ~ ~ +9600 ~ ~
       /ttl 7200 ~ ~


       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 '/origin', taking the new origin as the one argument to
       this function.  Note that changing the origin does not change the domain suffix used to
       determine whether a given domain name is authoritative.

       Here is one example usage of the '/origin' slash command:

       /origin ~
       www.% ~
       % MX 10 mail.% ~
       mail.% ~
       /origin ~
       www.% ~
       % MX 10 mail.% ~
       mail.% ~

       Which is equivalent to: ~ MX 10 ~ ~ ~ MX 10 ~ ~

       It is also possible to make the current origin be part of the new origin:

       /origin ~
       % ~ # now has IP
       /origin mail.% ~
       % ~ # now has IP

    Opush and Opop

       The '/opush' and '/opop' slash commands use a stack to remember and later recall values
       for the origin (see origin above). The '/opush' command is used just like the '/origin'
       command; however, the current origin is placed on a stack instead of discarded. The
       '/opop' command removes ("pops") the top element from this stack and makes the element the

       For example:

       /origin ~
       /opush mail.% ~ # origin is now; is on stack
       a.% ~ # has IP
       /opush ~ # and are on stack
       a.% ~ # has IP
       b.% ~ # has IP
       /opop ~ # origin is now again
       b.% ~ # has IP
       /opop ~ # origin is now
       % MX 10 a.mail.% ~ # MX 10
       % MX 20 b.mail.% ~ # MX 20

       The opush/opop stack can have up to seven elements on it.


       The '/read' slash commands allows one to have the contents of another file in a zone. The
       '/read' command takes a single argument: A filename that one wishes to read. The filename
       is only allowed to have letters, numbers, the '-' character, the '_' character, and the
       '.' character in it.

       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.

       Let us suppose that we have the following in a zone file: ~
       /read foo ~ MX 10 ~

       And a file foo with the following contents: ~ TXT 'Foomatic!' ~

       Then will have an A record with the value, a TXT value of
       'Foomatic!', and a MX record with priority 10 pointing to will have the IP

       Note that no pre-processing nor post-processing of the origin is done by the '/read'
       command; should the file read change the origin, this changed value will affect any
       records after the '/read' command.  For example, let us suppose looks like

       /origin ~
       % TXT 'Foomatic!' ~
       /read foo ~
       % MX 10 ~

       And the file foo looks like this:

       % ~
       /origin mail.% ~
       % ~

       Then the following records will be created:      TXT   'Foomatic!' ~      A ~ A ~ MX 10 ~

       To have something that works like '$INCLUDE filename' in a RFC1035 master file, do the

       /opush % ~
       /read filename ~
       /opop ~

       Or, for that matter, the equivalent of '$INCLUDE filename neworigin':

       /opush neworigin. ~
       /read filename ~
       /opop ~


       # 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'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. ~
       # Here, you can see that a single name, "" 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 "" is made ~ ~

       # We can have the label in either case; it makes no difference
       Z.EXAMPLE.NET. ~ ~

       # 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 ~

       # And we can have star records
       #*  A ~

       # 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 +86400 A ~ # As you can see, records can span multiple lines
                 A ~

       # This allows well-commented records, like this:           # Our C class machine
               +86400      # This record is stored for one day
               A           # A record
         # Where we are
               ~               # End of record

       # We can even have something similar to csv1 if we want...|+86400|a||~|a||~
       # Here, we see we can specify the ttl but not the rtype if desired|+86400||~

       # Here is a MX record
       % mx 10 mail.% ~
       mail.% +86400 IN A ~

       # We even have a bit of ipv6 support           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    txt 'This is some text' ~

       # Starting with MaraDNS 1.2.08, there is also support for SPF records,
       # which are identical to TXT records.  See RFC4408 for more details.    spf 'v=spf1 +mx -all' ~




       Sam Trenholme