in.named(1M)

NAME

in.named, named − internet domain name server

SYNOPSIS

in.named [ −q ] [ −r ] [−b bootfile ] [ −d debuglevel ] [ −p port[/localport] ]

DESCRIPTION

in.named is the Internet domain name server. in.named spawns the named-xfer process whenever it needs to perform a zone transfer (see named-xfer(1M)).

The in.named name service is used by hosts on the Internet to provide access to the Internet distributed naming database. See RFC 1034 and RFC 1035 for more information on the Internet name-domain system.

With no arguments, in.named reads the default boot file /etc/named.boot for any initial data, and listens for queries.

Any additional arguments beyond those shown in the SYNOPSIS section are interpreted as the names of boot files. If multiple boot files are specified, only the last is used.

The name server reads the boot file to obtain instructions on where to find its initial data.

OPTIONS

−b bootfile Use bootfile rather than /etc/named.boot. This option allows filenames to begin with a leading dash.

−d level Print debugging information. level is a number indicating the level of messages printed.

−p port/localport Use different, port numbers. The default is the standard port number as returned by getservbyname(3N) for service domain. The −p argument can specify up to two port numbers. The specification of two port numbers requires a ‘/’ (slash) separator. In this case, the first port is used when contacting remote servers, and the second one is the service port bound by the local instance of in.named. This option is used mostly for debugging purposes.

−q Trace all incoming queries. Note: this option is ignored in favor of the boot file directive, options query-log, when both options are used.

−r Turns recursion off in the server. Answers can come only from local (primary or secondary) zones. This option can be used on root servers. Note: This option will probably be eventually abandoned in favor of the boot file directive, options no-recursion.

USAGE

/etc/named.boot File Directives

The following is a sample /etc/named.boot file containing directives to guide the in.named process at startup time.

Long directives must fit on a single line; they will be misinterpreted if continued on subsequent lines. The semicolon character initiates the beginning of a line of ignored (comment) text. Text is ignored between the semicolon and the next newline character.

;boot file for the name server
directory /usr/local/adm/named

;type	domain	source host/file	backup_file
cache	.	root.cache
primary	Berkeley.EDU	berkeley.edu.zone
primary	32.128.IN-ADDR.ARPA	ucbhosts.rev
secondary	CC.Berkeley.EDU	128.32.137.8 128.32.137.3	cc.zone.bak
secondary	6.32.128.IN-ADDR.ARPA	128.32.137.8 128.32.137.3	cc.rev.bak
primary	0.0.127.IN-ADDR.ARPA	localhost.rev
forwarders	10.0.0.78 10.2.0.78
limit	transfers-in 10
options	forward-only query-log fake-iquery

The following list includes all of the directives that may be placed in the boot file. If a list item is present in the previous sample file, a discussion of the item in the sample file is included. These discussions are always introduced with the phrase, “Example Directive.”

bogusns address-list
Specifies that this server implements a special form of primitive access control. This server will not process queries which need to be sent to name server addresses (specified as dotted quads, not as domain names) given in address-list. This directive is useful when you know that some popular server has bad data in a zone or cache, and you want to avoid contamination while the problem is being fixed.

cache domain root-server-hints-file
Specifies that this server plays a caching name-server role by reading and occasionally updating root-server-hints-file. Access to this cache is not usually required during normal operation. During startup, however, it is used to obtain hints for finding the current root servers. The initial data in root-server-hints-file typically includes the locations of root domain servers for a local network that is not directly connected to the Internet. Otherwise, it lists Internet name servers.

The information in root-server-hints-file typically includes a list of root servers specified in terms of their name and address, and formatted in terms of resource records of type NS (nameserver) and type A (Internet address). (The resource record formats are described later in the section, Format of Resource Records in Zone Files.) The root.cache cache file for a server that is being connected directly to the Internet should be retrieved periodically from FTP.RS.INTERNIC.NET, since it contains a list of root servers that is occasionally updated.

Example Directive: The cache line in the example configuration file specifies that root.cache is the place for in.named to find and maintain a backup cache of root name servers.

directory dir
Causes the name server to change its working directory to the specified directory. This can help ensure the correct processing of any $INCLUDE directives that may reside in files that are referenced within primary directives in the configuration file.

Example Directive: The directory line in the example configuration file specifies that /usr/local/adm/named becomes the current path, when relative pathnames need to be resolved within the configuration file or within files that the configuration file references.

forwarders address-list
Specifies the addresses of sitewide servers that will accept recursive queries from other servers. If the boot file specifies one or more forwarders, this server sends all queries for data not in the cache to the forwarders first. Each forwarder is asked in turn until an answer is returned or the list is exhausted. If no answer is forthcoming from any forwarder, the server continues as it would have without the forwarders line unless it is in a forward-only mode.

The forwarding facility is useful for generating a large sitewide cache on a master, and for reducing traffic over links to outside servers. It can also be used to allow servers to run, that do not have direct access to the Internet, but wish to look up exterior names anyway.

Example Directive: The forwarders line in the example configuration file specifies 10.0.0.78 and 10.2.0.78 as two sitewide servers that can accept recursive queries from other servers.

include include-file
Causes the contents of include-file to be interpreted as additional boot directives, as though these contents had actually been entered at this location in the boot file. This can be useful for dealing with many zones or for implementing logical groupings of zones which are maintained by different people. Quotes around the filename are not necessary.

limit parameter-name size
Resets the internal limits of the BIND name server. Some of the supported limit values (datasize, for example) are implemented by the system and others (such as transfers-in) are implemented by BIND itself. The possible parameter-name and size values are:

datasize
The datasize limit value is not supported.

transfers-in max-processes
Sets the maximum number of named-xfer subprocesses which BIND will spawn at any one time.

transfers-per-ns max-transfers
Sets the maximum number of zone transfers to be simultaneously initiated to any given remote name server.

loglevel syslog-priority
Sets the minimum priority level of syslog(3) messages. Syslog messages at a lower priority (larger numerical value) are suppressed. The default is 5, corresponding to LOG_NOTICE, which filters out most informational chatter. Setting the loglevel to 7 (LOG_DEBUG) allows all messages. Suppressing at level 3 (LOG_ERR) or higher may mean that in.named will be unable to report fatal problems. See syslog and sys/syslog.h for priorities and corresponding numerical values.

listen-backlog backlog
Sets the backlog parameter for listen(3N). The maximum value is limited by the tcp_conn_req_max TCP configuration parameter. The default backlog is 5. The listen-backlog value is changed only when in.named is restarted; a SIGHUP is not sufficient.

Example Directive: The limit line in the example configuration file specifies that as many as ten concurrent BIND subprocesses can be spawned on this server.

max-fetch size
Establishes a limit that is identical to the one previously described for limit transfers-in. This directive is provided for backward compatibility.

options option-list
Switch on certain options that effect changes to the behavior of BIND. More than one boolean option can be specified in a single directive. The currently defined options are:

fake-iquery
Since in.named always responds to inverse queries, the fake-iquery option would have no useful effect, and is rejected as illegal.

forward-only
Causes the server to query only its forwarders. This option is normally used on a system that wishes to run a server but for physical or administrative reasons cannot be given access to the Internet.

no-fetch-glue
Keeps BIND from fetching missing glue when constructing the additional data section of a response. This can be used in conjunction with no-recursion to prevent BIND’s cache from ever growing in size or becoming corrupted.

no-recursion
Causes BIND to answer with a referral rather than actual data whenever it receives a query for a name for which this server does not play an authoritative role. Avoid setting this option on a server that is listed in any host’s resolv.conf file.

query-log
Causes all queries to be logged through syslog() (see syslogd(1M) and syslog(3)). Because this option results in the generation of considerable data, don’t turn it on lightly.

Example Directive: The options line in the example configuration file specifies forward-only, query-log, and fake-iquery, requesting the associated modifications in BIND behavior for this server.

primary zone master-file
Specifies that this server plays the primary name-server role for zone, by following the authoritative specifications in master-file. Each master file should begin with an SOA record for the zone (see Zone File Format).

Example Directives:

The first primary line in the example configuration file specifies that the file, berkeley.edu.zone, contains authoritative data for the Berkeley.EDU zone. Accordingly, the master file, berkeley.edu.zone, must contain data in the master file format described in RFC 883. All domain names are relative to the origin, which in this case is Berkeley.EDU (see below for a more detailed description).

The second primary line in the example configuration file states that the file ucbhosts.rev contains authoritative data for the zone, 32.128.IN-ADDR.ARPA. These data are used to translate addresses in network 128.32 to hostnames.

The third primary line in the example configuration file is interpreted in the same way as the preceding ones.

secondary zone address-list zone-backup-file
Specifies that this server plays a secondary name-server role for zone domain by fetching authoritative data moderated through the IP addresses in address-list. This server will try as many as 10 addresses specified in address-list, in the order that they are listed. Any argument following address-list that lacks the dotted-quad address format is interpreted as the zone-backup-file, the file into which it places a backup of the transferred zone. This secondary copy of the zone on this server is nevertheless considered authoritative for the specified domain. Whenever a new copy of the domain is received by automatic zone transfer from one of the master servers, this file is updated. If no zone-backup-file is specified, a temporary file is used. The temporary file is deleted after each successful zone transfer. Not specifying a zone-backup-file is not recommended because it is a needless waste of bandwidth.

Example Directive: The first secondary line in the example configuration file specifies that the authoritative data for the zone, CC.Berkeley.EDU, is taken from the name server at IP address, 128.32.137.8. If the transfer fails for this first address, this server tries 128.32.137.3. Furthermore, when it boots, this name server will load the zone from the backup file cc.zone.bak if it exists, providing a complete copy even if the master servers are unreachable.

The second secondary line in the example configuration file specifies that the address-to-hostname mapping for the subnet 128.32.136 should be obtained from the same list of master servers as those specified in the previous line.

slave Establishes forward-only mode. This option is allowed for backward compatibility. Its meaning is identical to a line containing options forward-only.

sortlist address-list
Specifies that this server will return host addresses in a sort order moderated by address-list. This is used to indicate networks that are to be preferred over other networks. Queries for host addresses from hosts on the same network as the server receives responses, with local network addresses listed first, then addresses on the sort list, then other addresses.

tcplist address-list

xfrnets address-list
Specifies that this server implements primitive access control in accordance with address-list. This directive causes a name server to only answer zone transfer requests from hosts which are on networks listed in address-list. This directive may also be given as tcplist for compatibility with older, interim servers.

Zone File Format

The zone files are also known as the authoritative master files (data files) for a zone. In the boot file, references were made to these files as part of the specification of any primary directives.

Two classes of entries populate the zone files, directives and resource records. The start of the zone file is likely to contain one or two directives that establish a context that modifies the way subsequent records are interpreted.

Resource records for a zone determine how a zone is managed by establishing zone characteristics. For example, one type of zone record establishes the zone’s mailbox information.

The very first record of each zone file should be a Start-of-Authority record ( SOA ) for a zone. A multiple-line SOA record is presented below. The meaning of the values in this sample will become clearer with the help of a list that describes the purpose of each field in the zone record (see the SOA list subitem under the rr-type list item in, Format of Resource Records in Zone Files).

@ IN SOA ucbvax.Berkeley.EDU. rwh.ucbvax.Berkeley.EDU. (

1989020501	;serial
10800	;refresh
3600	;retry
3600000	;expire
86400 )	;minimum

Resource records normally end at the end of a line, but may be continued across lines between opening and closing parentheses (as demonstrated by the preceding sample).

Comments are introduced by semicolons. They continue to the end of the line.

Directives in Zone Files

There are two control directives that help determine how the zone file is processed, $INCLUDE and $ORIGIN .

The $INCLUDE directive refers to still another file within which zone characteristics are described. Such files typically contain groups of resource records, but they may also contain further directives.

The $ORIGIN directive establishes a current origin that is appended to any domain values that do not end with a `.´ (dot). The placeholder domain represents the first resource record field as shown in Format of Resource Records in Zone Files.

The format for these directives is

$INCLUDE filename opt-current-domain
$ORIGIN current-domain

where:

current-domain Specifies the value of the current origin that remains in effect for this configuration file unless a subsequent $ORIGIN directive overrides it for the remaining portion of the file.

filename Specifies a file, the contents of which are, in effect, incorporated into the configuration file at the location of the corresponding $INCLUDE directive.

opt-current-domain Optionally defines a current origin that is applicable only to the records residing in the specified file in the corresponding $INCLUDE directive. This directive overrides the origin given in a preceding $ORIGIN directive, but only for the scope of the included text. See also current-domain.

Neither the opt-current-domain argument of $INCLUDE nor the $ORIGIN directive in the included file can affect the current origin in effect for the remaining records in the main configuration file (as defined by those $ORIGIN directives that reside there).

Format of Resource Records in Zone Files

The format of the resource records is

domain opt-ttl opt-class rr-type rr-data...

Where:

domain Specifies the domain being described by the current line and any following lines that lack a value for this field. Beware of any domain values that you enter without full qualification, because the value of the current origin will be appended to them. The value of the current origin is appended when domain does not end with a dot.

A domain value specified as the symbol @ is replaced with the value of the current origin. The current-domain or any locally-overriding opt-current-domain value is used as its replacement. (For a discussion of these placeholders, see the earlier discussion of the $ORIGIN and $INCLUDE directives.)

A domain value specified as a `.´ (dot) represents the root.

opt-ttl Specifies the number of seconds corresponding to the time-to-live value applicable to the zone characteristic that is defined in the remaining fields. This field is optional. It defaults to zero. Zero is interpreted as the minimum value specified in the SOA record for the zone.

opt-class Specifies the object address type; currently only one type is supported, IN, for objects connected to the Internet.

rr-type rr-data...
Specifies values that describe a zone characteristic.

Permissible rr-type and other field values are listed below. (Field values are listed in the order that they must appear.)

A address
Specifies the host address (in dotted-quad format). DCE or AFS server

CNAME canonical-name
Specifies in a domain-name format the canonical name for the alias (domain).

HINFO cpu-type OS-type
Host information supplied in terms of a CPU type and an OS type.

MX preference mail-exchanger
Specifies in domain-name format a mail exchanger preceded by a preference value (between 0 and 32767), with lower numeric values representing higher logical preferences.

NS authoritative-server
Specifies in domain-name format an authoritative name server.

NULL Specifies a null zone record.

PTR domain-pointer
Specifies in domain-name format a domain name pointer.

RP mailbox txt-referral
Offers details about how to reach a responsible person for the domain name.

SOA host-domain maintainer-addr serial-no refresh retry expire ttl
Establishes the start of a zone of authority in terms of the domain of the originating host (host-domain), the domain address of the maintainer (maintainer-addr), a serial number (serial-no), the refresh period in seconds (refresh), the retry period in seconds (retry), the expiration period in seconds (expire), and the minimum time-to-live period in seconds (ttl). See RFC 1035.

The serial number should be changed each time the master file is changed. Secondary servers check the serial number at intervals specified by the refresh time in seconds; if the serial number changes, a zone transfer will be done to load the new data.

If a master server cannot be contacted when a refresh is due, the retry time specifies the interval at which refreshes should be attempted. If a master server cannot be contacted within the interval given by the expire time, all data from the zone is discarded by secondary servers. The minimum value is the time-to-live used by records in the file with no explicit time-to-live value.

The serial number can be given as a dotted number. However, this is a very unwise thing to do, since the translation to normal integers is via concatenation rather than multiplication and addition. You could spell out the year, month, day of month, and 0..99 version number and still fit it inside the unsigned 32-bit size of this field. This strategy should work for the forseeable future (but is questionable after the year 4293).

For more detailed information, see RFC 883.

rr-data... See the description of rr-type.

Consult Name Server Operations Guide for BIND for further information about the supported types of resource records.

EXIT STATUS

The in.named process returns the following exit statuses:

0Successful completion.

1An error occurred.

FILES

/etc/named.boot name server configuration boot file

/etc/named.pid the process ID (on older systems)

/var/tmp/named.run debug output

/var/tmp/named.stats nameserver statistics data

/var/tmp/named_dump.db dump of the name servers database

/var/tmp/named.pid the process ID (on newer systems)

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcsu

NOTES

The following signals have the specified effect when sent to the server process using the kill(1) command:

SIGHUP Causes the server to read /etc/named.boot and reload the database. SIGHUP also causes the server to check the serial number on all secondary zones. Normally the serial numbers are only checked at the intervals specified by the SOA record at the start of each zones-definition file.

SIGINT Dumps the current database and cache to /var/tmp/named_dump.db.

SIGIOT Dumps statistical data into /var/tmp/named.stats. Statistical data are appended to the file.

SIGUSR1 Turns on debugging at the lowest level when received the first time; receipt of each additional SIGUSR1 signal causes the server to increment the debug level.

SIGUSR2 Turns off debugging completely.

SIGWINCH
Toggles logging of all incoming queries through the syslog system daemon (see syslogd(1M)).

SunOS 5.6 — Last change: 24 Jun 1997

Museum

Related Articles