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