named(1M)

NAME

named — Internet domain name server

SYNOPSIS

named [-4] [-c config_file] [-d debuglevel] [-f] [-g] [-n no_of_cpus] [-p port_number] [-t directory] [-u user_id] [-v]

DESCRIPTION

named is the Internet domain name server. See RFC 1033, RFC 1034, and RFC 1035 for more information on the Domain Name System (DNS). Without any arguments, named reads the default configuration file /etc/named.conf, reads any initial data, and listens for queries. named requires superuser privileges to execute.

Options

-4

Use IPv4 only, even if the host machine is capable of IPv6.

-c config_file

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

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

-f

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

-g

Specifies to log all the logging to stderr while named is running in foreground.

-n no_of_cpus

This option can be used to create worker threads equal to no_of_cpus to take advantage of multiple CPUs. If no option is given, named will try to determine the number of CPUs present and create one thread per CPU. If named is unable to determine the number of CPUs, a single worker thread is created.

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

-t directory

Specifies the working directory the server should run. 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 (.).

-u user_id

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

-v

Report version number and exit.

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;
        };
};
key rndc_key {
          algorithm "hmac-md5";
          secret "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
};

controls {
               inet 127.0.0.1 allow { 127.0.0.1; } keys { rndc_key; };
};

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 changes the working directory of the server to the directory specified. The working directory specified is relative to the new root directory if set by the -t option. 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 RFC 1035.

The key statement names a key with its string argument. The string has to be a valid domain name. However, this need not be hierarchical; thus, a string "rndc_key" is a valid name.

The key statement has two clauses: algorithm and secret. The configuration parser will accept any string as the argument to algorithm. However, only the string "hmac-md5" is supported for accepting control messages from the utility, rndc. See rndc(1) and rndc.conf(4). The secret is a base-64 encoded string, typically generated with dnssec-keygen.

The controls statement is used to configure the name server to accept connections from the utility, rndc which controls the name server. The key specified in this statement should match the one set in the rndc configuration file, rndc.conf.

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.

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

IPv6 Options

listen-on-v6

This option will specify the ports on which the server will listen for incoming queries sent using IPv6. In this option, only two values are supported: any and none. If this option is not specified in the named configuration file (named.conf), named will not listen on any IPv6 interfaces.

Examples, using any:

listen-on-v6 port 80 {any;};

listen-on-v6 port 1234 {any;};

Example, using none, to stop the server from listening to IPv6 addresses:

listen-on-v6 {none;};

NOTE: The hosts_to_named configuration file migration script does not add the listen-on-v6 option to the named.conf file on dual stack machine. In order to enable DNS services to listen on IPv6 interfaces, this entry needs to be added manually.

query-source-v6

This option will specify the server with IPv6 address, which is to be contacted for the answer to a query from an IPv6 source.

Example:

query-source-v6 address c000:1::a35 port 5000

transfer-source-v6

This option is similar to the transfer-source option, but is meant for zone transfers using IPv6. This works in an identical fashion for both Options statement grammar and Zone statement grammar.

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: All the db files have to start with a $TTL value. 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 RFCs 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, it is not advisable to give the serial number as a dotted number, 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 name server 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.
SIGINT & SIGTERM: Signals can be used to gracefully shut down the server.

Sending any other signals to the name server will have undefined outcome.

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

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, ./named.run, if debugging is on and named will quit.

AUTHOR

named was developed by the University of California, Berkeley.

FILES

/etc/named.conf: name server configuration file
/var/run/named.pid: process ID
./named.run: debug output