named.html revision ea94d370123a5892f6c47a97f21d1b28d44bb168
59602f2a7c4e4809941583bed3e94cd26e628f1aTinderbox User - Copyright (C) 2004-2009, 2011 Internet Systems Consortium, Inc. ("ISC")
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
19558a04decde0e7261d489d92d04ad88104217bTinderbox User - Permission to use, copy, modify, and/or distribute this software for any
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrews - purpose with or without fee is hereby granted, provided that the above
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrews - copyright notice and this permission notice appear in all copies.
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox User - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
287a6a8f9040dc43560cd69cddf83bfc0f53b76fTinderbox User - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
8de3f14f1c300c3e1ed99084cc03485b42c92bf1Tinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
e5a6871cd0635ecdb2bf792316a2d8c53206f4b2Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
950d203b64f512b85fcc093ee1e9e3e531a1aea3Tinderbox User - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User - PERFORMANCE OF THIS SOFTWARE.
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupont<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupont<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
d5637bdbb931ff79fced3d4858d83212ea58ed15Tinderbox User<a name="man.named"></a><div class="titlepage"></div>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<p><span class="application">named</span> — Internet domain name server</p>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<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>#listeners</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>
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User<p><span><strong class="command">named</strong></span>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews is a Domain Name System (DNS) server,
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User part of the BIND 9 distribution from ISC. For more
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews information on the DNS, see RFCs 1033, 1034, and 1035.
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User When invoked without arguments, <span><strong class="command">named</strong></span>
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User read the default configuration file
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox User <code class="filename">/etc/named.conf</code>, read any initial
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt data, and listen for queries.
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User Use IPv4 only even if the host machine is capable of IPv6.
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrews <code class="option">-4</code> and <code class="option">-6</code> are mutually
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater Use IPv6 only even if the host machine is capable of IPv4.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <code class="option">-4</code> and <code class="option">-6</code> are mutually
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User<dt><span class="term">-c <em class="replaceable"><code>config-file</code></em></span></dt>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews Use <em class="replaceable"><code>config-file</code></em> as the
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater configuration file instead of the default,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <code class="filename">/etc/named.conf</code>. To
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews ensure that reloading the configuration file continues
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User to work after the server has changed its working
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews directory due to to a possible
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <code class="option">directory</code> option in the configuration
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews file, <em class="replaceable"><code>config-file</code></em> should be
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews an absolute pathname.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews<dt><span class="term">-d <em class="replaceable"><code>debug-level</code></em></span></dt>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews Set the daemon's debug level to <em class="replaceable"><code>debug-level</code></em>.
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User Debugging traces from <span><strong class="command">named</strong></span> become
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox User more verbose as the debug level increases.
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User<dt><span class="term">-E <em class="replaceable"><code>engine-name</code></em></span></dt>
294e9d4c34462d29a3e766c88f452b46aeb3702fTinderbox User Use a crypto hardware (OpenSSL engine) for the crypto operations
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt it supports, for instance re-signing with private keys from
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt a secure key store. When compiled with PKCS#11 support
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt <em class="replaceable"><code>engine-name</code></em>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews defaults to pkcs11, the empty name resets it to no engine.
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox User Run the server in the foreground (i.e. do not daemonize).
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews Run the server in the foreground and force all logging
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User<dt><span class="term">-m <em class="replaceable"><code>flag</code></em></span></dt>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews Turn on memory usage debugging flags. Possible flags are
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User <em class="replaceable"><code>usage</code></em>,
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <em class="replaceable"><code>trace</code></em>,
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User <em class="replaceable"><code>record</code></em>,
aef6cf0f147a5014d4891c9689b9f463399e16e7Tinderbox User <em class="replaceable"><code>size</code></em>, and
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <em class="replaceable"><code>mctx</code></em>.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User These correspond to the ISC_MEM_DEBUGXXXX flags described in
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <code class="filename"><isc/mem.h></code>.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews<dt><span class="term">-n <em class="replaceable"><code>#cpus</code></em></span></dt>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews Create <em class="replaceable"><code>#cpus</code></em> worker threads
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User to take advantage of multiple CPUs. If not specified,
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews <span><strong class="command">named</strong></span> will try to determine the
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews number of CPUs present and create one thread per CPU.
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User If it is unable to determine the number of CPUs, a
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews single worker thread will be created.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews Listen for queries on port <em class="replaceable"><code>port</code></em>. If not
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User specified, the default is port 53.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews Write memory usage statistics to <code class="filename">stdout</code> on exit.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews This option is mainly of interest to BIND 9 developers
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User and may be removed or changed in a future release.
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User<dt><span class="term">-S <em class="replaceable"><code>#max-socks</code></em></span></dt>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont Allow <span><strong class="command">named</strong></span> to use up to
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User <em class="replaceable"><code>#max-socks</code></em> sockets.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
5747235bf35e7398984fd6b4632743396895ea7aTinderbox User This option should be unnecessary for the vast majority
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews The use of this option could even be harmful because the
a03cb08d0c4f1ca5fbc121d2f02bdffa7eb52286Mark Andrews specified value may exceed the limitation of the
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrews underlying system API.
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews It is therefore set only when the default configuration
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews causes exhaustion of file descriptors and the
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User operational environment is known to support the
5747235bf35e7398984fd6b4632743396895ea7aTinderbox User specified number of sockets.
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews Note also that the actual maximum number is normally a little
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews fewer than the specified value because
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User <span><strong class="command">named</strong></span> reserves some file descriptors
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrews for its internal use.
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrews<dt><span class="term">-t <em class="replaceable"><code>directory</code></em></span></dt>
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User to <em class="replaceable"><code>directory</code></em> after
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User processing the command line arguments, but before
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater reading the configuration file.
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater This option should be used in conjunction with the
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <code class="option">-u</code> option, as chrooting a process
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews running as root doesn't enhance security on most
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User systems; the way <code class="function">chroot(2)</code> is
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews defined allows a process with root privileges to
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User escape a chroot jail.
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User<dt><span class="term">-U <em class="replaceable"><code>#listeners</code></em></span></dt>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User Use <em class="replaceable"><code>#listeners</code></em>
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater worker threads to listen for incoming UDP packets on each
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User address. If not specified, <span><strong class="command">named</strong></span> will
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews use all of the worker threads for this purpose; the
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User <code class="option">-U</code> option allows the number to be
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews decreased but not increased.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<dt><span class="term">-u <em class="replaceable"><code>user</code></em></span></dt>
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User to <em class="replaceable"><code>user</code></em> after completing
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews privileged operations, such as creating sockets that
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User listen on privileged ports.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews On Linux, <span><strong class="command">named</strong></span> uses the kernel's
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User capability mechanism to drop all root privileges
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater except the ability to <code class="function">bind(2)</code> to
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews privileged port and set process resource limits.
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User Unfortunately, this means that the <code class="option">-u</code>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews option only works when <span><strong class="command">named</strong></span> is
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User later, since previous kernels did not allow privileges
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews to be retained after <code class="function">setuid(2)</code>.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews Report the version number and exit.
ac2e2800b4ac9cbe4cb756d967f4583c611eb75eMark Andrews Report the version number and build options, and exit.
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User<dt><span class="term">-x <em class="replaceable"><code>cache-file</code></em></span></dt>
bac4435d473c9a0281507524f084480c34aa942aTinderbox User Load data from <em class="replaceable"><code>cache-file</code></em> into the
933799f3641f4f78445d015008bad0038900a82aTinderbox User cache of the default view.
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrews<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
8711e5c73ca872d59810760af0332194cbdd619bAutomatic Updater This option must not be used. It is only of interest
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater to BIND 9 developers and may be removed or changed in a
bac4435d473c9a0281507524f084480c34aa942aTinderbox User future release.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater In routine operation, signals should not be used to control
f525041ae26958385b697cf82a30f108577024b6Tinderbox User the nameserver; <span><strong class="command">rndc</strong></span> should be used
c218e22e3e6cbd409b61a14f1480b5ce5c70bfc1Tinderbox User Force a reload of the server.
933799f3641f4f78445d015008bad0038900a82aTinderbox User<dt><span class="term">SIGINT, SIGTERM</span></dt>
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater Shut down the server.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The result of sending any other signals to the server is undefined.
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupont The <span><strong class="command">named</strong></span> configuration file is too complex
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User to describe in detail here. A complete description is provided
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
5e82fe9a56d17bfbd120817d00d28c5952ab4ddcTinderbox User <span><strong class="command">named</strong></span> inherits the <code class="function">umask</code>
4cda4fd158d6ded5586bacea8c388445d99611eaAutomatic Updater (file creation mode mask) from the parent process. If files
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews created by <span><strong class="command">named</strong></span>, such as journal files,
f2f7a53ba0ba69cfe8c505eea16f71bad9d8d449Tinderbox User need to have custom permissions, the <code class="function">umask</code>
c26604a73c4ce907ef6392f38b3fac838b1873a9Tinderbox User should be set explicitly in the script used to start the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <span><strong class="command">named</strong></span> process.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<dt><span class="term"><code class="filename">/etc/named.conf</code></span></dt>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews The default configuration file.
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User<dt><span class="term"><code class="filename">/var/run/named/named.pid</code></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The default process-id file.
757ff043760e4743dda1a10e7d58349275934902Tinderbox User <span class="citerefentry"><span class="refentrytitle">named-checkconf</span>(8)</span>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="citerefentry"><span class="refentrytitle">named-checkzone</span>(8)</span>,
ae454ec746d1d4db8d04e107d4d25ff13158c37fMark Andrews <span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User <span class="citerefentry"><span class="refentrytitle">lwresd</span>(8)</span>,
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <span class="citerefentry"><span class="refentrytitle">named.conf</span>(5)</span>,
1bcc3273a80c256f11d9098a00ba2c041939e233Mark Andrews <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
bac4435d473c9a0281507524f084480c34aa942aTinderbox User<p><span class="corpauthor">Internet Systems Consortium</span>