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