lwresd.docbook revision 135446 
1<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2<!--
3 - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
4 - Copyright (C) 2000, 2001  Internet Software Consortium.
5 -
6 - Permission to use, copy, modify, and distribute this software for any
7 - purpose with or without fee is hereby granted, provided that the above
8 - copyright notice and this permission notice appear in all copies.
9 -
10 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
11 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
12 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
13 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
14 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
15 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
16 - PERFORMANCE OF THIS SOFTWARE.
17-->
18
19<!-- $Id: lwresd.docbook,v 1.6.208.2 2004/06/03 02:24:57 marka Exp $ -->
20
21<refentry>
22  <refentryinfo>
23    <date>June 30, 2000</date>
24  </refentryinfo>
25
26  <refmeta>
27    <refentrytitle><application>lwresd</application></refentrytitle>
28    <manvolnum>8</manvolnum>
29    <refmiscinfo>BIND9</refmiscinfo>
30  </refmeta>
31
32  <refnamediv>
33    <refname><application>lwresd</application></refname>
34    <refpurpose>lightweight resolver daemon</refpurpose>
35  </refnamediv>
36
37  <refsynopsisdiv>
38    <cmdsynopsis>
39      <command>lwresd</command>
40      <arg><option>-C <replaceable class="parameter">config-file</replaceable></option></arg>
41      <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>
42      <arg><option>-f</option></arg>
43      <arg><option>-g</option></arg>
44      <arg><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg>
45      <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>
46      <arg><option>-P <replaceable class="parameter">port</replaceable></option></arg>
47      <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
48      <arg><option>-s</option></arg>
49      <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg>
50      <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
51      <arg><option>-v</option></arg>
52    </cmdsynopsis>
53  </refsynopsisdiv>
54
55  <refsect1>
56    <title>DESCRIPTION</title>
57    <para>
58	<command>lwresd</command> is the daemon providing name lookup
59	services to clients that use the BIND 9 lightweight resolver
60	library.  It is essentially a stripped-down, caching-only name
61	server that answers queries using the BIND 9 lightweight
62	resolver protocol rather than the DNS protocol.
63    </para>
64    <para>
65	<command>lwresd</command> listens for resolver queries on a
66	UDP port on the IPv4 loopback interface, 127.0.0.1.  This
67	means that <command>lwresd</command> can only be used by
68	processes running on the local machine.  By default UDP port
69	number 921 is used for lightweight resolver requests and
70	responses.
71    </para>
72    <para>
73	Incoming lightweight resolver requests are decoded by the
74	server which then resolves them using the DNS protocol.  When
75	the DNS lookup completes, <command>lwresd</command> encodes
76	the answers in the lightweight resolver format and returns
77	them to the client that made the request.
78    </para>
79    <para>
80	If <filename>/etc/resolv.conf</filename> contains any
81	<option>nameserver</option> entries, <command>lwresd</command>
82	sends recursive DNS queries to those servers.  This is similar
83	to the use of forwarders in a caching name server.  If no
84	<option>nameserver</option> entries are present, or if
85	forwarding fails, <command>lwresd</command> resolves the
86	queries autonomously starting at the root name servers, using
87	a built-in list of root server hints.
88    </para>
89  </refsect1>
90
91  <refsect1>
92    <title>OPTIONS</title>
93
94    <variablelist>
95      <varlistentry>
96	<term>-C <replaceable class="parameter">config-file</replaceable></term>
97	<listitem>
98	  <para>
99		Use <replaceable
100		class="parameter">config-file</replaceable> as the
101		configuration file instead of the default,
102		<filename>/etc/resolv.conf</filename>.
103          </para>
104	</listitem>
105      </varlistentry>
106
107      <varlistentry>
108	<term>-d <replaceable class="parameter">debug-level</replaceable></term>
109	<listitem>
110	  <para>
111		Set the daemon's debug level to <replaceable
112		class="parameter">debug-level</replaceable>.
113		Debugging traces from <command>lwresd</command> become
114		more verbose as the debug level increases.
115          </para>
116	</listitem>
117      </varlistentry>
118
119      <varlistentry>
120	<term>-f</term>
121	<listitem>
122	  <para>
123		Run the server in the foreground (i.e. do not daemonize).
124          </para>
125	</listitem>
126      </varlistentry>
127
128      <varlistentry>
129	<term>-g</term>
130	<listitem>
131	  <para>
132		Run the server in the foreground and force all logging
133		to <filename>stderr</filename>.
134          </para>
135	</listitem>
136      </varlistentry>
137
138      <varlistentry>
139	<term>-n <replaceable class="parameter">#cpus</replaceable></term>
140	<listitem>
141	  <para>
142		Create <replaceable
143		class="parameter">#cpus</replaceable> worker threads
144		to take advantage of multiple CPUs.  If not specified,
145		<command>lwresd</command> will try to determine the
146		number of CPUs present and create one thread per CPU.
147		If it is unable to determine the number of CPUs, a
148		single worker thread will be created.
149          </para>
150	</listitem>
151      </varlistentry>
152
153      <varlistentry>
154	<term>-P <replaceable class="parameter">port</replaceable></term>
155	<listitem>
156	  <para>
157		Listen for lightweight resolver queries on port
158		<replaceable class="parameter">port</replaceable>.  If
159		not specified, the default is port 921.
160          </para>
161	</listitem>
162      </varlistentry>
163
164      <varlistentry>
165	<term>-p <replaceable class="parameter">port</replaceable></term>
166	<listitem>
167	  <para>
168		Send DNS lookups to port <replaceable
169		class="parameter">port</replaceable>.  If not
170		specified, the default is port 53.  This provides a
171		way of testing the lightweight resolver daemon with a
172		name server that listens for queries on a non-standard
173		port number.
174          </para>
175	</listitem>
176      </varlistentry>
177
178      <varlistentry>
179	<term>-s</term>
180	<listitem>
181	  <para>
182		Write memory usage statistics to <filename>stdout</filename>
183		on exit.
184          </para>
185	  <note>
186	    <para>
187		This option is mainly of interest to BIND 9 developers
188		and may be removed or changed in a future release.
189	    </para>
190	  </note>
191	</listitem>
192      </varlistentry>
193
194      <varlistentry>
195	<term>-t <replaceable class="parameter">directory</replaceable></term>
196	<listitem>
197	  <para>
198		<function>chroot()</function> to <replaceable
199		class="parameter">directory</replaceable> after
200		processing the command line arguments, but before
201		reading the configuration file.
202          </para>
203	  <warning>
204	    <para>
205		This option should be used in conjunction with the
206		<option>-u</option> option, as chrooting a process
207		running as root doesn't enhance security on most
208		systems; the way <function>chroot()</function> is
209		defined allows a process with root privileges to
210		escape a chroot jail.
211	    </para>
212	  </warning>
213	</listitem>
214      </varlistentry>
215
216      <varlistentry>
217	<term>-u <replaceable class="parameter">user</replaceable></term>
218	<listitem>
219	  <para>
220		<function>setuid()</function> to <replaceable
221		class="parameter">user</replaceable> after completing
222		privileged operations, such as creating sockets that
223		listen on privileged ports.
224          </para>
225	</listitem>
226      </varlistentry>
227
228      <varlistentry>
229	<term>-v</term>
230	<listitem>
231	  <para>
232		Report the version number and exit.
233          </para>
234	</listitem>
235      </varlistentry>
236
237    </variablelist>
238
239  </refsect1>
240
241  <refsect1>
242    <title>FILES</title>
243
244    <variablelist>
245
246      <varlistentry>
247	<term><filename>/etc/resolv.conf</filename></term>
248	<listitem>
249	  <para>
250		The default configuration file.
251          </para>
252	</listitem>
253      </varlistentry>
254
255      <varlistentry>
256	<term><filename>/var/run/lwresd.pid</filename></term>
257	<listitem>
258	  <para>
259		The default process-id file.
260          </para>
261	</listitem>
262      </varlistentry>
263
264    </variablelist>
265
266  </refsect1>
267
268  <refsect1>
269    <title>SEE ALSO</title>
270    <para>
271	<citerefentry>
272	  <refentrytitle>named</refentrytitle>
273	  <manvolnum>8</manvolnum>
274        </citerefentry>,
275	<citerefentry>
276	  <refentrytitle>lwres</refentrytitle>
277	  <manvolnum>3</manvolnum>
278        </citerefentry>,
279	<citerefentry>
280	  <refentrytitle>resolver</refentrytitle>
281	  <manvolnum>5</manvolnum>
282        </citerefentry>.
283    </para>
284  </refsect1>
285
286  <refsect1>
287    <title>AUTHOR</title>
288    <para>
289	<corpauthor>Internet Systems Consortium</corpauthor>
290    </para>
291  </refsect1>
292
293</refentry>
294
295
296<!--
297 - Local variables:
298 - mode: sgml
299 - End:
300-->
301