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