lwresd.docbook 12.6 KB
Newer Older
1 2
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3
	       [<!ENTITY mdash "&#8212;">]>
Bob Halley's avatar
Bob Halley committed
4
<!--
Automatic Updater's avatar
Automatic Updater committed
5
 - Copyright (C) 2004, 2005, 2007, 2008  Internet Systems Consortium, Inc. ("ISC")
Bob Halley's avatar
Bob Halley committed
6 7
 - Copyright (C) 2000, 2001  Internet Software Consortium.
 -
Automatic Updater's avatar
Automatic Updater committed
8
 - Permission to use, copy, modify, and/or distribute this software for any
9 10 11
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 -
Mark Andrews's avatar
Mark Andrews committed
12 13 14 15 16 17 18
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
Bob Halley's avatar
Bob Halley committed
19
-->
Mark Andrews's avatar
Mark Andrews committed
20

21
<!-- $Id: lwresd.docbook,v 1.18 2008/11/06 05:30:24 marka Exp $ -->
Bob Halley's avatar
Bob Halley committed
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
<refentry>
  <refentryinfo>
    <date>June 30, 2000</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle><application>lwresd</application></refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo>BIND9</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname><application>lwresd</application></refname>
    <refpurpose>lightweight resolver daemon</refpurpose>
  </refnamediv>

38 39 40
  <docinfo>
    <copyright>
      <year>2004</year>
Mark Andrews's avatar
Mark Andrews committed
41
      <year>2005</year>
Mark Andrews's avatar
Mark Andrews committed
42
      <year>2007</year>
Automatic Updater's avatar
Automatic Updater committed
43
      <year>2008</year>
44 45 46 47 48
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
    <copyright>
      <year>2000</year>
      <year>2001</year>
Mark Andrews's avatar
Mark Andrews committed
49
      <holder>Internet Software Consortium.</holder>
50 51 52
    </copyright>
  </docinfo>

Bob Halley's avatar
Bob Halley committed
53 54 55
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>lwresd</command>
56
      <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
Bob Halley's avatar
Bob Halley committed
57 58 59 60 61
      <arg><option>-C <replaceable class="parameter">config-file</replaceable></option></arg>
      <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>
      <arg><option>-f</option></arg>
      <arg><option>-g</option></arg>
      <arg><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg>
62
      <arg><option>-m <replaceable class="parameter">flag</replaceable></option></arg>
Bob Halley's avatar
Bob Halley committed
63 64 65 66 67 68 69
      <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>
      <arg><option>-P <replaceable class="parameter">port</replaceable></option></arg>
      <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
      <arg><option>-s</option></arg>
      <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg>
      <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
      <arg><option>-v</option></arg>
70 71
      <arg><option>-4</option></arg>
      <arg><option>-6</option></arg>
Bob Halley's avatar
Bob Halley committed
72 73 74 75 76
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
77 78 79 80 81 82 83

    <para><command>lwresd</command>
      is the daemon providing name lookup
      services to clients that use the BIND 9 lightweight resolver
      library.  It is essentially a stripped-down, caching-only name
      server that answers queries using the BIND 9 lightweight
      resolver protocol rather than the DNS protocol.
Bob Halley's avatar
Bob Halley committed
84
    </para>
85 86 87 88 89 90 91 92

    <para><command>lwresd</command> 
      listens for resolver queries on a
      UDP port on the IPv4 loopback interface, 127.0.0.1.  This
      means that <command>lwresd</command> can only be used by
      processes running on the local machine.  By default UDP port
      number 921 is used for lightweight resolver requests and
      responses.
Bob Halley's avatar
Bob Halley committed
93 94
    </para>
    <para>
95 96 97 98 99
      Incoming lightweight resolver requests are decoded by the
      server which then resolves them using the DNS protocol.  When
      the DNS lookup completes, <command>lwresd</command> encodes
      the answers in the lightweight resolver format and returns
      them to the client that made the request.
Bob Halley's avatar
Bob Halley committed
100 101
    </para>
    <para>
102 103 104 105 106 107 108 109
      If <filename>/etc/resolv.conf</filename> contains any
      <option>nameserver</option> entries, <command>lwresd</command>
      sends recursive DNS queries to those servers.  This is similar
      to the use of forwarders in a caching name server.  If no
      <option>nameserver</option> entries are present, or if
      forwarding fails, <command>lwresd</command> resolves the
      queries autonomously starting at the root name servers, using
      a built-in list of root server hints.
Bob Halley's avatar
Bob Halley committed
110 111 112 113 114 115 116
    </para>
  </refsect1>

  <refsect1>
    <title>OPTIONS</title>

    <variablelist>
117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148

      <varlistentry>
        <term>-4</term>
        <listitem>
          <para>
            Use IPv4 only even if the host machine is capable of IPv6.
            <option>-4</option> and <option>-6</option> are mutually
            exclusive.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-6</term>
        <listitem>
          <para>
            Use IPv6 only even if the host machine is capable of IPv4.
            <option>-4</option> and <option>-6</option> are mutually
            exclusive.
          </para>
        </listitem>
      </varlistentry>

      <!-- this is in source but not mentioned? does this matter? -->
      <varlistentry>
        <term>-c <replaceable class="parameter">config-file</replaceable></term>
        <listitem>
          <para>
            Use <replaceable class="parameter">config-file</replaceable> as the
            configuration file instead of the default,
            <filename>/etc/lwresd.conf</filename>.
	    <!-- Should this be an absolute path name? -->
149
	    <option>-c</option> can not be used with <option>-C</option>.
150 151 152 153
          </para>
        </listitem>
      </varlistentry>

Bob Halley's avatar
Bob Halley committed
154
      <varlistentry>
155 156 157 158 159 160
        <term>-C <replaceable class="parameter">config-file</replaceable></term>
        <listitem>
          <para>
            Use <replaceable class="parameter">config-file</replaceable> as the
            configuration file instead of the default,
            <filename>/etc/resolv.conf</filename>.
161
	    <option>-C</option> can not be used with <option>-c</option>.
Bob Halley's avatar
Bob Halley committed
162
          </para>
163
        </listitem>
Bob Halley's avatar
Bob Halley committed
164 165 166
      </varlistentry>

      <varlistentry>
167 168 169 170 171 172
        <term>-d <replaceable class="parameter">debug-level</replaceable></term>
        <listitem>
          <para>
            Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.
            Debugging traces from <command>lwresd</command> become
            		more verbose as the debug level increases.
Bob Halley's avatar
Bob Halley committed
173
          </para>
174
        </listitem>
Bob Halley's avatar
Bob Halley committed
175 176 177
      </varlistentry>

      <varlistentry>
178 179 180 181
        <term>-f</term>
        <listitem>
          <para>
            Run the server in the foreground (i.e. do not daemonize).
Bob Halley's avatar
Bob Halley committed
182
          </para>
183
        </listitem>
Bob Halley's avatar
Bob Halley committed
184 185 186
      </varlistentry>

      <varlistentry>
187 188 189 190 191
        <term>-g</term>
        <listitem>
          <para>
            Run the server in the foreground and force all logging
            to <filename>stderr</filename>.
Bob Halley's avatar
Bob Halley committed
192
          </para>
193
        </listitem>
Bob Halley's avatar
Bob Halley committed
194 195
      </varlistentry>

196 197 198 199 200 201
      <varlistentry>
        <term>-i <replaceable class="parameter">pid-file</replaceable></term>
        <listitem>
          <para>
            Use <replaceable class="parameter">pid-file</replaceable> as the
            PID file instead of the default,
202
            <filename>/var/run/lwresd/lwresd.pid</filename>.
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-m <replaceable class="parameter">flag</replaceable></term>
        <listitem>
          <para>
            Turn on memory usage debugging flags.  Possible flags are
            <replaceable class="parameter">usage</replaceable>,
            <replaceable class="parameter">trace</replaceable>,
            <replaceable class="parameter">record</replaceable>,
            <replaceable class="parameter">size</replaceable>, and
            <replaceable class="parameter">mctx</replaceable>.  
            These correspond to the ISC_MEM_DEBUGXXXX flags described in
            <filename>&lt;isc/mem.h&gt;</filename>.
          </para>
        </listitem>
      </varlistentry>

Bob Halley's avatar
Bob Halley committed
223
      <varlistentry>
224 225 226 227 228 229 230 231 232
        <term>-n <replaceable class="parameter">#cpus</replaceable></term>
        <listitem>
          <para>
            Create <replaceable class="parameter">#cpus</replaceable> worker threads
            to take advantage of multiple CPUs.  If not specified,
            <command>lwresd</command> will try to determine the
            number of CPUs present and create one thread per CPU.
            If it is unable to determine the number of CPUs, a
            single worker thread will be created.
Bob Halley's avatar
Bob Halley committed
233
          </para>
234
        </listitem>
Bob Halley's avatar
Bob Halley committed
235 236 237
      </varlistentry>

      <varlistentry>
238 239 240 241 242 243
        <term>-P <replaceable class="parameter">port</replaceable></term>
        <listitem>
          <para>
            Listen for lightweight resolver queries on port
            <replaceable class="parameter">port</replaceable>.  If
            		not specified, the default is port 921.
Bob Halley's avatar
Bob Halley committed
244
          </para>
245
        </listitem>
Bob Halley's avatar
Bob Halley committed
246 247 248
      </varlistentry>

      <varlistentry>
249 250 251 252 253 254 255 256
        <term>-p <replaceable class="parameter">port</replaceable></term>
        <listitem>
          <para>
            Send DNS lookups to port <replaceable class="parameter">port</replaceable>.  If not
            specified, the default is port 53.  This provides a
            way of testing the lightweight resolver daemon with a
            name server that listens for queries on a non-standard
            port number.
Bob Halley's avatar
Bob Halley committed
257
          </para>
258
        </listitem>
Bob Halley's avatar
Bob Halley committed
259 260 261
      </varlistentry>

      <varlistentry>
262 263 264 265 266
        <term>-s</term>
        <listitem>
          <para>
            Write memory usage statistics to <filename>stdout</filename>
            on exit.
Bob Halley's avatar
Bob Halley committed
267
          </para>
268 269 270 271 272 273 274
          <note>
            <para>
              This option is mainly of interest to BIND 9 developers
              and may be removed or changed in a future release.
            </para>
          </note>
        </listitem>
Bob Halley's avatar
Bob Halley committed
275 276 277
      </varlistentry>

      <varlistentry>
278 279
        <term>-t <replaceable class="parameter">directory</replaceable></term>
        <listitem>
280
          <para>Chroot
281 282 283
	    to <replaceable class="parameter">directory</replaceable> after
            processing the command line arguments, but before
            reading the configuration file.
Bob Halley's avatar
Bob Halley committed
284
          </para>
285 286 287 288 289
          <warning>
            <para>
              This option should be used in conjunction with the
              <option>-u</option> option, as chrooting a process
              running as root doesn't enhance security on most
290
              systems; the way <function>chroot(2)</function> is
291 292 293 294 295
              defined allows a process with root privileges to
              escape a chroot jail.
            </para>
          </warning>
        </listitem>
Bob Halley's avatar
Bob Halley committed
296 297 298
      </varlistentry>

      <varlistentry>
299 300
        <term>-u <replaceable class="parameter">user</replaceable></term>
        <listitem>
301
          <para>Setuid
302 303 304
	    to <replaceable class="parameter">user</replaceable> after completing
            privileged operations, such as creating sockets that
            listen on privileged ports.
Bob Halley's avatar
Bob Halley committed
305
          </para>
306
        </listitem>
Bob Halley's avatar
Bob Halley committed
307 308 309
      </varlistentry>

      <varlistentry>
310 311 312 313
        <term>-v</term>
        <listitem>
          <para>
            Report the version number and exit.
Bob Halley's avatar
Bob Halley committed
314
          </para>
315
        </listitem>
Bob Halley's avatar
Bob Halley committed
316 317 318 319 320 321 322 323 324 325 326 327
      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1>
    <title>FILES</title>

    <variablelist>

      <varlistentry>
328 329 330 331
        <term><filename>/etc/resolv.conf</filename></term>
        <listitem>
          <para>
            The default configuration file.
Bob Halley's avatar
Bob Halley committed
332
          </para>
333
        </listitem>
Bob Halley's avatar
Bob Halley committed
334 335 336
      </varlistentry>

      <varlistentry>
337 338 339 340
        <term><filename>/var/run/lwresd.pid</filename></term>
        <listitem>
          <para>
            The default process-id file.
Bob Halley's avatar
Bob Halley committed
341
          </para>
342
        </listitem>
Bob Halley's avatar
Bob Halley committed
343 344 345 346 347 348 349 350
      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
351 352 353 354 355 356 357 358 359
    <para><citerefentry>
        <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>.
Bob Halley's avatar
Bob Halley committed
360 361 362 363 364
    </para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>
365
    <para><corpauthor>Internet Systems Consortium</corpauthor>
Bob Halley's avatar
Bob Halley committed
366 367 368
    </para>
  </refsect1>

369
</refentry><!--
Bob Halley's avatar
Bob Halley committed
370 371 372 373
 - Local variables:
 - mode: sgml
 - End:
-->