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