named.docbook revision 0f78f780648806bcb3e374b7dafac73e6c558ea8
5cd4555ad444fd391002ae32450572054369fd42Rob Austein<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
5cd4555ad444fd391002ae32450572054369fd42Rob Austein "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein [<!ENTITY mdash "—">]>
c1a883f2e04d94e99c433b1f6cfd0c0338f4ed85Mark Andrews - Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC")
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
dd750c560ae48cf6caeb9a9fe81d33fc4746106dBrian Wellington - Permission to use, copy, modify, and distribute this software for any
dd750c560ae48cf6caeb9a9fe81d33fc4746106dBrian Wellington - purpose with or without fee is hereby granted, provided that the above
dd750c560ae48cf6caeb9a9fe81d33fc4746106dBrian Wellington - copyright notice and this permission notice appear in all copies.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews<!-- $Id: named.docbook,v 1.17 2007/05/16 01:42:26 marka Exp $ -->
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <refentryinfo>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </refentryinfo>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <refentrytitle><application>named</application></refentrytitle>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <refnamediv>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <refname><application>named</application></refname>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <refpurpose>Internet domain name server</refpurpose>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <refsynopsisdiv>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <cmdsynopsis>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews <arg><option>-m <replaceable class="parameter">flag</replaceable></option></arg>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <arg><option>-x <replaceable class="parameter">cache-file</replaceable></option></arg>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </cmdsynopsis>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is a Domain Name System (DNS) server,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein part of the BIND 9 distribution from ISC. For more
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein information on the DNS, see RFCs 1033, 1034, and 1035.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein When invoked without arguments, <command>named</command>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein read the default configuration file
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <filename>/etc/named.conf</filename>, read any initial
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein data, and listen for queries.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <variablelist>
0ffaee887ff5674b8c3bb0435ae838f641981706Mark Andrews <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Use IPv4 only even if the host machine is capable of IPv6.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <option>-4</option> and <option>-6</option> are mutually
0ffaee887ff5674b8c3bb0435ae838f641981706Mark Andrews </varlistentry>
0ffaee887ff5674b8c3bb0435ae838f641981706Mark Andrews <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Use IPv6 only even if the host machine is capable of IPv4.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <option>-4</option> and <option>-6</option> are mutually
0ffaee887ff5674b8c3bb0435ae838f641981706Mark Andrews </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <term>-c <replaceable class="parameter">config-file</replaceable></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Use <replaceable class="parameter">config-file</replaceable> as the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein configuration file instead of the default,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein ensure that reloading the configuration file continues
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to work after the server has changed its working
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein directory due to to a possible
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <option>directory</option> option in the configuration
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein file, <replaceable class="parameter">config-file</replaceable> should be
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein an absolute pathname.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <term>-d <replaceable class="parameter">debug-level</replaceable></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Debugging traces from <command>named</command> become
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein more verbose as the debug level increases.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Run the server in the foreground (i.e. do not daemonize).
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Run the server in the foreground and force all logging
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews <varlistentry>
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews <term>-m <replaceable class="parameter">flag</replaceable></term>
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews Turn on memory usage debugging flags. Possible flags are
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews <replaceable class="parameter">usage</replaceable>,
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews <replaceable class="parameter">trace</replaceable>,
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews <replaceable class="parameter">record</replaceable>,
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews <replaceable class="parameter">size</replaceable>, and
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews <replaceable class="parameter">mctx</replaceable>.
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews These correspond to the ISC_MEM_DEBUGXXXX flags described in
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <term>-n <replaceable class="parameter">#cpus</replaceable></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Create <replaceable class="parameter">#cpus</replaceable> worker threads
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to take advantage of multiple CPUs. If not specified,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <command>named</command> will try to determine the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein number of CPUs present and create one thread per CPU.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein If it is unable to determine the number of CPUs, a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein single worker thread will be created.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <term>-p <replaceable class="parameter">port</replaceable></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Listen for queries on port <replaceable class="parameter">port</replaceable>. If not
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein specified, the default is port 53.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Write memory usage statistics to <filename>stdout</filename> on exit.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This option is mainly of interest to BIND 9 developers
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and may be removed or changed in a future release.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <term>-t <replaceable class="parameter">directory</replaceable></term>
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark Andrews <para>Chroot
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to <replaceable class="parameter">directory</replaceable> after
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein processing the command line arguments, but before
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein reading the configuration file.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This option should be used in conjunction with the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <option>-u</option> option, as chrooting a process
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein running as root doesn't enhance security on most
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark Andrews systems; the way <function>chroot(2)</function> is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein defined allows a process with root privileges to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein escape a chroot jail.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <term>-u <replaceable class="parameter">user</replaceable></term>
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark Andrews <para>Setuid
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to <replaceable class="parameter">user</replaceable> after completing
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein privileged operations, such as creating sockets that
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein listen on privileged ports.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein On Linux, <command>named</command> uses the kernel's
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein capability mechanism to drop all root privileges
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark Andrews except the ability to <function>bind(2)</function> to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein privileged port and set process resource limits.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Unfortunately, this means that the <option>-u</option>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein option only works when <command>named</command> is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein later, since previous kernels did not allow privileges
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark Andrews to be retained after <function>setuid(2)</function>.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Report the version number and exit.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <term>-x <replaceable class="parameter">cache-file</replaceable></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Load data from <replaceable class="parameter">cache-file</replaceable> into the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein cache of the default view.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This option must not be used. It is only of interest
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to BIND 9 developers and may be removed or changed in a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein future release.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein In routine operation, signals should not be used to control
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the nameserver; <command>rndc</command> should be used
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <variablelist>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Force a reload of the server.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Shut down the server.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The result of sending any other signals to the server is undefined.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The <command>named</command> configuration file is too complex
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to describe in detail here. A complete description is provided
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <variablelist>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <term><filename>/etc/named.conf</filename></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The default configuration file.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <term><filename>/var/run/named.pid</filename></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The default process-id file.
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </varlistentry>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley </variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
84910d09ee8244027c7031e03999bc60a3d63adbMark Andrews </citerefentry>,
84910d09ee8244027c7031e03999bc60a3d63adbMark Andrews <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><corpauthor>Internet Systems Consortium</corpauthor>
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley - Local variables:
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley - mode: sgml