contrib/bind9/bin/named/lwresd.docbook

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
   2 <!--
   3  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   4  - Copyright (C) 2000, 2001  Internet Software Consortium.
   5  -
   6  - Permission to use, copy, modify, and distribute this software for any
   7  - purpose with or without fee is hereby granted, provided that the above
   8  - copyright notice and this permission notice appear in all copies.
   9  -
  10  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  11  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  12  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  13  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  14  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  15  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  16  - PERFORMANCE OF THIS SOFTWARE.
  17 -->
  18
  19 <!-- $Id: lwresd.docbook,v 1.6.208.2 2004/06/03 02:24:57 marka Exp $ -->
  20
  21 <refentry>
  22   <refentryinfo>
  23     <date>June 30, 2000</date>
  24   </refentryinfo>
  25
  26   <refmeta>
  27     <refentrytitle><application>lwresd</application></refentrytitle>
  28     <manvolnum>8</manvolnum>
  29     <refmiscinfo>BIND9</refmiscinfo>
  30   </refmeta>
  31
  32   <refnamediv>
  33     <refname><application>lwresd</application></refname>
  34     <refpurpose>lightweight resolver daemon</refpurpose>
  35   </refnamediv>
  36
  37   <refsynopsisdiv>
  38     <cmdsynopsis>
  39       <command>lwresd</command>
  40       <arg><option>-C <replaceable class="parameter">config-file</replaceable></option></arg>
  41       <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>
  42       <arg><option>-f</option></arg>
  43       <arg><option>-g</option></arg>
  44       <arg><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg>
  45       <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>
  46       <arg><option>-P <replaceable class="parameter">port</replaceable></option></arg>
  47       <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
  48       <arg><option>-s</option></arg>
  49       <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg>
  50       <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
  51       <arg><option>-v</option></arg>
  52     </cmdsynopsis>
  53   </refsynopsisdiv>
  54
  55   <refsect1>
  56     <title>DESCRIPTION</title>
  57     <para>
  58         <command>lwresd</command> is the daemon providing name lookup
  59         services to clients that use the BIND 9 lightweight resolver
  60         library.  It is essentially a stripped-down, caching-only name
  61         server that answers queries using the BIND 9 lightweight
  62         resolver protocol rather than the DNS protocol.
  63     </para>
  64     <para>
  65         <command>lwresd</command> listens for resolver queries on a
  66         UDP port on the IPv4 loopback interface, 127.0.0.1.  This
  67         means that <command>lwresd</command> can only be used by
  68         processes running on the local machine.  By default UDP port
  69         number 921 is used for lightweight resolver requests and
  70         responses.
  71     </para>
  72     <para>
  73         Incoming lightweight resolver requests are decoded by the
  74         server which then resolves them using the DNS protocol.  When
  75         the DNS lookup completes, <command>lwresd</command> encodes
  76         the answers in the lightweight resolver format and returns
  77         them to the client that made the request.
  78     </para>
  79     <para>
  80         If <filename>/etc/resolv.conf</filename> contains any
  81         <option>nameserver</option> entries, <command>lwresd</command>
  82         sends recursive DNS queries to those servers.  This is similar
  83         to the use of forwarders in a caching name server.  If no
  84         <option>nameserver</option> entries are present, or if
  85         forwarding fails, <command>lwresd</command> resolves the
  86         queries autonomously starting at the root name servers, using
  87         a built-in list of root server hints.
  88     </para>
  89   </refsect1>
  90
  91   <refsect1>
  92     <title>OPTIONS</title>
  93
  94     <variablelist>
  95       <varlistentry>
  96         <term>-C <replaceable class="parameter">config-file</replaceable></term>
  97         <listitem>
  98           <para>
  99                 Use <replaceable
 100                 class="parameter">config-file</replaceable> as the
 101                 configuration file instead of the default,
 102                 <filename>/etc/resolv.conf</filename>.
 103           </para>
 104         </listitem>
 105       </varlistentry>
 106
 107       <varlistentry>
 108         <term>-d <replaceable class="parameter">debug-level</replaceable></term>
 109         <listitem>
 110           <para>
 111                 Set the daemon's debug level to <replaceable
 112                 class="parameter">debug-level</replaceable>.
 113                 Debugging traces from <command>lwresd</command> become
 114                 more verbose as the debug level increases.
 115           </para>
 116         </listitem>
 117       </varlistentry>
 118
 119       <varlistentry>
 120         <term>-f</term>
 121         <listitem>
 122           <para>
 123                 Run the server in the foreground (i.e. do not daemonize).
 124           </para>
 125         </listitem>
 126       </varlistentry>
 127
 128       <varlistentry>
 129         <term>-g</term>
 130         <listitem>
 131           <para>
 132                 Run the server in the foreground and force all logging
 133                 to <filename>stderr</filename>.
 134           </para>
 135         </listitem>
 136       </varlistentry>
 137
 138       <varlistentry>
 139         <term>-n <replaceable class="parameter">#cpus</replaceable></term>
 140         <listitem>
 141           <para>
 142                 Create <replaceable
 143                 class="parameter">#cpus</replaceable> worker threads
 144                 to take advantage of multiple CPUs.  If not specified,
 145                 <command>lwresd</command> will try to determine the
 146                 number of CPUs present and create one thread per CPU.
 147                 If it is unable to determine the number of CPUs, a
 148                 single worker thread will be created.
 149           </para>
 150         </listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term>-P <replaceable class="parameter">port</replaceable></term>
 155         <listitem>
 156           <para>
 157                 Listen for lightweight resolver queries on port
 158                 <replaceable class="parameter">port</replaceable>.  If
 159                 not specified, the default is port 921.
 160           </para>
 161         </listitem>
 162       </varlistentry>
 163
 164       <varlistentry>
 165         <term>-p <replaceable class="parameter">port</replaceable></term>
 166         <listitem>
 167           <para>
 168                 Send DNS lookups to port <replaceable
 169                 class="parameter">port</replaceable>.  If not
 170                 specified, the default is port 53.  This provides a
 171                 way of testing the lightweight resolver daemon with a
 172                 name server that listens for queries on a non-standard
 173                 port number.
 174           </para>
 175         </listitem>
 176       </varlistentry>
 177
 178       <varlistentry>
 179         <term>-s</term>
 180         <listitem>
 181           <para>
 182                 Write memory usage statistics to <filename>stdout</filename>
 183                 on exit.
 184           </para>
 185           <note>
 186             <para>
 187                 This option is mainly of interest to BIND 9 developers
 188                 and may be removed or changed in a future release.
 189             </para>
 190           </note>
 191         </listitem>
 192       </varlistentry>
 193
 194       <varlistentry>
 195         <term>-t <replaceable class="parameter">directory</replaceable></term>
 196         <listitem>
 197           <para>
 198                 <function>chroot()</function> to <replaceable
 199                 class="parameter">directory</replaceable> after
 200                 processing the command line arguments, but before
 201                 reading the configuration file.
 202           </para>
 203           <warning>
 204             <para>
 205                 This option should be used in conjunction with the
 206                 <option>-u</option> option, as chrooting a process
 207                 running as root doesn't enhance security on most
 208                 systems; the way <function>chroot()</function> is
 209                 defined allows a process with root privileges to
 210                 escape a chroot jail.
 211             </para>
 212           </warning>
 213         </listitem>
 214       </varlistentry>
 215
 216       <varlistentry>
 217         <term>-u <replaceable class="parameter">user</replaceable></term>
 218         <listitem>
 219           <para>
 220                 <function>setuid()</function> to <replaceable
 221                 class="parameter">user</replaceable> after completing
 222                 privileged operations, such as creating sockets that
 223                 listen on privileged ports.
 224           </para>
 225         </listitem>
 226       </varlistentry>
 227
 228       <varlistentry>
 229         <term>-v</term>
 230         <listitem>
 231           <para>
 232                 Report the version number and exit.
 233           </para>
 234         </listitem>
 235       </varlistentry>
 236
 237     </variablelist>
 238
 239   </refsect1>
 240
 241   <refsect1>
 242     <title>FILES</title>
 243
 244     <variablelist>
 245
 246       <varlistentry>
 247         <term><filename>/etc/resolv.conf</filename></term>
 248         <listitem>
 249           <para>
 250                 The default configuration file.
 251           </para>
 252         </listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><filename>/var/run/lwresd.pid</filename></term>
 257         <listitem>
 258           <para>
 259                 The default process-id file.
 260           </para>
 261         </listitem>
 262       </varlistentry>
 263
 264     </variablelist>
 265
 266   </refsect1>
 267
 268   <refsect1>
 269     <title>SEE ALSO</title>
 270     <para>
 271         <citerefentry>
 272           <refentrytitle>named</refentrytitle>
 273           <manvolnum>8</manvolnum>
 274         </citerefentry>,
 275         <citerefentry>
 276           <refentrytitle>lwres</refentrytitle>
 277           <manvolnum>3</manvolnum>
 278         </citerefentry>,
 279         <citerefentry>
 280           <refentrytitle>resolver</refentrytitle>
 281           <manvolnum>5</manvolnum>
 282         </citerefentry>.
 283     </para>
 284   </refsect1>
 285
 286   <refsect1>
 287     <title>AUTHOR</title>
 288     <para>
 289         <corpauthor>Internet Systems Consortium</corpauthor>
 290     </para>
 291   </refsect1>
 292
 293 </refentry>
 294
 295
 296 <!--
 297  - Local variables:
 298  - mode: sgml
 299  - End:
 300 -->