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