Skip to content

Authoring DNS zone files — a deep dive

The DNS zone file format from $ORIGIN to RFC 1035 escaping — owner fields, TTL inheritance, SOA timers, CNAME constraints, and the parser quirks that bite in production.

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 $TTL directive at top of file (RFC 2308 — required since 1998). If $TTL is also missing, uses the SOA minimum (deprecated and inconsistent across parsers).
  • Class. Always IN in 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

  1. Always set $TTL and $ORIGIN. Two lines at the top, before any record:

    $TTL 3600
    $ORIGIN example.com.

    Make $ORIGIN absolute (trailing dot). Make $TTL explicit so parsers do not fall back to SOA minimum.

  2. 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. expire matters 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).

  3. 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.20

    The A records for the in-zone NS hostnames are “glue” — they break the chicken-and-egg problem of needing to resolve ns1.example.com to find the server that holds example.com.

  4. A and AAAA records. Same syntax, different type:

    www     IN  A     203.0.113.50
    www     IN  AAAA  2001:db8::50

    www is unqualified — the current $ORIGIN is appended, producing www.example.com.. Multiple A records for the same owner are valid and produce round-robin DNS.

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

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

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

  8. $GENERATE for 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. through 50 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 get pages.cdn.example.net.example.com.. Run named-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. not hostmaster@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 $ORIGIN after $INCLUDE. $INCLUDE does not reset $ORIGIN to the parent file’s value when it returns. Set $ORIGIN explicitly 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.