named(1M)

NAME

named — Internet domain name server

SYNOPSIS

named [-d debuglevel] [-p port_number] [[-(b|c)] config_file] [-f] [-q] [-r] [-u user_name] [-g group_name] [-t directory] [-w directory] [config_file]

DESCRIPTION

named is the Internet domain name server. See RFC1033, RFC1034 and RFC1035 for more information on the Domain Name System. Without any arguments, named reads the default configuration file /etc/named.conf, reads any initial data, and listens for queries.

Options are:

-d debuglevel

Print debugging information. A number after the d determines the level of messages printed. If negative, debuglevel is set to ``1''.

NOTE: The new debugging framework is considerably more sophisticated than it was in older versions of NAMED. The configuration file's logging statement allows for multiple, distinct levels of debugging for each of a large set of categories of events (such as queries, transfers in or out, etc.).

-p port_number

Use a different port number.

NOTE: Previously, the syntax: " -p port#[/localport#] " was supported; the first port was that used when contacting remote servers, and the second one was the service port bound by the local instance of NAMED. The current usage is equivalent to the old usage without the localport# specified; this functionality can be specified with the listen-on clause of the configuration file's options statement.

-(b|c) config_file

Use a config_file other than /etc/named.conf.

-f

Run this process in the foreground; don't fork(2) and daemonize. (The default is to daemonize.)

-q

Trace all incoming queries, if NAMED has been compiled with QRYLOG defined.

NOTE: This option is deprecated in favor of the queries logging category of the configuration file's logging statement.

-r

Turns recursion off in the server. Answers can only come from local (primary or secondary) zones. This can be used on root servers. The default is to use recursion.

NOTE: This option can be overridden by and is deprecated in favor of the recursion clause of the configuration file's options statement.

-u user_name

Specifies the user the server should run as after it initializes. The value specified may be either a username or a numeric user id. If the -g flag is not specified, then the group id used will be the primary group of the user specified (initgroups() is called, so all of the user's groups will be available to the server).

-g group_name

Specifies the group the server should run as after it initializes. The value specified may be either a groupname or a numeric group id.

-t directory

Specifies the directory the server should chroot() into as soon as it is finished processing command line arguments.

-w directory

Sets the working directory of the server. The directory clause of the configuration file's options statement overrides any value specified on the command line. The default working directory is the current directory (.).

Any additional argument is taken as the name of the configuration file. The configuration file contains information about where the name server gets its initial data. If multiple configuration files are specified, only the last is used. Lines in the configuration file cannot be continued on subsequent lines. The following is a small example:

//
/*     configuration file for name server     */
#
options {
        directory "/usr/local/domain";
        forwarders {
                10.0.0.78;
                10.2.0.78;
        };
        noforward {
                test.com;
                c.b.a.in-addr.arpa;
        };
        sortlist {
                10.0.0.0;
                26.0.0.0;
        };
};

zone "." {
        type hint;
        file "db.cache";
};

zone "berkeley.edu" {
        type master;
        file "db.berkeley";
};

zone "32.128.in-addr.arpa" {
        type master;
        file "db.128.32";
};

zone "cc.berkeley.edu" {
        type slave;
        file "db.cc";
        masters {
                128.32.137.8;
        };
};

};

The directory statement causes the server to change its working directory to the directory specified. This can be important for the correct processing of $INCLUDE files (described later) in primary server's master files.

Files referenced in the configuration file contain data in the master file format described in RFC1035.

The forwarders line specifies the addresses of sitewide servers that will accept recursive queries from other servers. If the configuration file specifies one or more forwarders, then the server will send all queries for data not in the cache or in its authoritative data to the forwarders first. Each forwarder will be asked in turn until an answer is returned or the list is exhausted. If no answer is forthcoming from a forwarder, the server will continue as it would have without the forwarders line unless it is in forward-only mode. The forwarding facility is useful to cause a large sitewide cache to be generated on a master, and to reduce traffic over links to outside servers.

The noforward line specifies that the DNS server will not forward any request for something in or below the listed domains, even if the forwarders directive exists.

The sortlist line can be used to indicate networks that are preferred over other, unlisted networks. Address sorting only happens when the query is from a host on the same network as the server. The best address is placed first in the response. The address preference is local network addresses, then addresses on the sort list, then other addresses.

A server can access information from servers in other domains given a list of root name servers and their addresses. The zone "." line specifies that data in db.cache is to be placed in the backup cache. Its use is to prime the server with the locations of root domain servers. This information is used to find the current root servers and their addresses. The current root server information is placed in the operating cache. Data for the root nameservers in the backup cache are never discarded.

The zone "berkeley.edu" line states that the master file db.berkeley contains authoritative data for the berkeley.edu zone. A server authoritative for a zone has the most accurate information for the zone. All domain names are relative to the origin, in this case, berkeley.edu (see below for a more detailed description).

The zone "32.128.in-addr.arpa" line states that the file db.128.32 contains authoritative data for the domain 32.128.in-addr.arpa. This domain is used to translate addresses in network 128.32 to hostnames.

The zone "cc.berkeley.edu" line specifies that all authoritative data in the cc.berkeley.edu zone is to be transferred from the name server at Internet address 128.32.137.8 and will be saved in the backup file db.cc. Up to 10 addresses can be listed on this line. If a transfer fails, it will try the next address in the list. The secondary copy is also authoritative for the specified domain. The first non-Internet address on this line will be taken as a filename in which to backup the transferred zone. The name server will load the zone from this backup file (if it exists) when it boots, providing a complete copy, even if the master servers are unreachable. Whenever a new copy of the domain is received from one of the master servers, this file is updated. If no file name is given, a temporary file will be used and will be deleted after each successful zone transfer. This is not recommended because it causes a needless waste of bandwidth.

Master File Format

The master file consists of control information and a list of resource records for objects in the zone of the forms:

$INCLUDE filename  opt_domain
$ORIGIN domain
domain  opt_ttl  opt_class  type  resource_record_data  

where:

domain

is . for root, @ for the current origin, or a standard domain name. If domain is a standard domain name that does not end with ``.'', the current origin is appended to the domain. Domain names ending with ``.'' are unmodified.

opt_domain

This field is used to define an origin for the data in an included file. It is equivalent to placing an $ORIGIN statement before the first line of the included file. The field is optional. Neither the opt_domain field nor $ORIGIN statements in the included file modify the current origin for this file.

opt_ttl

An optional integer number for the time-to-live field. It defaults to zero, meaning the minimum value specified in the SOA record for the zone.

opt_class

The object address type; currently only one type is supported, IN, for objects connected to the DARPA Internet.

type

This field contains one of the following tokens; the data expected in the resource_record_data field is in parentheses:

A: a host address (dotted-quad IP address)
NS: an authoritative name server (domain)
MX: a mail exchanger (domain), preceded by a preference value (0..32767), with lower numeric values representing higher logical preferences.
CNAME: the canonical name for an alias (domain)
SOA: marks the start of a zone of authority (domain of originating host, domain address of maintainer, a serial number and the following parameters in seconds: refresh, retry, expire and minimum TTL (see RFC 883)).
NULL: a null resource record (no format or data)
RP: a Responsible Person for some domain name (mailbox, TXT-referral)
PTR: a domain name pointer (domain)
HINFO: host information (cpu_type OS_type)
TXT: text data (string)
WKS: a well known service description (IP address followed by a list of services)

Resource records normally end at the end of a line, but may be continued across lines between opening and closing parentheses. Comments are introduced by semicolons and continue to the end of the line.

NOTE: There are other resource record types not shown here. You should consult the BIND Operations Guide (``BOG'') for the complete list. Some resource record types may have been standardized in newer RFC's but not yet implemented in this version of BIND.

SOA Record Format

Each master zone file should begin with an SOA record for the zone. An example SOA record is as follows:

@   IN      SOA     ucbvax.Berkeley.EDU.  rwh.ucbvax.Berkeley.EDU. (
                                      1989020501      ; serial
                                      10800   ; refresh
                                      3600    ; retry
                                      3600000 ; expire
                                      86400 ) ; minimum

The SOA specifies a serial number, which should be changed each time the master file is changed. Note that the serial number can be given as a dotted number, but this is a very unwise thing to do since the translation to normal integers is via concatenation rather than multiplication and addition. You can spell out the year, month, day of month, and 0..99 version number and still fit inside the unsigned 32-bit size of this field. (It's true that we will have to rethink this strategy in the year 4294.)

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 (``TTL'') used by records in the file with no explicit time-to-live value.

NOTE: The boot file directives domain and suffixes have been obsoleted by a more useful, resolver-based implementation of suffixing for partially-qualified domain names. The prior mechanisms could fail under a number of situations, especially when then local nameserver did not have complete information.

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

SIGHUP: Causes server to read named.conf and reload database. If the server is built with the FORCED_RELOAD compile-time option, then SIGHUP will also cause the server to check the serial number on all secondary zones; normally, the serial numbers are only checked at the SOA-specified intervals.
SIGINT: Dumps current data base and cache to /var/tmp/named_dump.db.
SIGILL: Dumps statistics data into named.stats if the server is compiled with -DSTATS. Statistics data is appended to the file.
SIGSYS: Dumps the profiling data in /var/tmp if the server is compiled with profiling (server forks, chdirs and exits).
SIGTERM: Dumps the primary and secondary database files. Used to save modified data on shutdown if the server is compiled with dynamic updating enabled.
SIGUSR1: Turns on debugging; each SIGUSR1 increments debug level.
SIGUSR2: Turns off debugging completely.
SIGWINCH: Toggles the logging of all incoming queries via syslog() (requires server to have been built with the QRYLOG option).

sig_named(1M) can also be used for sending signals to the server process.

NOTE

named checks for symbolic or hard links while writing to the following files:

/var/run/named.pid
/var/tmp/named_dump.db
/var/tmp/named.run
/var/tmp/named.stats

If any of these files is linked to a different file before named writes into them, named will delete that file and create it afresh.

DIAGNOSTICS

Any errors encountered by named in the configuration file, master files, or in normal operation are logged with syslog and in the debug file, /var/tmp/named.run, if debugging is on.

AUTHOR

named was developed by the University of California, Berkeley.

FILES

/etc/named.conf: name server configuration file
/var/run/named.pid: process ID
/var/tmp/named.run: debug output
/var/tmp/named_dump.db: dump of the name server database
/var/tmp/named.stats: nameserver statistics data