lwresd.docbook revision f9f11eb54be19b7deedf3978496f71d81432a5ee
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
fdd80e9a55c70b36a3bf3e409b86897301c44ff8Automatic Updater "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont [<!ENTITY mdash "—">]>
4a14ce5ba00ab7bc55c99ffdcf59c7a4ab902721Automatic Updater - Copyright (C) 2004, 2005, 2007, 2008 Internet Systems Consortium, Inc. ("ISC")
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont - Copyright (C) 2000, 2001 Internet Software Consortium.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont - Permission to use, copy, modify, and/or distribute this software for any
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont - purpose with or without fee is hereby granted, provided that the above
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont - copyright notice and this permission notice appear in all copies.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
0e9e255d1643375056aa9ed7fe2a279713ffae78Automatic Updater - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont - PERFORMANCE OF THIS SOFTWARE.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont<!-- $Id: lwresd.docbook,v 1.19 2009/01/20 20:06:29 jreed Exp $ -->
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <refentryinfo>
922312472e2e05ebc64993d465999c5351b83036Automatic Updater </refentryinfo>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <refentrytitle><application>lwresd</application></refentrytitle>
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews <refname><application>lwresd</application></refname>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <refpurpose>lightweight resolver daemon</refpurpose>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont </refnamediv>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <holder>Internet Software Consortium.</holder>
0e9e255d1643375056aa9ed7fe2a279713ffae78Automatic Updater <refsynopsisdiv>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <cmdsynopsis>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater <arg><option>-C <replaceable class="parameter">config-file</replaceable></option></arg>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <arg><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <arg><option>-m <replaceable class="parameter">flag</replaceable></option></arg>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <arg><option>-P <replaceable class="parameter">port</replaceable></option></arg>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
8e821eea5f57ac47a94305aa7ab0c3570d92a311Automatic Updater </cmdsynopsis>
0e9e255d1643375056aa9ed7fe2a279713ffae78Automatic Updater </refsynopsisdiv>
8e821eea5f57ac47a94305aa7ab0c3570d92a311Automatic Updater is the daemon providing name lookup
8e821eea5f57ac47a94305aa7ab0c3570d92a311Automatic Updater services to clients that use the BIND 9 lightweight resolver
8e821eea5f57ac47a94305aa7ab0c3570d92a311Automatic Updater library. It is essentially a stripped-down, caching-only name
2a6d4c9948b3f4f31311bd799d114585a30419a9Automatic Updater server that answers queries using the BIND 9 lightweight
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont resolver protocol rather than the DNS protocol.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont listens for resolver queries on a
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont UDP port on the IPv4 loopback interface, 127.0.0.1. This
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont means that <command>lwresd</command> can only be used by
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont processes running on the local machine. By default, UDP port
2a6d4c9948b3f4f31311bd799d114585a30419a9Automatic Updater number 921 is used for lightweight resolver requests and
2a6d4c9948b3f4f31311bd799d114585a30419a9Automatic Updater Incoming lightweight resolver requests are decoded by the
2a6d4c9948b3f4f31311bd799d114585a30419a9Automatic Updater server which then resolves them using the DNS protocol. When
2a6d4c9948b3f4f31311bd799d114585a30419a9Automatic Updater the DNS lookup completes, <command>lwresd</command> encodes
8ec3c085233cedb22b05da36e2773c8f357a7e45Automatic Updater the answers in the lightweight resolver format and returns
8ec3c085233cedb22b05da36e2773c8f357a7e45Automatic Updater them to the client that made the request.
8ec3c085233cedb22b05da36e2773c8f357a7e45Automatic Updater If <filename>/etc/resolv.conf</filename> contains any
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <option>nameserver</option> entries, <command>lwresd</command>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont sends recursive DNS queries to those servers. This is similar
2a6d4c9948b3f4f31311bd799d114585a30419a9Automatic Updater to the use of forwarders in a caching name server. If no
2a6d4c9948b3f4f31311bd799d114585a30419a9Automatic Updater <option>nameserver</option> entries are present, or if
2a6d4c9948b3f4f31311bd799d114585a30419a9Automatic Updater forwarding fails, <command>lwresd</command> resolves the
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont queries autonomously starting at the root name servers, using
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont a built-in list of root server hints.
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <variablelist>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <varlistentry>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater Use IPv4 only even if the host machine is capable of IPv6.
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <option>-4</option> and <option>-6</option> are mutually
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont </varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont Use IPv6 only even if the host machine is capable of IPv4.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <option>-4</option> and <option>-6</option> are mutually
f8e3e03cacd16ffb923a9603fca23a9e1a1fee07Automatic Updater </varlistentry>
f8e3e03cacd16ffb923a9603fca23a9e1a1fee07Automatic Updater <!-- this is in source but not mentioned? does this matter? -->
f8e3e03cacd16ffb923a9603fca23a9e1a1fee07Automatic Updater <varlistentry>
f8e3e03cacd16ffb923a9603fca23a9e1a1fee07Automatic Updater <term>-c <replaceable class="parameter">config-file</replaceable></term>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont Use <replaceable class="parameter">config-file</replaceable> as the
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater configuration file instead of the default,
0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater <!-- Should this be an absolute path name? -->
0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater <option>-c</option> can not be used with <option>-C</option>.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont </varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <term>-C <replaceable class="parameter">config-file</replaceable></term>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater Use <replaceable class="parameter">config-file</replaceable> as the
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont configuration file instead of the default,
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <option>-C</option> can not be used with <option>-c</option>.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont </varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <term>-d <replaceable class="parameter">debug-level</replaceable></term>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont Debugging traces from <command>lwresd</command> become
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont more verbose as the debug level increases.
a3416b0a1b5482b6df32839445ca98c016945570Automatic Updater </varlistentry>
a3416b0a1b5482b6df32839445ca98c016945570Automatic Updater <varlistentry>
a3416b0a1b5482b6df32839445ca98c016945570Automatic Updater Run the server in the foreground (i.e. do not daemonize).
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont </varlistentry>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <varlistentry>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater Run the server in the foreground and force all logging
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater </varlistentry>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <varlistentry>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <term>-i <replaceable class="parameter">pid-file</replaceable></term>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater Use <replaceable class="parameter">pid-file</replaceable> as the
f8e3e03cacd16ffb923a9603fca23a9e1a1fee07Automatic Updater PID file instead of the default,
f8e3e03cacd16ffb923a9603fca23a9e1a1fee07Automatic Updater <filename>/var/run/lwresd/lwresd.pid</filename>.
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater </varlistentry>
5a24d24c8fba3480d707c0c902379ddb36501e12Automatic Updater <varlistentry>
f8e3e03cacd16ffb923a9603fca23a9e1a1fee07Automatic Updater <term>-m <replaceable class="parameter">flag</replaceable></term>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater Turn on memory usage debugging flags. Possible flags are
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <replaceable class="parameter">usage</replaceable>,
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <replaceable class="parameter">trace</replaceable>,
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <replaceable class="parameter">record</replaceable>,
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <replaceable class="parameter">size</replaceable>, and
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <replaceable class="parameter">mctx</replaceable>.
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater These correspond to the ISC_MEM_DEBUGXXXX flags described in
f8e3e03cacd16ffb923a9603fca23a9e1a1fee07Automatic Updater </varlistentry>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <varlistentry>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <term>-n <replaceable class="parameter">#cpus</replaceable></term>
f8e3e03cacd16ffb923a9603fca23a9e1a1fee07Automatic Updater Create <replaceable class="parameter">#cpus</replaceable> worker threads
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater to take advantage of multiple CPUs. If not specified,
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater <command>lwresd</command> will try to determine the
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater number of CPUs present and create one thread per CPU.
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater If it is unable to determine the number of CPUs, a
0e9e255d1643375056aa9ed7fe2a279713ffae78Automatic Updater single worker thread will be created.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont </varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <term>-P <replaceable class="parameter">port</replaceable></term>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont Listen for lightweight resolver queries on port
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <replaceable class="parameter">port</replaceable>. If
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont not specified, the default is port 921.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont </varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <term>-p <replaceable class="parameter">port</replaceable></term>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont Send DNS lookups to port <replaceable class="parameter">port</replaceable>. If not
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont specified, the default is port 53. This provides a
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont way of testing the lightweight resolver daemon with a
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater name server that listens for queries on a non-standard
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont </varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <varlistentry>
c7d32c0b0ff4c01f0d4479af3410d3c06044d48aAutomatic Updater Write memory usage statistics to <filename>stdout</filename>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont This option is mainly of interest to BIND 9 developers
0e9e255d1643375056aa9ed7fe2a279713ffae78Automatic Updater and may be removed or changed in a future release.
8e821eea5f57ac47a94305aa7ab0c3570d92a311Automatic Updater </varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <term>-t <replaceable class="parameter">directory</replaceable></term>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont to <replaceable class="parameter">directory</replaceable> after
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont processing the command line arguments, but before
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont reading the configuration file.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont This option should be used in conjunction with the
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <option>-u</option> option, as chrooting a process
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews running as root doesn't enhance security on most
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont systems; the way <function>chroot(2)</function> is
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont defined allows a process with root privileges to
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont escape a chroot jail.
922312472e2e05ebc64993d465999c5351b83036Automatic Updater </varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <term>-u <replaceable class="parameter">user</replaceable></term>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont to <replaceable class="parameter">user</replaceable> after completing
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont privileged operations, such as creating sockets that
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont listen on privileged ports.