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