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