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 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.5 2007/01/29 23:57:20 marka 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>-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
  73     <para><command>lwresd</command>
  74       is the daemon providing name lookup
  75       services to clients that use the BIND 9 lightweight resolver
  76       library.  It is essentially a stripped-down, caching-only name
  77       server that answers queries using the BIND 9 lightweight
  78       resolver protocol rather than the DNS protocol.
  79     </para>
  80
  81     <para><command>lwresd</command>
  82       listens for resolver queries on a
  83       UDP port on the IPv4 loopback interface, 127.0.0.1.  This
  84       means that <command>lwresd</command> can only be used by
  85       processes running on the local machine.  By default UDP port
  86       number 921 is used for lightweight resolver requests and
  87       responses.
  88     </para>
  89     <para>
  90       Incoming lightweight resolver requests are decoded by the
  91       server which then resolves them using the DNS protocol.  When
  92       the DNS lookup completes, <command>lwresd</command> encodes
  93       the answers in the lightweight resolver format and returns
  94       them to the client that made the request.
  95     </para>
  96     <para>
  97       If <filename>/etc/resolv.conf</filename> contains any
  98       <option>nameserver</option> entries, <command>lwresd</command>
  99       sends recursive DNS queries to those servers.  This is similar
 100       to the use of forwarders in a caching name server.  If no
 101       <option>nameserver</option> entries are present, or if
 102       forwarding fails, <command>lwresd</command> resolves the
 103       queries autonomously starting at the root name servers, using
 104       a built-in list of root server hints.
 105     </para>
 106   </refsect1>
 107
 108   <refsect1>
 109     <title>OPTIONS</title>
 110
 111     <variablelist>
 112       <varlistentry>
 113         <term>-C <replaceable class="parameter">config-file</replaceable></term>
 114         <listitem>
 115           <para>
 116             Use <replaceable class="parameter">config-file</replaceable> as the
 117             configuration file instead of the default,
 118             <filename>/etc/resolv.conf</filename>.
 119           </para>
 120         </listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term>-d <replaceable class="parameter">debug-level</replaceable></term>
 125         <listitem>
 126           <para>
 127             Set the daemon's debug level to <replaceable 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 class="parameter">#cpus</replaceable> worker threads
 158             to take advantage of multiple CPUs.  If not specified,
 159             <command>lwresd</command> will try to determine the
 160             number of CPUs present and create one thread per CPU.
 161             If it is unable to determine the number of CPUs, a
 162             single worker thread will be created.
 163           </para>
 164         </listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term>-P <replaceable class="parameter">port</replaceable></term>
 169         <listitem>
 170           <para>
 171             Listen for lightweight resolver queries on port
 172             <replaceable class="parameter">port</replaceable>.  If
 173                         not specified, the default is port 921.
 174           </para>
 175         </listitem>
 176       </varlistentry>
 177
 178       <varlistentry>
 179         <term>-p <replaceable class="parameter">port</replaceable></term>
 180         <listitem>
 181           <para>
 182             Send DNS lookups to port <replaceable class="parameter">port</replaceable>.  If not
 183             specified, the default is port 53.  This provides a
 184             way of testing the lightweight resolver daemon with a
 185             name server that listens for queries on a non-standard
 186             port number.
 187           </para>
 188         </listitem>
 189       </varlistentry>
 190
 191       <varlistentry>
 192         <term>-s</term>
 193         <listitem>
 194           <para>
 195             Write memory usage statistics to <filename>stdout</filename>
 196             on exit.
 197           </para>
 198           <note>
 199             <para>
 200               This option is mainly of interest to BIND 9 developers
 201               and may be removed or changed in a future release.
 202             </para>
 203           </note>
 204         </listitem>
 205       </varlistentry>
 206
 207       <varlistentry>
 208         <term>-t <replaceable class="parameter">directory</replaceable></term>
 209         <listitem>
 210           <para><function>chroot()</function>
 211             to <replaceable class="parameter">directory</replaceable> after
 212             processing the command line arguments, but before
 213             reading the configuration file.
 214           </para>
 215           <warning>
 216             <para>
 217               This option should be used in conjunction with the
 218               <option>-u</option> option, as chrooting a process
 219               running as root doesn't enhance security on most
 220               systems; the way <function>chroot()</function> is
 221               defined allows a process with root privileges to
 222               escape a chroot jail.
 223             </para>
 224           </warning>
 225         </listitem>
 226       </varlistentry>
 227
 228       <varlistentry>
 229         <term>-u <replaceable class="parameter">user</replaceable></term>
 230         <listitem>
 231           <para><function>setuid()</function>
 232             to <replaceable class="parameter">user</replaceable> after completing
 233             privileged operations, such as creating sockets that
 234             listen on privileged ports.
 235           </para>
 236         </listitem>
 237       </varlistentry>
 238
 239       <varlistentry>
 240         <term>-v</term>
 241         <listitem>
 242           <para>
 243             Report the version number and exit.
 244           </para>
 245         </listitem>
 246       </varlistentry>
 247
 248     </variablelist>
 249
 250   </refsect1>
 251
 252   <refsect1>
 253     <title>FILES</title>
 254
 255     <variablelist>
 256
 257       <varlistentry>
 258         <term><filename>/etc/resolv.conf</filename></term>
 259         <listitem>
 260           <para>
 261             The default configuration file.
 262           </para>
 263         </listitem>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term><filename>/var/run/lwresd.pid</filename></term>
 268         <listitem>
 269           <para>
 270             The default process-id file.
 271           </para>
 272         </listitem>
 273       </varlistentry>
 274
 275     </variablelist>
 276
 277   </refsect1>
 278
 279   <refsect1>
 280     <title>SEE ALSO</title>
 281     <para><citerefentry>
 282         <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
 283       </citerefentry>,
 284       <citerefentry>
 285         <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
 286       </citerefentry>,
 287       <citerefentry>
 288         <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
 289       </citerefentry>.
 290     </para>
 291   </refsect1>
 292
 293   <refsect1>
 294     <title>AUTHOR</title>
 295     <para><corpauthor>Internet Systems Consortium</corpauthor>
 296     </para>
 297   </refsect1>
 298
 299 </refentry><!--
 300  - Local variables:
 301  - mode: sgml
 302  - End:
 303 -->