PageRenderTime 31ms CodeModel.GetById 21ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

/contrib/bind9/bin/named/lwresd.docbook

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 374 lines | 337 code | 37 blank | 0 comment | 0 complexity | 01c5ee575ae31d8f6047fb90767c31a0 MD5 | raw file
  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 "&#8212;">]>
  4<!--
  5 - Copyright (C) 2004, 2005, 2007-2009  Internet Systems Consortium, Inc. ("ISC")
  6 - Copyright (C) 2000, 2001  Internet Software Consortium.
  7 -
  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.
 11 -
 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.
 19-->
 20
 21<!-- $Id: lwresd.docbook,v 1.20 2009/01/20 23:47:56 tbox Exp $ -->
 22<refentry>
 23  <refentryinfo>
 24    <date>June 30, 2000</date>
 25  </refentryinfo>
 26
 27  <refmeta>
 28    <refentrytitle><application>lwresd</application></refentrytitle>
 29    <manvolnum>8</manvolnum>
 30    <refmiscinfo>BIND9</refmiscinfo>
 31  </refmeta>
 32
 33  <refnamediv>
 34    <refname><application>lwresd</application></refname>
 35    <refpurpose>lightweight resolver daemon</refpurpose>
 36  </refnamediv>
 37
 38  <docinfo>
 39    <copyright>
 40      <year>2004</year>
 41      <year>2005</year>
 42      <year>2007</year>
 43      <year>2008</year>
 44      <year>2009</year>
 45      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
 46    </copyright>
 47    <copyright>
 48      <year>2000</year>
 49      <year>2001</year>
 50      <holder>Internet Software Consortium.</holder>
 51    </copyright>
 52  </docinfo>
 53
 54  <refsynopsisdiv>
 55    <cmdsynopsis>
 56      <command>lwresd</command>
 57      <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
 58      <arg><option>-C <replaceable class="parameter">config-file</replaceable></option></arg>
 59      <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>
 60      <arg><option>-f</option></arg>
 61      <arg><option>-g</option></arg>
 62      <arg><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg>
 63      <arg><option>-m <replaceable class="parameter">flag</replaceable></option></arg>
 64      <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>
 65      <arg><option>-P <replaceable class="parameter">port</replaceable></option></arg>
 66      <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
 67      <arg><option>-s</option></arg>
 68      <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg>
 69      <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
 70      <arg><option>-v</option></arg>
 71      <arg><option>-4</option></arg>
 72      <arg><option>-6</option></arg>
 73    </cmdsynopsis>
 74  </refsynopsisdiv>
 75
 76  <refsect1>
 77    <title>DESCRIPTION</title>
 78
 79    <para><command>lwresd</command>
 80      is the daemon providing name lookup
 81      services to clients that use the BIND 9 lightweight resolver
 82      library.  It is essentially a stripped-down, caching-only name
 83      server that answers queries using the BIND 9 lightweight
 84      resolver protocol rather than the DNS protocol.
 85    </para>
 86
 87    <para><command>lwresd</command> 
 88      listens for resolver queries on a
 89      UDP port on the IPv4 loopback interface, 127.0.0.1.  This
 90      means that <command>lwresd</command> can only be used by
 91      processes running on the local machine.  By default, UDP port
 92      number 921 is used for lightweight resolver requests and
 93      responses.
 94    </para>
 95    <para>
 96      Incoming lightweight resolver requests are decoded by the
 97      server which then resolves them using the DNS protocol.  When
 98      the DNS lookup completes, <command>lwresd</command> encodes
 99      the answers in the lightweight resolver format and returns
100      them to the client that made the request.
101    </para>
102    <para>
103      If <filename>/etc/resolv.conf</filename> contains any
104      <option>nameserver</option> entries, <command>lwresd</command>
105      sends recursive DNS queries to those servers.  This is similar
106      to the use of forwarders in a caching name server.  If no
107      <option>nameserver</option> entries are present, or if
108      forwarding fails, <command>lwresd</command> resolves the
109      queries autonomously starting at the root name servers, using
110      a built-in list of root server hints.
111    </para>
112  </refsect1>
113
114  <refsect1>
115    <title>OPTIONS</title>
116
117    <variablelist>
118
119      <varlistentry>
120        <term>-4</term>
121        <listitem>
122          <para>
123            Use IPv4 only even if the host machine is capable of IPv6.
124            <option>-4</option> and <option>-6</option> are mutually
125            exclusive.
126          </para>
127        </listitem>
128      </varlistentry>
129
130      <varlistentry>
131        <term>-6</term>
132        <listitem>
133          <para>
134            Use IPv6 only even if the host machine is capable of IPv4.
135            <option>-4</option> and <option>-6</option> are mutually
136            exclusive.
137          </para>
138        </listitem>
139      </varlistentry>
140
141      <!-- this is in source but not mentioned? does this matter? -->
142      <varlistentry>
143        <term>-c <replaceable class="parameter">config-file</replaceable></term>
144        <listitem>
145          <para>
146            Use <replaceable class="parameter">config-file</replaceable> as the
147            configuration file instead of the default,
148            <filename>/etc/lwresd.conf</filename>.
149	    <!-- Should this be an absolute path name? -->
150	    <option>-c</option> can not be used with <option>-C</option>.
151          </para>
152        </listitem>
153      </varlistentry>
154
155      <varlistentry>
156        <term>-C <replaceable class="parameter">config-file</replaceable></term>
157        <listitem>
158          <para>
159            Use <replaceable class="parameter">config-file</replaceable> as the
160            configuration file instead of the default,
161            <filename>/etc/resolv.conf</filename>.
162	    <option>-C</option> can not be used with <option>-c</option>.
163          </para>
164        </listitem>
165      </varlistentry>
166
167      <varlistentry>
168        <term>-d <replaceable class="parameter">debug-level</replaceable></term>
169        <listitem>
170          <para>
171            Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.
172            Debugging traces from <command>lwresd</command> become
173            		more verbose as the debug level increases.
174          </para>
175        </listitem>
176      </varlistentry>
177
178      <varlistentry>
179        <term>-f</term>
180        <listitem>
181          <para>
182            Run the server in the foreground (i.e. do not daemonize).
183          </para>
184        </listitem>
185      </varlistentry>
186
187      <varlistentry>
188        <term>-g</term>
189        <listitem>
190          <para>
191            Run the server in the foreground and force all logging
192            to <filename>stderr</filename>.
193          </para>
194        </listitem>
195      </varlistentry>
196
197      <varlistentry>
198        <term>-i <replaceable class="parameter">pid-file</replaceable></term>
199        <listitem>
200          <para>
201            Use <replaceable class="parameter">pid-file</replaceable> as the
202            PID file instead of the default,
203            <filename>/var/run/lwresd/lwresd.pid</filename>.
204          </para>
205        </listitem>
206      </varlistentry>
207
208      <varlistentry>
209        <term>-m <replaceable class="parameter">flag</replaceable></term>
210        <listitem>
211          <para>
212            Turn on memory usage debugging flags.  Possible flags are
213            <replaceable class="parameter">usage</replaceable>,
214            <replaceable class="parameter">trace</replaceable>,
215            <replaceable class="parameter">record</replaceable>,
216            <replaceable class="parameter">size</replaceable>, and
217            <replaceable class="parameter">mctx</replaceable>.  
218            These correspond to the ISC_MEM_DEBUGXXXX flags described in
219            <filename>&lt;isc/mem.h&gt;</filename>.
220          </para>
221        </listitem>
222      </varlistentry>
223
224      <varlistentry>
225        <term>-n <replaceable class="parameter">#cpus</replaceable></term>
226        <listitem>
227          <para>
228            Create <replaceable class="parameter">#cpus</replaceable> worker threads
229            to take advantage of multiple CPUs.  If not specified,
230            <command>lwresd</command> will try to determine the
231            number of CPUs present and create one thread per CPU.
232            If it is unable to determine the number of CPUs, a
233            single worker thread will be created.
234          </para>
235        </listitem>
236      </varlistentry>
237
238      <varlistentry>
239        <term>-P <replaceable class="parameter">port</replaceable></term>
240        <listitem>
241          <para>
242            Listen for lightweight resolver queries on port
243            <replaceable class="parameter">port</replaceable>.  If
244            		not specified, the default is port 921.
245          </para>
246        </listitem>
247      </varlistentry>
248
249      <varlistentry>
250        <term>-p <replaceable class="parameter">port</replaceable></term>
251        <listitem>
252          <para>
253            Send DNS lookups to port <replaceable class="parameter">port</replaceable>.  If not
254            specified, the default is port 53.  This provides a
255            way of testing the lightweight resolver daemon with a
256            name server that listens for queries on a non-standard
257            port number.
258          </para>
259        </listitem>
260      </varlistentry>
261
262      <varlistentry>
263        <term>-s</term>
264        <listitem>
265          <para>
266            Write memory usage statistics to <filename>stdout</filename>
267            on exit.
268          </para>
269          <note>
270            <para>
271              This option is mainly of interest to BIND 9 developers
272              and may be removed or changed in a future release.
273            </para>
274          </note>
275        </listitem>
276      </varlistentry>
277
278      <varlistentry>
279        <term>-t <replaceable class="parameter">directory</replaceable></term>
280        <listitem>
281          <para>Chroot
282	    to <replaceable class="parameter">directory</replaceable> after
283            processing the command line arguments, but before
284            reading the configuration file.
285          </para>
286          <warning>
287            <para>
288              This option should be used in conjunction with the
289              <option>-u</option> option, as chrooting a process
290              running as root doesn't enhance security on most
291              systems; the way <function>chroot(2)</function> is
292              defined allows a process with root privileges to
293              escape a chroot jail.
294            </para>
295          </warning>
296        </listitem>
297      </varlistentry>
298
299      <varlistentry>
300        <term>-u <replaceable class="parameter">user</replaceable></term>
301        <listitem>
302          <para>Setuid
303	    to <replaceable class="parameter">user</replaceable> after completing
304            privileged operations, such as creating sockets that
305            listen on privileged ports.
306          </para>
307        </listitem>
308      </varlistentry>
309
310      <varlistentry>
311        <term>-v</term>
312        <listitem>
313          <para>
314            Report the version number and exit.
315          </para>
316        </listitem>
317      </varlistentry>
318
319    </variablelist>
320
321  </refsect1>
322
323  <refsect1>
324    <title>FILES</title>
325
326    <variablelist>
327
328      <varlistentry>
329        <term><filename>/etc/resolv.conf</filename></term>
330        <listitem>
331          <para>
332            The default configuration file.
333          </para>
334        </listitem>
335      </varlistentry>
336
337      <varlistentry>
338        <term><filename>/var/run/lwresd.pid</filename></term>
339        <listitem>
340          <para>
341            The default process-id file.
342          </para>
343        </listitem>
344      </varlistentry>
345
346    </variablelist>
347
348  </refsect1>
349
350  <refsect1>
351    <title>SEE ALSO</title>
352    <para><citerefentry>
353        <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
354      </citerefentry>,
355      <citerefentry>
356        <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
357      </citerefentry>,
358      <citerefentry>
359        <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
360      </citerefentry>.
361    </para>
362  </refsect1>
363
364  <refsect1>
365    <title>AUTHOR</title>
366    <para><corpauthor>Internet Systems Consortium</corpauthor>
367    </para>
368  </refsect1>
369
370</refentry><!--
371 - Local variables:
372 - mode: sgml
373 - End:
374-->