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