A DNS zone file looks deceptively simple — five columns of text — but the parser rules accumulated over forty years of DNS history are unforgiving in surprising ways. This article is the reference for the format: directives, the implicit owner-field inheritance, TTL precedence, SOA timer semantics, CNAME constraints, escape rules. The deliverable is the knowledge to read, write, and debug a zone file without surprises.
How to verify
Before you change anything, parse what you have. named-checkzone (from BIND) is the standard validator and it is strict — closer to the RFC than the lenient parsers most authoritative servers ship:
named-checkzone example.com /etc/bind/zones/db.example.com
named-checkzone -i full -k fail -n fail example.com /etc/bind/zones/db.example.com
kdig @ns1.example.com example.com SOA +short
dig @ns1.example.com example.com AXFR | tail
The strict flags catch CNAME-at-apex, mismatched glue, and weird TTL ordering. If named-checkzone is happy, most other tools will be too.
What’s happening
A DNS zone file describes one zone — a contiguous chunk of the DNS tree under a single administrative authority. The file format (RFC 1035 §5) is a sequence of resource records, one per line, plus directives that affect how subsequent records are parsed.
A line has up to five columns:
<owner> <ttl> <class> <type> <rdata...>
Three of the five are optional with inheritance rules:
- Owner. If omitted (line starts with whitespace), it inherits the previous owner.
- TTL. If omitted, uses the
$TTLdirective at top of file (RFC 2308 — required since 1998). If$TTLis also missing, uses the SOA minimum (deprecated and inconsistent across parsers). - Class. Always
INin modern internet DNS. Omitting it is fine.
Directives start with $:
$ORIGIN example.com.— base name appended to unqualified owners.$TTL 3600— default TTL for subsequent records.$INCLUDE file— pull in another file’s records (good for splitting big zones).$GENERATE— generate a series of similar records (PTR ranges, for example).
The @ symbol means “the current $ORIGIN.” A trailing dot on a name makes it absolute; without a trailing dot, the current $ORIGIN is appended. This last rule is the source of most zone-file bugs.
The procedure
-
Always set
$TTLand$ORIGIN. Two lines at the top, before any record:$TTL 3600 $ORIGIN example.com.Make
$ORIGINabsolute (trailing dot). Make$TTLexplicit so parsers do not fall back to SOA minimum. -
Write the SOA correctly. This is the only record where the timers matter operationally:
@ IN SOA ns1.example.com. hostmaster.example.com. ( 2026060201 ; serial YYYYMMDDnn convention 3600 ; refresh how often secondaries check primary 600 ; retry how often after a failed check 1209600 ; expire how long secondaries serve if primary is gone 300 ; minimum negative-response TTL )The five fields after the email address are the timers.
expirematters most — if your primary is down longer than this, secondaries stop serving the zone and clients get SERVFAIL. Set it long (1-2 weeks is standard). -
NS records at the apex. Every zone needs at least one NS at the zone apex. List all your authoritative servers:
@ IN NS ns1.example.com. @ IN NS ns2.example.com. ns1 IN A 203.0.113.10 ; glue — required because ns1 is in this zone ns2 IN A 203.0.113.20The A records for the in-zone NS hostnames are “glue” — they break the chicken-and-egg problem of needing to resolve
ns1.example.comto find the server that holdsexample.com. -
A and AAAA records. Same syntax, different type:
www IN A 203.0.113.50 www IN AAAA 2001:db8::50wwwis unqualified — the current$ORIGINis appended, producingwww.example.com.. Multiple A records for the same owner are valid and produce round-robin DNS. -
CNAME — and what it forbids. A CNAME aliases a name to another name:
blog IN CNAME pages.cdn.example.net.The trailing dot on the target is critical — without it, the CNAME points at
pages.cdn.example.net.example.com.which is almost never what you want.The constraint: a name with a CNAME cannot have any other records. No A, no MX, no TXT, no nothing. Putting a CNAME at the zone apex (
@) is invalid because the apex has SOA and NS. Use ALIAS/ANAME (vendor-specific) or just put the A record directly. -
MX and SPF. Mail records are routine but the priority field is easy to forget:
@ IN MX 10 mail.example.com. @ IN MX 20 backup-mx.example.net. @ IN TXT "v=spf1 mx -all"Lower priority wins. Two MXs with the same priority spread load.
-
TXT records and escaping. Long TXT values (DKIM keys, SPF chains) often exceed the 255-byte single-string limit. The format allows multiple strings per RDATA:
default._domainkey IN TXT ( "v=DKIM1; k=rsa; " "p=MIIBIjANBgkqhkiG9w0BAQEFA..." "...IDAQAB" )Many resolvers concatenate them; some do not. Test by re-querying the published value.
-
$GENERATEfor PTR ranges. Reverse zones for /24s benefit:$ORIGIN 113.0.203.in-addr.arpa. $GENERATE 10-50 $ PTR host-$.example.com.Produces
10 PTR host-10.example.com.through50 PTR host-50.example.com.. Saves typing forty almost-identical lines.
Common pitfalls
- Forgetting the trailing dot.
www IN CNAME pages.cdn.example.net(no trailing dot) — the parser appends$ORIGIN, you getpages.cdn.example.net.example.com.. Runnamed-checkzone— it warns. - CNAME at apex. Discussed above. Many DNS providers offer “ALIAS” or “ANAME” as a vendor extension to fake it; understand that those are not real DNS records and are flattened to A/AAAA at query time.
- Wrong SOA email format. The hostmaster email is
hostmaster.example.com.nothostmaster@example.com. The first dot is the@substitution. If the local-part needs a literal dot, escape it:john\.doe.example.com.. - TTL too low. Setting TTL to 60 seconds for everything looks operationally flexible, but it costs cache misses and resolver load. Use 300-3600 for normal records; only drop to 60 for records actively being changed.
- Stale
$ORIGINafter$INCLUDE.$INCLUDEdoes not reset$ORIGINto the parent file’s value when it returns. Set$ORIGINexplicitly at the top of each included file. - CR/LF line endings. Most parsers cope but some get confused. Save zone files as UTF-8 LF only, no BOM.
In the engagements we run, the zone file is rarely hand-edited any more — it is the output of a templating layer (Ansible, Terraform DNS provider, a CMDB → zone-file pipeline). The format itself is still worth understanding because every audit, debug session, and migration eventually requires reading a flat file. We codify the templates, version them, and validate with named-checkzone before any reload. See our managed operations service for the broader operating model.