Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CSV2(5)			       MaraDNS reference		       CSV2(5)

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

    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

       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


       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

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


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

       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


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

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

       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

       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

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

       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

       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

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

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

MARADNS				 January 2007			       CSV2(5)


Want to link to this manual page? Use this URL:

home | help