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.
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 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:
a.example.net. 10.11.12.13 ~ b.example.net. A 10.11.12.14 ~ c.example.net. +64000 A 10.11.12.15 ~
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. ~
example.net. MX 10 mail.example.net. ~ mail.example.net. 10.11.12.16 ~
a.example.net. AAAA 2001:db8:dec:ade::f ~
_http._tcp.% SRV 0 0 80 a.% ~
www.example.com. NAPTR 100 100 's';'http+I2R';'' _http._tcp.example.com. ~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.
example.net. NS ns1.example.net. ~ example.net. NS ns2.example.net. ~
x.org. SOA x.org. email@x.org. 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:
x.org. SOA x.org. john\.doe@x.org. 1 7200 3600 604800 1800 ~Note that the csv2 parser will not allow more than one dot in a row; 'john\.\.doe@x.org' 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:
x.org. SOA x.org. email@x.org. /serial 7200 3600 604800 1800 ~The '/serial' string is case-sensitive; only '/serial' in all lower case will parse.
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.
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.
Here is one example SPF record:
example.com. SPF 'v=spf1 +mx a:colo.example.com/28 -all' ~Use '\x7e' to put a tilde ("~" character) in a SPF record:
example.com. SPF 'v=spf1 +mx a:colo.example.com/28 '\x7e'all' ~More information about SPF records can be found in RFC4408, or by performing a web search for 'sender policy framework'.
Note that SPF records never gained traction, and their role is handled by TXT records.
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.
x.example.net. A 10.3.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.3.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.
x.example.net. AAAA 2001:db8:dec:ade::b:c:d ~ d.0.0.0.c.0.0.0.b.0.0.0.0.0.0.0.e.d.a.0.c.e.d.0.8.b.d.0.1.0.0.2 PTR x.example.net. ~But the above two lines in a zone file can also be represented thusly:
x.example.net. FQDN6 2001:db8:dec:ade::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.
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.
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:
example.com. 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.
For example, to advertise that example.net has the IP 10.1.2.3, and has a SSH, HTTP (web), and NNTP server:
example.net. WKS 10.1.2.3 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.
Example:
example.net. MD a.example.net. ~ example.net. MF b.example.net. ~Is equivalent to:
example.net. MX 0 a.example.net. ~ example.net. MX 10 b.example.net. ~
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. ~More information about these records can be found in RFC1035.
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:
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. ~
More information about these records can be obtained from RFC1706.
If used, here is how the records would look in a csv2 zone file:
example.net. NSAP 0x47.0005.80.005a00.0000.0001.e133.ffffff000162.00 ~ example.net. NSAP-PTR nsap.example.net. ~
example.net. PX 15 px1.example.net. px2.example.net. ~
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:
example.net. 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.
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:
example.net. LOC 19 31 2.123 N 98 3 4 W 2000m 2m 4m 567m ~
example.com. RAW 257 \x00\x05'issueletsencrypt.org' ~
*.example.net. A 10.11.12.13 ~In this example, anything.example.net will have the IP 10.11.12.13. Note that this does not set the ip for "example.net", which needs a separate record:
example.net. A 10.11.12.13 ~Note also that stars must be at the beginining of a name; to have stars at the end of a name, use the csv2_default_zonefile feature as described in the mararc man page.
For example, in the zone for example.net. (e.g. one's mararc file has csv2["example.net."] = "db.example.net", and we are editing the "db.example.net" file):
www.% A 10.10.10.10 ~This will cause "www.example.net" to have the ip 10.10.10.10.
These commands are as follows:
The default TTL is 86400 seconds (one day) until changed by the '/ttl' slash command.
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 '/ttl' 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:
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 ~
Here is one example usage of the '/origin' slash command:
/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 ~Which is equivalent to:
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 ~It is also possible to make the current origin be part of the new origin:
/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
For example:
/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.The opush/opop stack can have up to seven elements on 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:
mail.foo.example.com. 10.3.2.1 ~ /read foo ~ foo.example.com. MX 10 mail.foo.example.com. ~And a file foo with the following contents:
foo.example.com. 10.1.2.3 ~ foo.example.com. TXT 'Foomatic!' ~Then foo.example.com will have an A record with the value 10.1.2.3, a TXT value of 'Foomatic!', 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.
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 db.example.com looks like this:
/origin foo.example.com. ~ % TXT 'Foomatic!' ~ /read foo ~ % MX 10 mail.foo.example.com. ~And the file foo looks like this:
% 10.1.2.3 ~ /origin mail.% ~ % 10.3.2.1 ~Then the following records will be created:
foo.example.com. TXT 'Foomatic!' ~ 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. ~To have something that works like '$INCLUDE filename' in a RFC1035 master file, do the following:
/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.
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 '+' 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
# Note that "IN" is a pseudo-RR which means to ignore the RR type and
# look at the next RR type in the zone file; this allows MaraDNS zone
# files to look more like BIND zone files.
% mx 10 mail.% ~
mail.% +86400 IN A 10.22.23.24 ~
# We even have a bit of ipv6 support
a.example.net. aaaa 2001:db8:1:2::3:f ~
# Not to mention support for SRV records
_http._tcp.% srv 0 0 80 a.% ~
# TXT records, naturally
example.net. 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.
example.net. spf 'v=spf1 +mx a:colo.example.com/28 -all' ~