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 "—">]>
5 - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
6 - Copyright (C) 2000, 2001 Internet Software Consortium.
8 - Permission to use, copy, modify, and/or 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.
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.
21 <!-- $Id: lwresd.docbook,v 1.6.208.9 2007/08/28 07:19:08 tbox Exp $ -->
25 <date>June 30, 2000</date>
29 <refentrytitle><application>lwresd</application></refentrytitle>
30 <manvolnum>8</manvolnum>
31 <refmiscinfo>BIND9</refmiscinfo>
39 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
44 <holder>Internet Software Consortium.</holder>
49 <refname><application>lwresd</application></refname>
50 <refpurpose>lightweight resolver daemon</refpurpose>
55 <command>lwresd</command>
56 <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
57 <arg><option>-C <replaceable class="parameter">config-file</replaceable></option></arg>
58 <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>
59 <arg><option>-f</option></arg>
60 <arg><option>-g</option></arg>
61 <arg><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg>
62 <arg><option>-m <replaceable class="parameter">flag</replaceable></option></arg>
63 <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>
64 <arg><option>-P <replaceable class="parameter">port</replaceable></option></arg>
65 <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
66 <arg><option>-s</option></arg>
67 <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg>
68 <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
69 <arg><option>-v</option></arg>
70 <arg><option>-4</option></arg>
71 <arg><option>-6</option></arg>
76 <title>DESCRIPTION</title>
78 <command>lwresd</command> is the daemon providing name lookup
79 services to clients that use the BIND 9 lightweight resolver
80 library. It is essentially a stripped-down, caching-only name
81 server that answers queries using the BIND 9 lightweight
82 resolver protocol rather than the DNS protocol.
85 <command>lwresd</command> listens for resolver queries on a
86 UDP port on the IPv4 loopback interface, 127.0.0.1. This
87 means that <command>lwresd</command> can only be used by
88 processes running on the local machine. By default UDP port
89 number 921 is used for lightweight resolver requests and
93 Incoming lightweight resolver requests are decoded by the
94 server which then resolves them using the DNS protocol. When
95 the DNS lookup completes, <command>lwresd</command> encodes
96 the answers in the lightweight resolver format and returns
97 them to the client that made the request.
100 If <filename>/etc/resolv.conf</filename> contains any
101 <option>nameserver</option> entries, <command>lwresd</command>
102 sends recursive DNS queries to those servers. This is similar
103 to the use of forwarders in a caching name server. If no
104 <option>nameserver</option> entries are present, or if
105 forwarding fails, <command>lwresd</command> resolves the
106 queries autonomously starting at the root name servers, using
107 a built-in list of root server hints.
112 <title>OPTIONS</title>
120 Use IPv4 only even if the host machine is capable of IPv6.
121 <option>-4</option> and <option>-6</option> are mutually
131 Use IPv6 only even if the host machine is capable of IPv4.
132 <option>-4</option> and <option>-6</option> are mutually
138 <!-- this is in source but not mentioned? does this matter? -->
140 <term>-c <replaceable class="parameter">config-file</replaceable></term>
143 Use <replaceable class="parameter">config-file</replaceable> as the
144 configuration file instead of the default,
145 <filename>/etc/lwresd.conf</filename>.
146 <term>-c</term> can not be used with <term>-C</term>.
152 <term>-C <replaceable class="parameter">config-file</replaceable></term>
155 Use <replaceable class="parameter">config-file</replaceable> as the
156 configuration file instead of the default,
157 <filename>/etc/resolv.conf</filename>.
158 <term>-C</term> can not be used with <term>-c</term>.
164 <term>-d <replaceable class="parameter">debug-level</replaceable></term>
167 Set the daemon's debug level to <replaceable
168 class="parameter">debug-level</replaceable>.
169 Debugging traces from <command>lwresd</command> become
170 more verbose as the debug level increases.
179 Run the server in the foreground (i.e. do not daemonize).
188 Run the server in the foreground and force all logging
189 to <filename>stderr</filename>.
195 <term>-i <replaceable class="parameter">pid-file</replaceable></term>
198 Use <replaceable class="parameter">pid-file</replaceable> as the
199 PID file instead of the default,
200 <filename>/var/run/lwresd.pid</filename>.
206 <term>-m <replaceable class="parameter">flag</replaceable></term>
209 Turn on memory usage debugging flags. Possible flags are
210 <replaceable class="parameter">usage</replaceable>,
211 <replaceable class="parameter">trace</replaceable>, and
212 <replaceable class="parameter">record</replaceable>.
213 These correspond to the ISC_MEM_DEBUGXXXX flags described in
214 <filename><isc/mem.h></filename>.
220 <term>-n <replaceable class="parameter">#cpus</replaceable></term>
224 class="parameter">#cpus</replaceable> worker threads
225 to take advantage of multiple CPUs. If not specified,
226 <command>lwresd</command> will try to determine the
227 number of CPUs present and create one thread per CPU.
228 If it is unable to determine the number of CPUs, a
229 single worker thread will be created.
235 <term>-P <replaceable class="parameter">port</replaceable></term>
238 Listen for lightweight resolver queries on port
239 <replaceable class="parameter">port</replaceable>. If
240 not specified, the default is port 921.
246 <term>-p <replaceable class="parameter">port</replaceable></term>
249 Send DNS lookups to port <replaceable
250 class="parameter">port</replaceable>. If not
251 specified, the default is port 53. This provides a
252 way of testing the lightweight resolver daemon with a
253 name server that listens for queries on a non-standard
263 Write memory usage statistics to <filename>stdout</filename>
268 This option is mainly of interest to BIND 9 developers
269 and may be removed or changed in a future release.
276 <term>-t <replaceable class="parameter">directory</replaceable></term>
279 <function>Chroot</function> to <replaceable
280 class="parameter">directory</replaceable> after
281 processing the command line arguments, but before
282 reading the configuration file.
286 This option should be used in conjunction with the
287 <option>-u</option> option, as chrooting a process
288 running as root doesn't enhance security on most
289 systems; the way <function>chroot(2)</function> is
290 defined allows a process with root privileges to
291 escape a chroot jail.
298 <term>-u <replaceable class="parameter">user</replaceable></term>
301 <function>Setuid</function> to <replaceable
302 class="parameter">user</replaceable> after completing
303 privileged operations, such as creating sockets that
304 listen on privileged ports.
313 Report the version number and exit.
328 <term><filename>/etc/resolv.conf</filename></term>
331 The default configuration file.
337 <term><filename>/var/run/lwresd.pid</filename></term>
340 The default process-id file.
350 <title>SEE ALSO</title>
353 <refentrytitle>named</refentrytitle>
354 <manvolnum>8</manvolnum>
357 <refentrytitle>lwres</refentrytitle>
358 <manvolnum>3</manvolnum>
361 <refentrytitle>resolver</refentrytitle>
362 <manvolnum>5</manvolnum>
368 <title>AUTHOR</title>
370 <corpauthor>Internet Systems Consortium</corpauthor>