H Format of DNS Data File Entries

The Domain Name Service (DNS) configuration file, by default called /etc/namedb/named.conf, specifies the names of the DNS data files. These data files consist of entries, also known as Resource Records (RR), that follow the formats described in this chapter.

H.1 Format of DNS Resource Records

Here is the general format of a DNS Resource Record:

name ttl addr-class entry-type entry-specific-data

The fields are defined as follows:

Field	Description
`name`	This is the name of the domain, for example `cities.dec.com`. The domain name must begin in the first column. For some data file entries the name field is left blank. In that case, the domain name is assumed to be the same as the previous entry. A free standing period (.) refers to the current domain. A free standing at sign (`@`) denotes the current origin, thus allowing you to specify more than one domain. Two free standing periods (`..`) represent the null domain name of the root.
`ttl`	This is the time-to-live field, and specifies how long, in seconds, the data will be stored in the database. If this field is left blank, the value defaults to the ttl specified in the SOA (start of authority) entry. The maximum time-to-live is 99999999 seconds, or 3 years.
`addr-class`	This field is the address class. There are three classes: IN -- Internet addresses, TXT -- naming service data, ANY -- all other types of network addresses. The address class of all data file entries of a given entry-type in a particular zone must be the same. Therefore, only the first entry in a zone need specify the `addr-class` field.
`entry-type`	This field states the resource record type, for example SOA or A.
`entry-specific-data`	All fields after the entry-type field vary for each type of date file entry (resource record).

The case is preserved in name and data fields when loaded into the DNS server. Comparisons and lookups using the DNS are case insensitive.

The following characters have special meanings in DNS data file entries:

Character	Meaning
\x	A backslash (\) escapes the next nondigit (`x`) character so that the character's special meaning does not apply. For example, you could use a period (.) to place a period character in a label.
\nnn	A backslash denotes the octet corresponding to the decimal number represented by nnn. The resulting octet is assumed to be text and is not checked for special meaning.
()	Parentheses group data that cross a line. In effect, line terminations are not recognized within parentheses.
;	A semicolon starts a comment, causing the rest of the line to be ignored.
*	An asterisk signifies a wildcard.

Most DNS data file entries have the current domain appended to their names if they are not terminated by a period (.). This is useful for appending the current domain name to the data, such as system names, but could cause problems when you do not want this to happen. Consequently, if the name is not in the domain for which you are creating the data file, end the name with a period.

Data files (resource records) can have the following types of entries:

$include

$origin

A -- address

CNAME -- canonical name

HINFO -- host information

MB -- mail box

MG -- mail group

MINFO -- mailbox information

MR -- mail rename

MX -- mail exchanger

NS -- name server

PTR -- domain name pointer

SOA -- start of authority

WKS -- well known services

H.2 Description of Data File Entries

The following sections describe each data file entry and its format.

H.2.1 Include Entry

An include entry is similar to a header file in the C programming language. This feature is particularly useful for separating different types of data into multiple files. An include entry begins with $include in the first column, and is followed by the name of the file to be included. For example:

$include /etc/namedb/mailboxes

This entry requests the DNS to load the data file /etc/namedb/mailboxes.

The $include entry loads data files into the local zone and acts as a data file organizer. For example, you can use $include entries to separate mail from host information.

H.2.2 Origin Entry

An origin entry changes the origin in a data file. This feature is particularly useful for putting more than one domain in a data file. An origin entry begins with $origin in the first column, followed by a domain origin. For example:

$origin state.dec.com.

This entry includes the domain state.dec.com in the data file. As a result, the DNS can provide information about the state.dec.com domain in addition to the local domain, provided your server is authoritative for the zone.

The $origin and $include entries can work together. They can save typing and help keep the files organized. For example, assume that the following entries are in the hosts.rev file:

$origin ll.128.in-addr.arpa.
$include cities.dec.com.rev

The period after arpa signifies the complete domain name. Assume that the cities.dec.com.rev file consists of entries similar to the following:

33.22 IN PTR chicago.cities.dec.com.

In this situation, the complete reverse name for the host chicago is translated to be as follows:

33.22.11.128. in-addr.arpa. IN PTR chicago.cities.dec.com.

H.2.3 Address Entry

The address (A) data file entry lists the address for a specific system. An A entry has the following format:

name ttl addr-class entry-type address

The fields in the A entry have the values described in Section H.1, with the exception of the address field. This field specifies the IP address for each system. There should be only one A entry for each address of a given system.

The following is an example of two A entries:

;name                  ttl    addr-class    entry-type    address
miaml.cities.dec.com.         IN            A             128.11.22.44
                              IN            A             128.11.22.33

In this example, note that in the first entry the ttl field is blank, thus using the default ttl specified in the SOA entry. In the second entry, the first and second fields are blank, thus using the default name specified in the previous entry and the default ttl specified in the SOA entry. In this example, the host miami.cities.dec.com has two IP addresses.

H.2.4 Canonical Name Entry

The canonical name (CNAME) entry specifies an alias for a canonical name. For example, if the canonical name, (also known as the full DNS name or the fully qualified name) is miami.cities.dec.com, a reasonable alias might be miami or mi.

An alias must be unique, and all other entries should be associated with the canonical name and not with the alias. Do not create an alias and then use it in other entries. A CNAME entry has the following format:

aliases ttl addr-class entry-type can-name

The fields in the CNAME entry have the values described in Section H.1, with the following exceptions:

Field	Description
`alias`	This field specifies the nickname (alias) of the canonical name of the host.
`can-name`	This is the canonical name of the host. If the canonical name is a part of the current domain, you need to specify only the host name, for example, miami. If the canonical name is for a host in another domain, you must specify the fully qualified DNS name, followed by a period (.). For example: ohio.state.dec.com.

The following example shows two CNAME entries. The first entry is for a CNAME in the current domain, cities.dec.com; the second entry is for a CNAME in another domain:

;aliases    ttl    addr-class    entry-type    can-name
to                 IN            CNAME         toledo
oh                 IN            CNAME         ohio.state.dec.com.

H.2.5 Host Information Entry

The host information (HINFO) data file entry is for host specific information. This entry lists the hardware and operating system that are running at the specified host system. Only a single space separates the name of the hardware from the operating system information. Thus, if you need to use spaces as part of a host or operating system name, you must place the name in quotation marks. In addition, there can be no more than one HINFO entry for each host on the domain. The following is the HINFO entry format:

host ttl addr-class entry-type hardware opsys

The fields in the HINFO entry have the values described in Section H.1, with the following exceptions:

Field	Description
`host`	This field specifies the host name. If the host is in the current domain, you need to specify only the host, for example, chicago. If the host is in a different domain, you must specify the full DNS name, for example, utah.state.dec.com.. Be sure to include the period (.) at the end of the host name. This indicates the fully qualified DNS name.
`hardware`	This field specifies the type of CPU, for example, an AlphaServer 8400.
`opsys`	This field specifies the type of operating system running on the specified host and should be Tru64 UNIX for the Tru64 UNIX operating system.

The following is an example of a HINFO entry:

;name                ttl   addr-class   entry-type   hardware             opsys
ohio.state.dec.com.        IN           HINFO        "AlphaServer 8400"   "Tru64 UNIX"

In this example, note that the second field specifying the ttl is blank, thus using the default ttl specified in the SOA entry.

H.2.6 Mailbox Entry

The mailbox (MB) entry lists the system where a user wants to receive mail. The following is the format of an MB entry:

login ttl addr-class entry-type system

The fields in the MB entry have the values described in Section H.1, with the following exceptions:

Field	Description
`login`	This field is the login name for a user. Login names must be unique for the domain.
`system`	This field specifies the name system where the user wants to receive mail.

The following is an example of an MB entry:

;login    ttl    addr-class    entry-type    system
fred             IN            MB            potsdam.cities.dec.com.

In this example, note that the second field is blank, thus using the ttl specified in the SOA entry. Consequently, the user Fred will have mail delivered to the host named potsdam in the domain cities.dec.com.

H.2.7 Mail Group Entry

The mail group (MG) entry specifies the members of a mail group. The MG entry is usually used with a MINFO entry. The following is the format of an MG entry:

group ttl addr-class entry-type member

The fields in the MG entry have the values described in Section H.1, with the following exceptions:

Field	Description
`group`	This field specifies the name of the mail group, for example, users or marketing.
`member`	This field specifies the login name and the domain of the user to be included in the mail group.

The following is an example of a MINFO entry and several MG entries:

;group    ttl    addr-class    entry-type    requests        member
fun              IN            MINFO         BIND-REQUEST    fred@miami.cities.dec.com.
                 IN            MG                            john@miami.cities.dec.com.
                               MG                            amy@miami.cities.dec.com.

In this example, note that the second field for all three entries is blank, thus using the ttl specified in the SOA entry. In addition, Fred, John, and Amy will receive any mail sent to the mail group fun.

H.2.8 Mailbox Information Entry

The mailbox information (MINFO) entry creates a mail group for a mailing list. The MINFO entry is usually associated with a mail group (MG) entry, but can also be used with a mailbox (MB) entry. The following is the format of a MINFO entry:

mailbox ttl addr-class entry-type requests maintainer

The fields in the MINFO entry have the values described in Section H.1, with the following exceptions:

Field	Description
`mailbox`	This field specifies the name of the mailbox, and is usually BIND.
`requests`	This field specifies the name where users should send mail relating to the DNS or mail. For example, a user might want to send a mail message requesting that an alias be set up.
`maintainer`	This field contains the login name of the person who should receive mail error messages. This is particularly useful when an error in member's names should be reported to a person other than the sender.

The following is an example of a MINFO entry:

mailbox    ttl    addr-class    entry-type    requests        maintainer
BIND              IN            MINFO         BIND-REQUEST    fred@miami.cities.dec.com.

In this example, note that the second field is blank, thus using the ttl specified in the SOA entry.

H.2.9 Mail Rename Entry

The mail rename (MR) entry lists aliases for a specific user. The following is the format of an MR entry:

alias ttl addr-class entry-type login

The fields in the MR entry have the values described in Section H.1, with the following exceptions:

Field	Description
`alias`	This field lists the nicknames for the specified user. The alias must be unique to the domain.
`login`	This field is the login name for the user whose alias is being established. There should also be a corresponding MB entry for the specified login name. Login names must be unique for the domain.

The following is an example of an MR entry:

;alias    ttl    addr-class    entry-type    login
lady             IN            MR            diana
princess         IN            MR            diana

This example shows how to set up the aliases lady and princess for a user whose login name is diana. Note that the second field is left blank, thus using the ttl specified in the SOA entry.

H.2.10 Mail Exchanger Entry

The mail exchanger (MX) entry specifies a system in the local domain (called a gateway) that knows how to deliver mail to a system that may not be directly connected to the local network. Consequently, the MX entry is useful for systems outside your local network that want to send mail to a user on one of your network's hosts.

You can also use the MX entry to list some of the hosts in the /etc/hosts file so that they do not appear to other systems using the DNS service.

The following is the format of an MX entry:

system ttl addr-class entry-type pref-value gateway

The fields in the MX entry have the values described in Section H.1, with the following exceptions:

Field	Description
`system`	This field specifies the name of the system where mail is to be sent.
`pref-value`	This field specifies the order a mailer should follow when there is more than one way to deliver mail to a given system.
`gateway`	This field contains the name of the gateway system, that is, the system that can deliver mail to the destination system on another network.

The following is an example of two MX entries:

;system                 ttl    addr-class    entry-type    pref-value    gateway
tampa.cities.dec.com           IN            MX            0             seismo.cs.au.
*.folks.dec.com                IN            MX            0             relay.cs.net.

In this example, all mail destined for the domain folks.dec.com, regardless of the host name, is sent by route of the relay.cs.net host. In addition, note that the second field in both entries is blank, thus using the ttl specified in the SOA entry. The second entry uses an asterisk, which is a wildcard.

H.2.11 Name Server Entry

The name server (NS) entry specifies that a system is a name server for the specified domain. The following is the format of the NS entry:

name ttl addr-class entry-type server

The fields in the NS entry have the values described in Section H.1, with the exception of the server field. This field specifies the name of the primary master server for the domain specified in the first field.

The following is an example of an NS entry:

;name    ttl    addr-class    entry-type    server
                IN            NS            utah.states.dec.com.

H.2.12 Domain Name Pointer Entry

The domain name pointer (PTR) entry allows special names to point to some other location in the domain. PTR names should be unique to the zone. These entries are located on a primary server in the file /etc/namedb/hosts.rev. The following is the format of a PTR entry:

rev-addr ttl addr-class entry-type hostname

The fields in the PTR entry have the values described in Section H.1, with the following exceptions:

Field	Description
`rev-addr`	This field specifies the reverse IP address of the host. For example, if the host's address is 128.11.22.33, the reverse address is 33.22.11.128.
`hostname`	This is the fully qualified DNS name of the host, for example, miami.cities.dec.com. Be sure to include the period (.) at the end of the host name if the host is not in the current domain.

The following is an example of two PTR entries:

;rev-addr                     ttl    addr-class     entry-type    hostname
33.22                                IN             PTR           chicago
66.55.44.121.in-addr.arpa.           IN             PTR           mail.peace.org.

In this example, the first entry is for a host whose IP host address is 22.33 in the current domain. The specified rev.addr (33.22) is meaningful assuming that a $origin entry exists. See Section H.2.2 for a description of the $origin entry. If there is not an $origin entry, then the entire IP address, in reverse, must be specified.

The second entry is for a host in different domain (mail.peace.org.). As a rule, you should not do this because you are putting data in your server's cache for which your server is not authoritative. PTR entries and other resource records should be for hosts in your domain only. The PTR entry sets up a reverse pointer for the host mail.peace.org.

H.2.13 Start of Authority Entry

The start of authority (SOA) entry designates the beginning of a zone. There should be no more than one SOA entry per zone. The following is the format of an SOA entry:

name ttl addr-class entry-type origin person serial# refresh retry \ expire min

The forward slash (\) indicates line continuation.

The fields in the SOA entry have the values described in Section H.1, with the following exceptions:

Field	Description
`origin`	This field is the name of the host on which the data file resides. This is usually a master server.
`person`	This field defines the login name and mailing address of the person responsible for the DNS running on the local domain.
`serial#`	This field specifies the version number of the data file. The person editing the master files for the zone should increment the value in this field each time a change is made to the data within the file. The serial number being changed informs the secondary servers that there is new data to be obtained from the master server. The maximum number is 2³²-1 after the decimal point. The serial number field allows the DNS to determine which of two copies of data files in a zone are more recent. Typically, the serial number field begins at one (1) and is incremented by one each time the original data file is modified. It is best to use whole integers.
`refresh`	This field specifies how often, in seconds, a secondary DNS server is to check with the master server to see if it needs to update its data files. If the data files are out of date (as indicated by a mismatch of serial number fields), they are updated with the contents of the master server's files. The minimum refresh period is 30 seconds. If the refresh field is blank, however, the data file is not dynamically updated.
`retry`	This field specifies how often, in seconds, a secondary DNS server will try to refresh its data files after a refresh failure has occurred while making the check. If a DNS server attempts to refresh the files and fails, it tries to refresh them again every so many seconds, as specified in the retry field.
`expire`	This field specifies the upper limit, in seconds, that a secondary DNS server can use the data files in its cache before the data expires for lack of being updated, or before the DNS server checks to see if its cache needs to be updated.
`min`	This field specifies the default time to live, in seconds, that a data entry can exist in the event that the ttl entry is left blank.

The following is an example of an SOA entry. The first line is a comment that shows the fields:

;name   ttl   addr-class   entry-type   origin                              person
@             IN           SOA          utah.states.dec.com. hes.utah.states.dec.com. (
                                            1       ; serial
                                            3600    ; refresh every hr.
                                            300     ; retry every 5 min.
                                            3600000 ; expire in 1000 hrs.
                                            86400 ) ; min. life is 24 hrs.

In this example note that the parentheses indicate to the DNS that this is a single entry. The ttl field is blank, indicating that the default time to live specified in the min field (86400 seconds) is being used.

The semicolons allow comments for readability. In the example, the serial field is 1, the refresh field is 3600 seconds (once per hour), the retry field is 300 seconds (once per 5 minutes), the expire field is 3,600,000 seconds (1000 hours), and the min field is 86400 seconds (24 hours).

H.2.14 Well Known Services Entry

The well known services (WKS) entry describes well known services supported by a particular protocol at a specified address. The services and port numbers are obtained from the list of services specified in the /etc/services file. The following is the format of a WKS entry:

name ttl addr-class entry-type address protocol services

The fields in the WKS entry have the values described in Section H.1, with the following exceptions:

Field	Description
`address`	This field specifies the IP address for each system. There should be only one WKS entry for each protocol at each address.
`protocol`	This field specifies the protocol to be used, for example TCP or UDP.

Here is an example of two WKS entries:

;name    ttl    addr-class    entry-type    address       protocol    services
                IN            WKS           128.32.0.4    UDP         who route
                IN            WKS           128.32.0.78   TCP         (echo talk
                                                              discard sunrpc sftp
                                                              uucp-path netstat host
                                                              systat daytime link
                                                              auth time ftp
                                                              nntp whois pop
                                                              finger smtp supdup
                                                              domain nameserver
                                                              chargen)

Note that the first and second fields of both entries in this example are blank, which indicates that they are using the domain name specified in a previous entry and the default ttl specified in the SOA entry. The services listed in the second entry are contained within parentheses and are thus interpreted as being one entry, even though they appear to be on several lines.