Skip to main content

5. Master Files

Master files are text files that contain RRs in text form. Since the contents of a zone can be expressed in the form of a list of RRs, a master file is most often used to define a zone, though it can be used to list a cache's contents.

This section first discusses the format of RRs in a master file, and then the special considerations when a master file is used to create a zone in some name server.

5.1. Format​

The format of master files is a sequence of entries.

General Rules​

Line-Oriented Format:

  • Entries are predominantly line-oriented
  • Parentheses can be used to continue a list of items across a line boundary
  • Text literals can contain CRLF within the text

Delimiters:

  • Any combination of tabs and spaces act as a delimiter between separate items

Comments:

  • The end of any line can end with a comment
  • Comments start with a ; (semicolon)
  • The remainder of the line after ; is ignored

Blank Lines:

  • Blank lines, with or without comments, are allowed anywhere in the file

Entry Types​

The following entries are defined:

<blank>[<comment>]

$ORIGIN `<domain-name>` [<comment>]

$INCLUDE `<file-name>` [`<domain-name>`] [<comment>]

`<domain-name>`<rr> [<comment>]

<blank><rr> [<comment>]

Control Entries​

Two control entries are defined: $ORIGIN and $INCLUDE.

$ORIGIN:

  • Followed by a domain name
  • Resets the current origin for relative domain names to the stated name
  • Example: $ORIGIN example.com.

$INCLUDE:

  • Inserts the named file into the current file
  • May optionally specify a domain name that sets the relative domain name origin for the included file
  • May also have a comment
  • Note: A $INCLUDE entry never changes the relative origin of the parent file, regardless of changes to the relative origin made within the included file
  • Example: $INCLUDE /var/named/example.com.hosts

Resource Record Entries​

The last two entry forms represent RRs:

Owner Name Rules:

  • If an entry for an RR begins with a blank, then the RR is assumed to be owned by the last stated owner
  • If an RR entry begins with a <domain-name>, then the owner name is reset

RR Format:

<rr> contents take one of the following forms:

[<TTL>] [<class>] <type> <RDATA>

[<class>] [<TTL>] <type> <RDATA>

Field Descriptions:

  • TTL: Optional, decimal integer representing time to live in seconds
  • Class: Optional, standard mnemonic (e.g., IN)
  • Type: Required, standard mnemonic (e.g., A, NS, MX)
  • RDATA: Required, data appropriate to the type and class

Defaults:

  • Omitted class and TTL values default to the last explicitly stated values
  • Since type and class mnemonics are disjoint, the parse is unique

Note: This order is different from the order used in examples and the order used in the actual RRs; the given order allows easier parsing and defaulting.

5.2. Domain Names in Master Files​

<domain-name>s make up a large share of the data in the master file.

Label Representation​

Basic Format:

  • Labels in the domain name are expressed as character strings and separated by dots
  • Quoting conventions allow arbitrary characters to be stored in domain names

Absolute vs. Relative Names:

  • Absolute Names: Domain names that end in a dot are called absolute, and are taken as complete

    • Example: www.example.com.

  • Relative Names: Domain names which do not end in a dot are called relative

    • The actual domain name is the concatenation of the relative part with an origin specified in a $ORIGIN, $INCLUDE, or as an argument to the master file loading routine
    • A relative name is an error when no origin is available
    • Example: www with origin example.com. becomes www.example.com.

Character Strings​

<character-string> is expressed in one or two ways:

  1. Unquoted: A contiguous set of characters without interior spaces
  2. Quoted: A string beginning with " and ending with "
    • Inside a " delimited string, any character can occur except for a " itself
    • A " must be quoted using \ (backslash)

5.3. Special Encodings​

Because master files are text files, several special encodings are necessary to allow arbitrary data to be loaded.

Special Characters and Sequences​

. (dot):

  • A free standing . denotes the root
  • Example: In example.com., the trailing . denotes the root

@ (at sign):

  • A free standing @ is used to denote the current origin
  • Example: @ IN SOA ... refers to the zone's origin

\X (backslash escape):

  • Where X is any character other than a digit (0-9)
  • Used to quote that character so that its special meaning does not apply
  • Examples:
    • \. can be used to place a dot character in a label
    • \; can be used to include a semicolon in a string (not as a comment)
    • \\ represents a backslash character

\DDD (decimal escape):

  • Where each D is a digit
  • Represents the octet corresponding to the decimal number described by DDD
  • The resulting octet is assumed to be text and is not checked for special meaning
  • Example: \065 represents the character 'A' (ASCII 65)

( ) (parentheses):

  • Parentheses are used to group data that crosses a line boundary
  • In effect, line terminations are not recognized within parentheses
  • Useful for SOA records and other multi-line entries

; (semicolon):

  • Semicolon is used to start a comment
  • The remainder of the line is ignored

5.4. Use of Master Files to Define Zones​

When a master file is used to load a zone, the operation should be suppressed if any errors are encountered in the master file.

Rationale​

The rationale for this is that a single error can have widespread consequences. For example:

  • Suppose that the RRs defining a delegation have syntax errors
  • Then the server will return authoritative name errors for all names in the subzone
  • (except in the case where the subzone is also present on the server)

Validity Checks​

Several validity checks should be performed in addition to ensuring that the file is syntactically correct:

  1. Class Consistency: All RRs in the file should have the same class

  2. SOA Requirement: Exactly one SOA RR should be present at the top of the zone

  3. Glue Information: If delegations are present and glue information is required, it should be present

  4. Authoritative Data: Information present outside of the authoritative nodes in the zone should be glue information, rather than the result of an origin or similar error

5.5. Master File Example​

The following is an example file which might be used to define the ISI.EDU zone and is loaded with an origin of ISI.EDU:

@   IN  SOA     VENERA      Action\.domains (
                                 20     ; SERIAL
                                 7200   ; REFRESH
                                 600    ; RETRY
                                 3600000; EXPIRE
                                 60)    ; MINIMUM

        NS      A.ISI.EDU.
        NS      VENERA
        NS      VAXA
        MX      10      VENERA
        MX      20      VAXA

A       A       26.3.0.103

VENERA  A       10.1.0.52
        A       128.9.0.32

VAXA    A       10.2.0.27
        A       128.9.0.33


$INCLUDE <SUBSYS>ISI-MAILBOXES.TXT

Example Analysis​

SOA Record:

  • @ represents the zone origin (ISI.EDU.)
  • VENERA is the primary name server (relative name, becomes VENERA.ISI.EDU.)
  • Action\.domains is the responsible person's mailbox ([email protected])
    • Note the use of \ to escape the dot in the email address
  • Serial number: 20
  • Refresh: 7200 seconds (2 hours)
  • Retry: 600 seconds (10 minutes)
  • Expire: 3600000 seconds (approximately 41.67 days)
  • Minimum: 60 seconds

NS Records:

  • Three name servers: A.ISI.EDU. (absolute), VENERA (relative), VAXA (relative)

MX Records:

  • Primary mail exchanger: VENERA with preference 10
  • Secondary mail exchanger: VAXA with preference 20

A Records:

  • A.ISI.EDU. has one IPv4 address
  • VENERA.ISI.EDU. has two IPv4 addresses (multihomed)
  • VAXA.ISI.EDU. has two IPv4 addresses (multihomed)

$INCLUDE Directive:

  • Includes an external file containing mailbox records

Included File Example​

Where the file <SUBSYS>ISI-MAILBOXES.TXT contains:

    MOE     MB      A.ISI.EDU.
    LARRY   MB      A.ISI.EDU.
    CURLEY  MB      A.ISI.EDU.
    STOOGES MG      MOE
            MG      LARRY
            MG      CURLEY

Explanation:

  • MB records define individual mailboxes
  • MG records define a mail group
  • The STOOGES mail group includes three members
  • Blank lines indicate continuation of the previous owner name

5.6. Common Master File Patterns​

Pattern 1: Simple Zone File​

$ORIGIN example.com.
$TTL 86400

@   IN  SOA ns1.example.com. admin.example.com. (
            2024010101  ; Serial
            3600        ; Refresh
            1800        ; Retry
            604800      ; Expire
            86400 )     ; Minimum

    IN  NS  ns1.example.com.
    IN  NS  ns2.example.com.

ns1 IN  A   192.0.2.1
ns2 IN  A   192.0.2.2
www IN  A   192.0.2.10

Pattern 2: Delegated Subdomain​

; Delegation to subdomain
subdomain       IN  NS  ns1.subdomain.example.com.
                IN  NS  ns2.subdomain.example.com.

; Glue records (required if name servers are in subdomain)
ns1.subdomain   IN  A   192.0.2.20
ns2.subdomain   IN  A   192.0.2.21

Pattern 3: Multiple A Records (Load Balancing)​

; Round-robin DNS for load balancing
www     IN  A   192.0.2.10
        IN  A   192.0.2.11
        IN  A   192.0.2.12

5.7. Best Practices​

  1. Always Use Absolute Names for External References: Names outside your zone should end with a dot

  2. Use $ORIGIN Carefully: Set it at the beginning and avoid changing it unnecessarily

  3. Include Serial Numbers: Always increment the serial number when making changes

  4. Use Comments: Document your zone file with comments

  5. Test Before Deploying: Use tools like named-checkzone to validate syntax

  6. Maintain Consistency: Keep consistent formatting for readability

  7. Backup: Always maintain backups of working zone files before making changes

Next: 6. Name Server Implementation

Last updated on