named.html revision 8ec3c085233cedb22b05da36e2773c8f357a7e45
6ea1b817e31b89a627e146fe69e23ea0a64c89ecBob Halley - Copyright (C) 2004-2009 Internet Systems Consortium, Inc. ("ISC")
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Permission to use, copy, modify, and/or distribute this software for any
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - purpose with or without fee is hereby granted, provided that the above
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - copyright notice and this permission notice appear in all copies.
d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - PERFORMANCE OF THIS SOFTWARE.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<!-- $Id: named.html,v 1.33 2009/10/06 01:14:41 tbox Exp $ -->
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<a name="man.named"></a><div class="titlepage"></div>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<p><span class="application">named</span> — Internet domain name server</p>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<div class="cmdsynopsis"><p><code class="command">named</code> [<code class="option">-4</code>] [<code class="option">-6</code>] [<code class="option">-c <em class="replaceable"><code>config-file</code></em></code>] [<code class="option">-d <em class="replaceable"><code>debug-level</code></em></code>] [<code class="option">-E <em class="replaceable"><code>engine-name</code></em></code>] [<code class="option">-f</code>] [<code class="option">-g</code>] [<code class="option">-m <em class="replaceable"><code>flag</code></em></code>] [<code class="option">-n <em class="replaceable"><code>#cpus</code></em></code>] [<code class="option">-p <em class="replaceable"><code>port</code></em></code>] [<code class="option">-s</code>] [<code class="option">-S <em class="replaceable"><code>#max-socks</code></em></code>] [<code class="option">-t <em class="replaceable"><code>directory</code></em></code>] [<code class="option">-u <em class="replaceable"><code>user</code></em></code>] [<code class="option">-v</code>] [<code class="option">-V</code>] [<code class="option">-x <em class="replaceable"><code>cache-file</code></em></code>]</p></div>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<p><span><strong class="command">named</strong></span>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User is a Domain Name System (DNS) server,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User part of the BIND 9 distribution from ISC. For more
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User information on the DNS, see RFCs 1033, 1034, and 1035.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User When invoked without arguments, <span><strong class="command">named</strong></span>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User read the default configuration file
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <code class="filename">/etc/named.conf</code>, read any initial
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User data, and listen for queries.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Use IPv4 only even if the host machine is capable of IPv6.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <code class="option">-4</code> and <code class="option">-6</code> are mutually
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Use IPv6 only even if the host machine is capable of IPv4.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <code class="option">-4</code> and <code class="option">-6</code> are mutually
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<dt><span class="term">-c <em class="replaceable"><code>config-file</code></em></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Use <em class="replaceable"><code>config-file</code></em> as the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein configuration file instead of the default,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="filename">/etc/named.conf</code>. To
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User ensure that reloading the configuration file continues
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User to work after the server has changed its working
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein directory due to to a possible
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="option">directory</code> option in the configuration
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein file, <em class="replaceable"><code>config-file</code></em> should be
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein an absolute pathname.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<dt><span class="term">-d <em class="replaceable"><code>debug-level</code></em></span></dt>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Set the daemon's debug level to <em class="replaceable"><code>debug-level</code></em>.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Debugging traces from <span><strong class="command">named</strong></span> become
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User more verbose as the debug level increases.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<dt><span class="term">-E <em class="replaceable"><code>engine-name</code></em></span></dt>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Use a crypto hardware (OpenSSL engine) for the crypto operations
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User it supports, for instance re-signing with private keys from
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein a secure key store. When compiled with PKCS#11 support
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="replaceable"><code>engine-name</code></em>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein defaults to pkcs11, the empty name resets it to no engine.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Run the server in the foreground (i.e. do not daemonize).
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Run the server in the foreground and force all logging
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term">-m <em class="replaceable"><code>flag</code></em></span></dt>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Turn on memory usage debugging flags. Possible flags are
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="replaceable"><code>usage</code></em>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="replaceable"><code>trace</code></em>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="replaceable"><code>record</code></em>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="replaceable"><code>size</code></em>, and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein These correspond to the ISC_MEM_DEBUGXXXX flags described in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="filename"><isc/mem.h></code>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term">-n <em class="replaceable"><code>#cpus</code></em></span></dt>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Create <em class="replaceable"><code>#cpus</code></em> worker threads
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein to take advantage of multiple CPUs. If not specified,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span><strong class="command">named</strong></span> will try to determine the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User number of CPUs present and create one thread per CPU.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If it is unable to determine the number of CPUs, a
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User single worker thread will be created.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt>
91a45a8ad51e9167e674ac5ed9b4c9eb3e7faea6Tinderbox User Listen for queries on port <em class="replaceable"><code>port</code></em>. If not
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User specified, the default is port 53.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User Write memory usage statistics to <code class="filename">stdout</code> on exit.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User This option is mainly of interest to BIND 9 developers
6ea2385360e9e2167e65f9286447da9eea189457Tinderbox User and may be removed or changed in a future release.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<dt><span class="term">-S <em class="replaceable"><code>#max-socks</code></em></span></dt>
6ea2385360e9e2167e65f9286447da9eea189457Tinderbox User Allow <span><strong class="command">named</strong></span> to use up to
6ea2385360e9e2167e65f9286447da9eea189457Tinderbox User <em class="replaceable"><code>#max-socks</code></em> sockets.
6ea2385360e9e2167e65f9286447da9eea189457Tinderbox User<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This option should be unnecessary for the vast majority
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User The use of this option could even be harmful because the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein specified value may exceed the limitation of the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User underlying system API.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User It is therefore set only when the default configuration
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein causes exhaustion of file descriptors and the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User operational environment is known to support the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User specified number of sockets.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Note also that the actual maximum number is normally a little
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein fewer than the specified value because
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span><strong class="command">named</strong></span> reserves some file descriptors
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User for its internal use.
e68c527dff2f1f7df2a542f8d6f9181a27e05eb7Tinderbox User<dt><span class="term">-t <em class="replaceable"><code>directory</code></em></span></dt>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User to <em class="replaceable"><code>directory</code></em> after
0eea9763d88e3edf9b6de585f7cfbb08de977124Tinderbox User processing the command line arguments, but before
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User reading the configuration file.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User This option should be used in conjunction with the
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <code class="option">-u</code> option, as chrooting a process
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User running as root doesn't enhance security on most
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User systems; the way <code class="function">chroot(2)</code> is
a1b05dea35aa30b152a47115e18bbe679d3fcf19Mark Andrews defined allows a process with root privileges to
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User escape a chroot jail.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<dt><span class="term">-u <em class="replaceable"><code>user</code></em></span></dt>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User to <em class="replaceable"><code>user</code></em> after completing
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User privileged operations, such as creating sockets that
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User listen on privileged ports.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User On Linux, <span><strong class="command">named</strong></span> uses the kernel's
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein capability mechanism to drop all root privileges
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein except the ability to <code class="function">bind(2)</code> to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein privileged port and set process resource limits.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Unfortunately, this means that the <code class="option">-u</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein option only works when <span><strong class="command">named</strong></span> is
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein later, since previous kernels did not allow privileges
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User to be retained after <code class="function">setuid(2)</code>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Report the version number and exit.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Report the version number and build options, and exit.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term">-x <em class="replaceable"><code>cache-file</code></em></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Load data from <em class="replaceable"><code>cache-file</code></em> into the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein cache of the default view.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User This option must not be used. It is only of interest
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User to BIND 9 developers and may be removed or changed in a
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User future release.
c4d99a62407cebca29653666ae11f87e4f56ebbcAutomatic Updater In routine operation, signals should not be used to control
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User the nameserver; <span><strong class="command">rndc</strong></span> should be used
c4d99a62407cebca29653666ae11f87e4f56ebbcAutomatic Updater Force a reload of the server.
c4d99a62407cebca29653666ae11f87e4f56ebbcAutomatic Updater<dt><span class="term">SIGINT, SIGTERM</span></dt>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User Shut down the server.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The result of sending any other signals to the server is undefined.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The <span><strong class="command">named</strong></span> configuration file is too complex
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User to describe in detail here. A complete description is provided
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span><strong class="command">named</strong></span> inherits the <code class="function">umask</code>
d71e2e0c61df16ff37c9934c371a4a60c08974f7Mark Andrews (file creation mode mask) from the parent process. If files
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein created by <span><strong class="command">named</strong></span>, such as journal files,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein need to have custom permissions, the <code class="function">umask</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein should be set explicitly in the script used to start the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span><strong class="command">named</strong></span> process.
2a1d6afad5c725cbc796c10f1d2b9041eda9f077Automatic Updater<dt><span class="term"><code class="filename">/etc/named.conf</code></span></dt>
0e1dece22e128f9dfa723316a35c4b3f06912381Tinderbox User The default configuration file.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<dt><span class="term"><code class="filename">/var/run/named/named.pid</code></span></dt>
0e1dece22e128f9dfa723316a35c4b3f06912381Tinderbox User The default process-id file.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="citerefentry"><span class="refentrytitle">named-checkconf</span>(8)</span>,
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <span class="citerefentry"><span class="refentrytitle">named-checkzone</span>(8)</span>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="citerefentry"><span class="refentrytitle">lwresd</span>(8)</span>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="citerefentry"><span class="refentrytitle">named.conf</span>(5)</span>,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
d71e2e0c61df16ff37c9934c371a4a60c08974f7Mark Andrews<p><span class="corpauthor">Internet Systems Consortium</span>