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