contrib/bind9/bin/named/lwresd.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, 2005, 2007  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000, 2001  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: lwresd.docbook,v 1.7.18.8 2007/08/28 07:20:01 tbox Exp $ -->
  22 <refentry>
  23   <refentryinfo>
  24     <date>June 30, 2000</date>
  25   </refentryinfo>
  26
  27   <refmeta>
  28     <refentrytitle><application>lwresd</application></refentrytitle>
  29     <manvolnum>8</manvolnum>
  30     <refmiscinfo>BIND9</refmiscinfo>
  31   </refmeta>
  32
  33   <refnamediv>
  34     <refname><application>lwresd</application></refname>
  35     <refpurpose>lightweight resolver daemon</refpurpose>
  36   </refnamediv>
  37
  38   <docinfo>
  39     <copyright>
  40       <year>2004</year>
  41       <year>2005</year>
  42       <year>2007</year>
  43       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  44     </copyright>
  45     <copyright>
  46       <year>2000</year>
  47       <year>2001</year>
  48       <holder>Internet Software Consortium.</holder>
  49     </copyright>
  50   </docinfo>
  51
  52   <refsynopsisdiv>
  53     <cmdsynopsis>
  54       <command>lwresd</command>
  55       <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
  56       <arg><option>-C <replaceable class="parameter">config-file</replaceable></option></arg>
  57       <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>
  58       <arg><option>-f</option></arg>
  59       <arg><option>-g</option></arg>
  60       <arg><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg>
  61       <arg><option>-m <replaceable class="parameter">flag</replaceable></option></arg>
  62       <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>
  63       <arg><option>-P <replaceable class="parameter">port</replaceable></option></arg>
  64       <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
  65       <arg><option>-s</option></arg>
  66       <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg>
  67       <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
  68       <arg><option>-v</option></arg>
  69       <arg><option>-4</option></arg>
  70       <arg><option>-6</option></arg>
  71     </cmdsynopsis>
  72   </refsynopsisdiv>
  73
  74   <refsect1>
  75     <title>DESCRIPTION</title>
  76
  77     <para><command>lwresd</command>
  78       is the daemon providing name lookup
  79       services to clients that use the BIND 9 lightweight resolver
  80       library.  It is essentially a stripped-down, caching-only name
  81       server that answers queries using the BIND 9 lightweight
  82       resolver protocol rather than the DNS protocol.
  83     </para>
  84
  85     <para><command>lwresd</command>
  86       listens for resolver queries on a
  87       UDP port on the IPv4 loopback interface, 127.0.0.1.  This
  88       means that <command>lwresd</command> can only be used by
  89       processes running on the local machine.  By default UDP port
  90       number 921 is used for lightweight resolver requests and
  91       responses.
  92     </para>
  93     <para>
  94       Incoming lightweight resolver requests are decoded by the
  95       server which then resolves them using the DNS protocol.  When
  96       the DNS lookup completes, <command>lwresd</command> encodes
  97       the answers in the lightweight resolver format and returns
  98       them to the client that made the request.
  99     </para>
 100     <para>
 101       If <filename>/etc/resolv.conf</filename> contains any
 102       <option>nameserver</option> entries, <command>lwresd</command>
 103       sends recursive DNS queries to those servers.  This is similar
 104       to the use of forwarders in a caching name server.  If no
 105       <option>nameserver</option> entries are present, or if
 106       forwarding fails, <command>lwresd</command> resolves the
 107       queries autonomously starting at the root name servers, using
 108       a built-in list of root server hints.
 109     </para>
 110   </refsect1>
 111
 112   <refsect1>
 113     <title>OPTIONS</title>
 114
 115     <variablelist>
 116
 117       <varlistentry>
 118         <term>-4</term>
 119         <listitem>
 120           <para>
 121             Use IPv4 only even if the host machine is capable of IPv6.
 122             <option>-4</option> and <option>-6</option> are mutually
 123             exclusive.
 124           </para>
 125         </listitem>
 126       </varlistentry>
 127
 128       <varlistentry>
 129         <term>-6</term>
 130         <listitem>
 131           <para>
 132             Use IPv6 only even if the host machine is capable of IPv4.
 133             <option>-4</option> and <option>-6</option> are mutually
 134             exclusive.
 135           </para>
 136         </listitem>
 137       </varlistentry>
 138
 139       <!-- this is in source but not mentioned? does this matter? -->
 140       <varlistentry>
 141         <term>-c <replaceable class="parameter">config-file</replaceable></term>
 142         <listitem>
 143           <para>
 144             Use <replaceable class="parameter">config-file</replaceable> as the
 145             configuration file instead of the default,
 146             <filename>/etc/lwresd.conf</filename>.
 147             <!-- Should this be an absolute path name? -->
 148             <term>-c</term> can not be used with <term>-C</term>.
 149           </para>
 150         </listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term>-C <replaceable class="parameter">config-file</replaceable></term>
 155         <listitem>
 156           <para>
 157             Use <replaceable class="parameter">config-file</replaceable> as the
 158             configuration file instead of the default,
 159             <filename>/etc/resolv.conf</filename>.
 160             <term>-C</term> can not be used with <term>-c</term>.
 161           </para>
 162         </listitem>
 163       </varlistentry>
 164
 165       <varlistentry>
 166         <term>-d <replaceable class="parameter">debug-level</replaceable></term>
 167         <listitem>
 168           <para>
 169             Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.
 170             Debugging traces from <command>lwresd</command> become
 171                         more verbose as the debug level increases.
 172           </para>
 173         </listitem>
 174       </varlistentry>
 175
 176       <varlistentry>
 177         <term>-f</term>
 178         <listitem>
 179           <para>
 180             Run the server in the foreground (i.e. do not daemonize).
 181           </para>
 182         </listitem>
 183       </varlistentry>
 184
 185       <varlistentry>
 186         <term>-g</term>
 187         <listitem>
 188           <para>
 189             Run the server in the foreground and force all logging
 190             to <filename>stderr</filename>.
 191           </para>
 192         </listitem>
 193       </varlistentry>
 194
 195       <varlistentry>
 196         <term>-i <replaceable class="parameter">pid-file</replaceable></term>
 197         <listitem>
 198           <para>
 199             Use <replaceable class="parameter">pid-file</replaceable> as the
 200             PID file instead of the default,
 201             <filename>/var/run/lwresd.pid</filename>.
 202           </para>
 203         </listitem>
 204       </varlistentry>
 205
 206       <varlistentry>
 207         <term>-m <replaceable class="parameter">flag</replaceable></term>
 208         <listitem>
 209           <para>
 210             Turn on memory usage debugging flags.  Possible flags are
 211             <replaceable class="parameter">usage</replaceable>,
 212             <replaceable class="parameter">trace</replaceable>,
 213             <replaceable class="parameter">record</replaceable>,
 214             <replaceable class="parameter">size</replaceable>, and
 215             <replaceable class="parameter">mctx</replaceable>.
 216             These correspond to the ISC_MEM_DEBUGXXXX flags described in
 217             <filename>&lt;isc/mem.h&gt;</filename>.
 218           </para>
 219         </listitem>
 220       </varlistentry>
 221
 222       <varlistentry>
 223         <term>-n <replaceable class="parameter">#cpus</replaceable></term>
 224         <listitem>
 225           <para>
 226             Create <replaceable class="parameter">#cpus</replaceable> worker threads
 227             to take advantage of multiple CPUs.  If not specified,
 228             <command>lwresd</command> will try to determine the
 229             number of CPUs present and create one thread per CPU.
 230             If it is unable to determine the number of CPUs, a
 231             single worker thread will be created.
 232           </para>
 233         </listitem>
 234       </varlistentry>
 235
 236       <varlistentry>
 237         <term>-P <replaceable class="parameter">port</replaceable></term>
 238         <listitem>
 239           <para>
 240             Listen for lightweight resolver queries on port
 241             <replaceable class="parameter">port</replaceable>.  If
 242                         not specified, the default is port 921.
 243           </para>
 244         </listitem>
 245       </varlistentry>
 246
 247       <varlistentry>
 248         <term>-p <replaceable class="parameter">port</replaceable></term>
 249         <listitem>
 250           <para>
 251             Send DNS lookups to port <replaceable class="parameter">port</replaceable>.  If not
 252             specified, the default is port 53.  This provides a
 253             way of testing the lightweight resolver daemon with a
 254             name server that listens for queries on a non-standard
 255             port number.
 256           </para>
 257         </listitem>
 258       </varlistentry>
 259
 260       <varlistentry>
 261         <term>-s</term>
 262         <listitem>
 263           <para>
 264             Write memory usage statistics to <filename>stdout</filename>
 265             on exit.
 266           </para>
 267           <note>
 268             <para>
 269               This option is mainly of interest to BIND 9 developers
 270               and may be removed or changed in a future release.
 271             </para>
 272           </note>
 273         </listitem>
 274       </varlistentry>
 275
 276       <varlistentry>
 277         <term>-t <replaceable class="parameter">directory</replaceable></term>
 278         <listitem>
 279           <para>Chroot
 280             to <replaceable class="parameter">directory</replaceable> after
 281             processing the command line arguments, but before
 282             reading the configuration file.
 283           </para>
 284           <warning>
 285             <para>
 286               This option should be used in conjunction with the
 287               <option>-u</option> option, as chrooting a process
 288               running as root doesn't enhance security on most
 289               systems; the way <function>chroot(2)</function> is
 290               defined allows a process with root privileges to
 291               escape a chroot jail.
 292             </para>
 293           </warning>
 294         </listitem>
 295       </varlistentry>
 296
 297       <varlistentry>
 298         <term>-u <replaceable class="parameter">user</replaceable></term>
 299         <listitem>
 300           <para>Setuid
 301             to <replaceable class="parameter">user</replaceable> after completing
 302             privileged operations, such as creating sockets that
 303             listen on privileged ports.
 304           </para>
 305         </listitem>
 306       </varlistentry>
 307
 308       <varlistentry>
 309         <term>-v</term>
 310         <listitem>
 311           <para>
 312             Report the version number and exit.
 313           </para>
 314         </listitem>
 315       </varlistentry>
 316
 317     </variablelist>
 318
 319   </refsect1>
 320
 321   <refsect1>
 322     <title>FILES</title>
 323
 324     <variablelist>
 325
 326       <varlistentry>
 327         <term><filename>/etc/resolv.conf</filename></term>
 328         <listitem>
 329           <para>
 330             The default configuration file.
 331           </para>
 332         </listitem>
 333       </varlistentry>
 334
 335       <varlistentry>
 336         <term><filename>/var/run/lwresd.pid</filename></term>
 337         <listitem>
 338           <para>
 339             The default process-id file.
 340           </para>
 341         </listitem>
 342       </varlistentry>
 343
 344     </variablelist>
 345
 346   </refsect1>
 347
 348   <refsect1>
 349     <title>SEE ALSO</title>
 350     <para><citerefentry>
 351         <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
 352       </citerefentry>,
 353       <citerefentry>
 354         <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
 355       </citerefentry>,
 356       <citerefentry>
 357         <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
 358       </citerefentry>.
 359     </para>
 360   </refsect1>
 361
 362   <refsect1>
 363     <title>AUTHOR</title>
 364     <para><corpauthor>Internet Systems Consortium</corpauthor>
 365     </para>
 366   </refsect1>
 367
 368 </refentry><!--
 369  - Local variables:
 370  - mode: sgml
 371  - End:
 372 -->