CSV1(5)

💖 CSV1(5) — the csv1 zone file format, explained by your fave ✨

okay bestie, this is the man page for csv1 — the format of the csv1 zone file that MaraDNS uses. it's giving "vintage but still serving" 🎀. it's from the MaraDNS reference set, manual page number 5 (the file-formats girlies 🫶), and we're gonna go through every single line together. no skimming, no gatekeeping, periodt.

---

🌸 SPECIAL NOTE 🌸

the csv1 zone file format is supported primarily for MaraDNS users who already have zone files in the csv1 format. that's the whole point, bestie — it's the legacy-comfort format.

MaraDNS now supports a csv2 zone file format. and listen: note that the csv1 zone file format will continue to function as long as I am MaraDNS' maintainer. that's a promise, not a vibe. 🫡

---

✨ SPECIAL CHARACTERS ✨

these lil guys have powers, iykyk:

• | — this delimits fields. it's the divider, the fence between your stuff 💅
• # — this signifies a comment. lines starting with this are ignored, otherwise it has no significance.
• % — this, in domain names, signifies that the rest of the domain name should be the name of this zone.
• * — this is translated to mean "any host name that otherwise does not resolve". it must be at the beginning of a domain name. no cap.
• \ — this is used as an escape character, either to escape octal values such as '\045' for %, or to escape the '%' character so it has no special meaning, or to escape the backslash character.

---

🧚 NOTES ON PROCESSING 🧚

all domain-name labels are converted to their lower-case equivalents before processing is done. why? because domain-name literals in the database with one or more upper-case letters in them are case-sensitive. this is the author's way to resolve RFC1035's desire to both allow binary domain labels and be case-insensitive. iconic problem-solving honestly 🌈

the file must first have a SOA record, followed by one or more NS records, followed by other records. the initial NS and SOA records must be RR for this zone. NS records after any non-NS record must be part of another zone. the resolution algorithm will not break if non-CNAME records share records with a CNAME record, but this is not a good idea to do. don't do it bestie, I'm begging 🙈

---

💅 RR FORMAT 💅

a domain name is a one-letter designation of its type, followed by the domain name separated by dots, ending with either a % or a trailing dot.

if the domain name does not end with a % or trailing dot, an error is returned. so like… don't forget your ending, okay? 😭

---

👑 SUPPORTED RR TYPES 👑

MaraDNS only supports the following types of resource records (RRs) in csv1 files. more resource records types are supported in csv2 zone files; see csv2(5) for details.

• A — type A — RFC1035 section 3.2.2 value 1
• N — type NS — RFC1035 section 3.2.2 value 2
• C — type CNAME — RFC1035 section 3.2.2 value 5
• S — type SOA — RFC1035 section 3.2.2 value 6
• P — type PTR — RFC1035 section 3.2.2 value 12
• @ — type MX — RFC1035 section 3.2.2 value 15
• T — type TXT — RFC1035 section 3.2.2 value 16
• U — type any — determined in third field of line

---

🦋 FORMAT OF SUPPORTED RR TYPES 🦋

here are the formats, shown by letter name. this is the main character section, let's get into it:

A — has three fields

• field one: the domain name
• field two: the ttl for the name in seconds
• field three: the ip address, in dotted decimal notation

example:

Ahost.example.com.|7200|10.1.2.3

A records are described with grueling detail in RFC1035. in short, an A record is an IP address for a given host name. simple as that, slay 💅

N — has three fields

• field one: the domain name of the record
• field two: the ttl for the name in seconds
• field three: the domain name this NS points to.

example:

Nexample.com.|86400|ns.example.com.

NS (N here) records are described in RFC1035.

C — has three fields

• field one: the domain name of the record
• field two: the ttl for the name in seconds
• field three: the domain this CNAME record points to

example:

Calias.example.org.|3200|realname.example.org.

CNAME (which C is short for) records are described in RFC1035.

S — has nine fields

• field one: the domain name of the record
• field two: the TTL of the record
• field three: the origin of the domain. in other words, the name of the primary name server for the domain.
• field four: the email address for this domain (in the RFC822, not BIND format)
• field five: the serial for the domain
• field six: the refresh (how often to see updates) for the domain
• field seven: the retry (how often to try when down) for the domain
• field eight: the expire (how long before the slave gives up) for the domain
• field nine: the minimum (and default) TTL for the domain

example:

Sexample.net.|86400|%|hostmaster@%|19771108|7200|3600|604800|1800

SOA (S here) records are described in RFC1035. nine fields bestie, she's a lot but she's worth it 🌸

P — has three fields

• field one: the IP we wish to point to (in in-addr.arpa form)
• field two: the ttl for the name in seconds
• field three: the FQDN for the IP in question

example:

P3.2.1.10.in-addr.arpa.|86400|ns.example.com.

PTR (P here) records, which are used for reverse DNS lookups, are described in RFC1035. note that one needs control of the appropriate in-addr.arpa subdomain to make PTR records visible on the internet at large. so like, you need the keys to the house, not just the address 🔑

@ — has four fields

• field one: The host that people send email to
• field two: the ttl for this record
• field three: The preference for this MX host
• field four: The name of this MX host

example:

@example.com.|86400|10|mail.example.com.

MX (@ here) records are described in RFC1035.

T — has three fields

• field one: The host someone wants to get additional information about
• field two: the ttl for this record
• field three: The desired text. any data becomes the record up until a new line is reached. the new line is not part of the TXT record

example:

Texample.com.|86400|Example.com: Buy example products online

TXT (T here) records are described in RFC1035.

U — has four fields

• field one: The host someone wants a data type normally unsupported by MaraDNS for
• field two: the ttl for this record
• field three: The numeric code for this data type (33 for SRV, etc.)
• field four: The raw binary data for this data type

example:

Uexample.com.|3600|40|\010\001\002Kitchen sink data

the above example is a "Kitchen Sink" RR (see draft-ietf-dnsind-kitchen-sink-02.txt) with a "meaning" of 8, a "coding" of 1, a "subcoding" of 2, and a data string of "Kitchen sink data". since this particular data type is not formalized in a RFC at this time, the most appropriate method of storing this data is by using the catch-all "unsupported" syntax. the catch-all ate and left no crumbs 🍓

---

🎀 EXAMPLE CSV1 ZONE FILE 🎀

look at her. a full zone file. gorgeous.

# Example CSV1 zone file

# This is what is known as a SOA record.  All zone files need to have one
# of these
S%|86400|%|hostmaster@%|19771108|7200|3600|604800|1800
# These are known as authoritative NS records.  All zone files need one or
# more of these
N%|86400|ns1.%
N%|86400|ns2.%

# Some IP addresses
Ans1.%|86400|10.0.0.1
Ans2.%|86400|192.168.0.1
A%|86400|10.1.2.3
Amx.%|86400|10.1.2.4

# An 'IN MX' record
@%|86400|10|mx.%

---

💀 LEGAL DISCLAIMER 💀

okay bestie, this part is the serious one. I'm not gonna clown around with the legal text, so here it is exactly as it is, all caps and all. read it, don't skip it, it's important 🙏

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/

---

and that's the whole page bestie, you made it to the end 🫶 this was the MARADNS reference for CSV1(5), dated January 2002 — yeah she's an elder but she's still iconic, and the csv1 format keeps working as long as the maintainer's holding it down. go write some zone files, you've got this 💖✨