contrib/bind9/bin/named/lwresd.docbook

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