contrib/bind9/bin/named/named.docbook

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   2                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
   3                [<!ENTITY mdash "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2004-2009, 2011, 2013  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000, 2001, 2003  Internet Software Consortium.
   7  -
   8  - Permission to use, copy, modify, and/or distribute this software for any
   9  - purpose with or without fee is hereby granted, provided that the above
  10  - copyright notice and this permission notice appear in all copies.
  11  -
  12  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  13  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  14  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  15  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  16  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  17  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  18  - PERFORMANCE OF THIS SOFTWARE.
  19 -->
  20
  21 <!-- $Id: named.docbook,v 1.28 2011/11/09 23:46:23 tbox Exp $ -->
  22 <refentry id="man.named">
  23   <refentryinfo>
  24     <date>May 21, 2009</date>
  25   </refentryinfo>
  26
  27   <refmeta>
  28     <refentrytitle><application>named</application></refentrytitle>
  29     <manvolnum>8</manvolnum>
  30     <refmiscinfo>BIND9</refmiscinfo>
  31   </refmeta>
  32
  33   <refnamediv>
  34     <refname><application>named</application></refname>
  35     <refpurpose>Internet domain name server</refpurpose>
  36   </refnamediv>
  37
  38   <docinfo>
  39     <copyright>
  40       <year>2004</year>
  41       <year>2005</year>
  42       <year>2006</year>
  43       <year>2007</year>
  44       <year>2008</year>
  45       <year>2009</year>
  46       <year>2011</year>
  47       <year>2013</year>
  48       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  49     </copyright>
  50     <copyright>
  51       <year>2000</year>
  52       <year>2001</year>
  53       <year>2003</year>
  54       <holder>Internet Software Consortium.</holder>
  55     </copyright>
  56   </docinfo>
  57
  58   <refsynopsisdiv>
  59     <cmdsynopsis>
  60       <command>named</command>
  61       <arg><option>-4</option></arg>
  62       <arg><option>-6</option></arg>
  63       <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
  64       <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>
  65       <arg><option>-E <replaceable class="parameter">engine-name</replaceable></option></arg>
  66       <arg><option>-f</option></arg>
  67       <arg><option>-g</option></arg>
  68       <arg><option>-m <replaceable class="parameter">flag</replaceable></option></arg>
  69       <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>
  70       <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
  71       <arg><option>-s</option></arg>
  72       <arg><option>-S <replaceable class="parameter">#max-socks</replaceable></option></arg>
  73       <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg>
  74       <arg><option>-U <replaceable class="parameter">#listeners</replaceable></option></arg>
  75       <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
  76       <arg><option>-v</option></arg>
  77       <arg><option>-V</option></arg>
  78       <arg><option>-x <replaceable class="parameter">cache-file</replaceable></option></arg>
  79     </cmdsynopsis>
  80   </refsynopsisdiv>
  81
  82   <refsect1>
  83     <title>DESCRIPTION</title>
  84     <para><command>named</command>
  85       is a Domain Name System (DNS) server,
  86       part of the BIND 9 distribution from ISC.  For more
  87       information on the DNS, see RFCs 1033, 1034, and 1035.
  88     </para>
  89     <para>
  90       When invoked without arguments, <command>named</command>
  91       will
  92       read the default configuration file
  93       <filename>/etc/named.conf</filename>, read any initial
  94       data, and listen for queries.
  95     </para>
  96   </refsect1>
  97
  98   <refsect1>
  99     <title>OPTIONS</title>
 100
 101     <variablelist>
 102       <varlistentry>
 103         <term>-4</term>
 104         <listitem>
 105           <para>
 106             Use IPv4 only even if the host machine is capable of IPv6.
 107             <option>-4</option> and <option>-6</option> are mutually
 108             exclusive.
 109           </para>
 110         </listitem>
 111       </varlistentry>
 112
 113       <varlistentry>
 114         <term>-6</term>
 115         <listitem>
 116           <para>
 117             Use IPv6 only even if the host machine is capable of IPv4.
 118             <option>-4</option> and <option>-6</option> are mutually
 119             exclusive.
 120           </para>
 121         </listitem>
 122       </varlistentry>
 123
 124       <varlistentry>
 125         <term>-c <replaceable class="parameter">config-file</replaceable></term>
 126         <listitem>
 127           <para>
 128             Use <replaceable class="parameter">config-file</replaceable> as the
 129             configuration file instead of the default,
 130             <filename>/etc/named.conf</filename>.  To
 131             ensure that reloading the configuration file continues
 132             to work after the server has changed its working
 133             directory due to to a possible
 134             <option>directory</option> option in the configuration
 135             file, <replaceable class="parameter">config-file</replaceable> should be
 136             an absolute pathname.
 137           </para>
 138         </listitem>
 139       </varlistentry>
 140
 141       <varlistentry>
 142         <term>-d <replaceable class="parameter">debug-level</replaceable></term>
 143         <listitem>
 144           <para>
 145             Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.
 146             Debugging traces from <command>named</command> become
 147             more verbose as the debug level increases.
 148           </para>
 149         </listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term>-E <replaceable class="parameter">engine-name</replaceable></term>
 154         <listitem>
 155           <para>
 156             Use a crypto hardware (OpenSSL engine) for the crypto operations
 157             it supports, for instance re-signing with private keys from
 158             a secure key store. When compiled with PKCS#11 support
 159             <replaceable class="parameter">engine-name</replaceable>
 160             defaults to pkcs11, the empty name resets it to no engine.
 161           </para>
 162         </listitem>
 163       </varlistentry>
 164
 165       <varlistentry>
 166         <term>-f</term>
 167         <listitem>
 168           <para>
 169             Run the server in the foreground (i.e. do not daemonize).
 170           </para>
 171         </listitem>
 172       </varlistentry>
 173
 174       <varlistentry>
 175         <term>-g</term>
 176         <listitem>
 177           <para>
 178             Run the server in the foreground and force all logging
 179             to <filename>stderr</filename>.
 180           </para>
 181         </listitem>
 182       </varlistentry>
 183
 184       <varlistentry>
 185         <term>-m <replaceable class="parameter">flag</replaceable></term>
 186         <listitem>
 187           <para>
 188             Turn on memory usage debugging flags.  Possible flags are
 189             <replaceable class="parameter">usage</replaceable>,
 190             <replaceable class="parameter">trace</replaceable>,
 191             <replaceable class="parameter">record</replaceable>,
 192             <replaceable class="parameter">size</replaceable>, and
 193             <replaceable class="parameter">mctx</replaceable>.
 194             These correspond to the ISC_MEM_DEBUGXXXX flags described in
 195             <filename>&lt;isc/mem.h&gt;</filename>.
 196           </para>
 197         </listitem>
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term>-n <replaceable class="parameter">#cpus</replaceable></term>
 202         <listitem>
 203           <para>
 204             Create <replaceable class="parameter">#cpus</replaceable> worker threads
 205             to take advantage of multiple CPUs.  If not specified,
 206             <command>named</command> will try to determine the
 207             number of CPUs present and create one thread per CPU.
 208             If it is unable to determine the number of CPUs, a
 209             single worker thread will be created.
 210           </para>
 211         </listitem>
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term>-p <replaceable class="parameter">port</replaceable></term>
 216         <listitem>
 217           <para>
 218             Listen for queries on port <replaceable class="parameter">port</replaceable>.  If not
 219             specified, the default is port 53.
 220           </para>
 221         </listitem>
 222       </varlistentry>
 223
 224       <varlistentry>
 225         <term>-s</term>
 226         <listitem>
 227           <para>
 228             Write memory usage statistics to <filename>stdout</filename> on exit.
 229           </para>
 230           <note>
 231             <para>
 232               This option is mainly of interest to BIND 9 developers
 233               and may be removed or changed in a future release.
 234             </para>
 235           </note>
 236         </listitem>
 237       </varlistentry>
 238
 239       <varlistentry>
 240         <term>-S <replaceable class="parameter">#max-socks</replaceable></term>
 241         <listitem>
 242           <para>
 243             Allow <command>named</command> to use up to
 244             <replaceable class="parameter">#max-socks</replaceable> sockets.
 245           </para>
 246           <warning>
 247             <para>
 248               This option should be unnecessary for the vast majority
 249               of users.
 250               The use of this option could even be harmful because the
 251               specified value may exceed the limitation of the
 252               underlying system API.
 253               It is therefore set only when the default configuration
 254               causes exhaustion of file descriptors and the
 255               operational environment is known to support the
 256               specified number of sockets.
 257               Note also that the actual maximum number is normally a little
 258               fewer than the specified value because
 259               <command>named</command> reserves some file descriptors
 260               for its internal use.
 261             </para>
 262           </warning>
 263         </listitem>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term>-t <replaceable class="parameter">directory</replaceable></term>
 268         <listitem>
 269           <para>Chroot
 270             to <replaceable class="parameter">directory</replaceable> after
 271             processing the command line arguments, but before
 272             reading the configuration file.
 273           </para>
 274           <warning>
 275             <para>
 276               This option should be used in conjunction with the
 277               <option>-u</option> option, as chrooting a process
 278               running as root doesn't enhance security on most
 279               systems; the way <function>chroot(2)</function> is
 280               defined allows a process with root privileges to
 281               escape a chroot jail.
 282             </para>
 283           </warning>
 284         </listitem>
 285       </varlistentry>
 286
 287       <varlistentry>
 288         <term>-U <replaceable class="parameter">#listeners</replaceable></term>
 289         <listitem>
 290           <para>
 291             Use <replaceable class="parameter">#listeners</replaceable>
 292             worker threads to listen for incoming UDP packets on each
 293             address.  If not specified, <command>named</command> will
 294             use the number of detected CPUs.  If <option>-n</option>
 295             has been set to a higher value than the number of CPUs,
 296             then <option>-U</option> may be increased as high as that
 297             value, but no higher.
 298           </para>
 299         </listitem>
 300       </varlistentry>
 301
 302       <varlistentry>
 303         <term>-u <replaceable class="parameter">user</replaceable></term>
 304         <listitem>
 305           <para>Setuid
 306             to <replaceable class="parameter">user</replaceable> after completing
 307             privileged operations, such as creating sockets that
 308             listen on privileged ports.
 309           </para>
 310           <note>
 311             <para>
 312               On Linux, <command>named</command> uses the kernel's
 313                         capability mechanism to drop all root privileges
 314               except the ability to <function>bind(2)</function> to
 315               a
 316               privileged port and set process resource limits.
 317               Unfortunately, this means that the <option>-u</option>
 318               option only works when <command>named</command> is
 319               run
 320               on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or
 321               later, since previous kernels did not allow privileges
 322               to be retained after <function>setuid(2)</function>.
 323             </para>
 324           </note>
 325         </listitem>
 326       </varlistentry>
 327
 328       <varlistentry>
 329         <term>-v</term>
 330         <listitem>
 331           <para>
 332             Report the version number and exit.
 333           </para>
 334         </listitem>
 335       </varlistentry>
 336
 337       <varlistentry>
 338         <term>-V</term>
 339         <listitem>
 340           <para>
 341             Report the version number and build options, and exit.
 342           </para>
 343         </listitem>
 344       </varlistentry>
 345
 346       <varlistentry>
 347         <term>-x <replaceable class="parameter">cache-file</replaceable></term>
 348         <listitem>
 349           <para>
 350             Load data from <replaceable class="parameter">cache-file</replaceable> into the
 351             cache of the default view.
 352           </para>
 353           <warning>
 354             <para>
 355               This option must not be used.  It is only of interest
 356               to BIND 9 developers and may be removed or changed in a
 357               future release.
 358             </para>
 359           </warning>
 360         </listitem>
 361       </varlistentry>
 362
 363     </variablelist>
 364
 365   </refsect1>
 366
 367   <refsect1>
 368     <title>SIGNALS</title>
 369     <para>
 370       In routine operation, signals should not be used to control
 371       the nameserver; <command>rndc</command> should be used
 372       instead.
 373     </para>
 374
 375     <variablelist>
 376
 377       <varlistentry>
 378         <term>SIGHUP</term>
 379         <listitem>
 380           <para>
 381             Force a reload of the server.
 382           </para>
 383         </listitem>
 384       </varlistentry>
 385
 386       <varlistentry>
 387         <term>SIGINT, SIGTERM</term>
 388         <listitem>
 389           <para>
 390             Shut down the server.
 391           </para>
 392         </listitem>
 393       </varlistentry>
 394
 395     </variablelist>
 396
 397     <para>
 398       The result of sending any other signals to the server is undefined.
 399     </para>
 400
 401   </refsect1>
 402
 403   <refsect1>
 404     <title>CONFIGURATION</title>
 405     <para>
 406       The <command>named</command> configuration file is too complex
 407       to describe in detail here.  A complete description is provided
 408       in the
 409       <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
 410     </para>
 411
 412     <para>
 413       <command>named</command> inherits the <function>umask</function>
 414       (file creation mode mask) from the parent process. If files
 415       created by <command>named</command>, such as journal files,
 416       need to have custom permissions, the <function>umask</function>
 417       should be set explicitly in the script used to start the
 418       <command>named</command> process.
 419     </para>
 420
 421   </refsect1>
 422
 423   <refsect1>
 424     <title>FILES</title>
 425
 426     <variablelist>
 427
 428       <varlistentry>
 429         <term><filename>/etc/named.conf</filename></term>
 430         <listitem>
 431           <para>
 432             The default configuration file.
 433           </para>
 434         </listitem>
 435       </varlistentry>
 436
 437       <varlistentry>
 438         <term><filename>/var/run/named/named.pid</filename></term>
 439         <listitem>
 440           <para>
 441             The default process-id file.
 442           </para>
 443         </listitem>
 444       </varlistentry>
 445
 446     </variablelist>
 447
 448   </refsect1>
 449
 450   <refsect1>
 451     <title>SEE ALSO</title>
 452     <para><citetitle>RFC 1033</citetitle>,
 453       <citetitle>RFC 1034</citetitle>,
 454       <citetitle>RFC 1035</citetitle>,
 455       <citerefentry>
 456         <refentrytitle>named-checkconf</refentrytitle>
 457         <manvolnum>8</manvolnum>
 458       </citerefentry>,
 459       <citerefentry>
 460         <refentrytitle>named-checkzone</refentrytitle>
 461         <manvolnum>8</manvolnum>
 462       </citerefentry>,
 463       <citerefentry>
 464         <refentrytitle>rndc</refentrytitle>
 465         <manvolnum>8</manvolnum>
 466       </citerefentry>,
 467       <citerefentry>
 468         <refentrytitle>lwresd</refentrytitle>
 469         <manvolnum>8</manvolnum>
 470       </citerefentry>,
 471       <citerefentry>
 472         <refentrytitle>named.conf</refentrytitle>
 473         <manvolnum>5</manvolnum>
 474       </citerefentry>,
 475       <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
 476     </para>
 477   </refsect1>
 478
 479   <refsect1>
 480     <title>AUTHOR</title>
 481     <para><corpauthor>Internet Systems Consortium</corpauthor>
 482     </para>
 483   </refsect1>
 484
 485 </refentry><!--
 486  - Local variables:
 487  - mode: sgml
 488  - End:
 489 -->