2 - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
3 - Copyright (C) 2000, 2001 Internet Software Consortium.
5 - Permission to use, copy, modify, and distribute this software for any
6 - purpose with or without fee is hereby granted, provided that the above
7 - copyright notice and this permission notice appear in all copies.
9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 - PERFORMANCE OF THIS SOFTWARE.
17 <!-- $Id: lwresd.html,v 1.4.2.1.4.15 2007/05/16 06:10:55 marka Exp $ -->
20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
22 <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="id2476275"></a><div class="titlepage"></div>
26 <div class="refnamediv">
28 <p><span class="application">lwresd</span> — lightweight resolver daemon</p>
30 <div class="refsynopsisdiv">
32 <div class="cmdsynopsis"><p><code class="command">lwresd</code> [<code class="option">-c <em class="replaceable"><code>config-file</code></em></code>] [<code class="option">-C <em class="replaceable"><code>config-file</code></em></code>] [<code class="option">-d <em class="replaceable"><code>debug-level</code></em></code>] [<code class="option">-f</code>] [<code class="option">-g</code>] [<code class="option">-i <em class="replaceable"><code>pid-file</code></em></code>] [<code class="option">-m <em class="replaceable"><code>flag</code></em></code>] [<code class="option">-n <em class="replaceable"><code>#cpus</code></em></code>] [<code class="option">-P <em class="replaceable"><code>port</code></em></code>] [<code class="option">-p <em class="replaceable"><code>port</code></em></code>] [<code class="option">-s</code>] [<code class="option">-t <em class="replaceable"><code>directory</code></em></code>] [<code class="option">-u <em class="replaceable"><code>user</code></em></code>] [<code class="option">-v</code>] [<code class="option">-4</code>] [<code class="option">-6</code>]</p></div>
34 <div class="refsect1" lang="en">
35 <a name="id2543451"></a><h2>DESCRIPTION</h2>
37 <span><strong class="command">lwresd</strong></span> is the daemon providing name lookup
38 services to clients that use the BIND 9 lightweight resolver
39 library. It is essentially a stripped-down, caching-only name
40 server that answers queries using the BIND 9 lightweight
41 resolver protocol rather than the DNS protocol.
44 <span><strong class="command">lwresd</strong></span> listens for resolver queries on a
45 UDP port on the IPv4 loopback interface, 127.0.0.1. This
46 means that <span><strong class="command">lwresd</strong></span> can only be used by
47 processes running on the local machine. By default UDP port
48 number 921 is used for lightweight resolver requests and
52 Incoming lightweight resolver requests are decoded by the
53 server which then resolves them using the DNS protocol. When
54 the DNS lookup completes, <span><strong class="command">lwresd</strong></span> encodes
55 the answers in the lightweight resolver format and returns
56 them to the client that made the request.
59 If <code class="filename">/etc/resolv.conf</code> contains any
60 <code class="option">nameserver</code> entries, <span><strong class="command">lwresd</strong></span>
61 sends recursive DNS queries to those servers. This is similar
62 to the use of forwarders in a caching name server. If no
63 <code class="option">nameserver</code> entries are present, or if
64 forwarding fails, <span><strong class="command">lwresd</strong></span> resolves the
65 queries autonomously starting at the root name servers, using
66 a built-in list of root server hints.
69 <div class="refsect1" lang="en">
70 <a name="id2543500"></a><h2>OPTIONS</h2>
71 <div class="variablelist"><dl>
72 <dt><span class="term">-4</span></dt>
74 Use IPv4 only even if the host machine is capable of IPv6.
75 <code class="option">-4</code> and <code class="option">-6</code> are mutually
78 <dt><span class="term">-6</span></dt>
80 Use IPv6 only even if the host machine is capable of IPv4.
81 <code class="option">-4</code> and <code class="option">-6</code> are mutually
84 <dt><span class="term">-c <em class="replaceable"><code>config-file</code></em></span></dt>
86 Use <em class="replaceable"><code>config-file</code></em> as the
87 configuration file instead of the default,
88 <code class="filename">/etc/lwresd.conf</code>.
89 <font color="red"><term>-c</term></font> can not be used with <font color="red"><term>-C</term></font>.
91 <dt><span class="term">-C <em class="replaceable"><code>config-file</code></em></span></dt>
93 Use <em class="replaceable"><code>config-file</code></em> as the
94 configuration file instead of the default,
95 <code class="filename">/etc/resolv.conf</code>.
96 <font color="red"><term>-C</term></font> can not be used with <font color="red"><term>-c</term></font>.
98 <dt><span class="term">-d <em class="replaceable"><code>debug-level</code></em></span></dt>
100 Set the daemon's debug level to <em class="replaceable"><code>debug-level</code></em>.
101 Debugging traces from <span><strong class="command">lwresd</strong></span> become
102 more verbose as the debug level increases.
104 <dt><span class="term">-f</span></dt>
106 Run the server in the foreground (i.e. do not daemonize).
108 <dt><span class="term">-g</span></dt>
110 Run the server in the foreground and force all logging
111 to <code class="filename">stderr</code>.
113 <dt><span class="term">-i <em class="replaceable"><code>pid-file</code></em></span></dt>
115 Use <em class="replaceable"><code>pid-file</code></em> as the
116 PID file instead of the default,
117 <code class="filename">/var/run/lwresd.pid</code>.
119 <dt><span class="term">-m <em class="replaceable"><code>flag</code></em></span></dt>
121 Turn on memory usage debugging flags. Possible flags are
122 <em class="replaceable"><code>usage</code></em>,
123 <em class="replaceable"><code>trace</code></em>, and
124 <em class="replaceable"><code>record</code></em>.
125 These correspond to the ISC_MEM_DEBUGXXXX flags described in
126 <code class="filename"><isc/mem.h></code>.
128 <dt><span class="term">-n <em class="replaceable"><code>#cpus</code></em></span></dt>
130 Create <em class="replaceable"><code>#cpus</code></em> worker threads
131 to take advantage of multiple CPUs. If not specified,
132 <span><strong class="command">lwresd</strong></span> will try to determine the
133 number of CPUs present and create one thread per CPU.
134 If it is unable to determine the number of CPUs, a
135 single worker thread will be created.
137 <dt><span class="term">-P <em class="replaceable"><code>port</code></em></span></dt>
139 Listen for lightweight resolver queries on port
140 <em class="replaceable"><code>port</code></em>. If
141 not specified, the default is port 921.
143 <dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt>
145 Send DNS lookups to port <em class="replaceable"><code>port</code></em>. If not
146 specified, the default is port 53. This provides a
147 way of testing the lightweight resolver daemon with a
148 name server that listens for queries on a non-standard
151 <dt><span class="term">-s</span></dt>
154 Write memory usage statistics to <code class="filename">stdout</code>
157 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
158 <h3 class="title">Note</h3>
160 This option is mainly of interest to BIND 9 developers
161 and may be removed or changed in a future release.
165 <dt><span class="term">-t <em class="replaceable"><code>directory</code></em></span></dt>
168 <code class="function">Chroot</code> to <em class="replaceable"><code>directory</code></em> after
169 processing the command line arguments, but before
170 reading the configuration file.
172 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
173 <h3 class="title">Warning</h3>
175 This option should be used in conjunction with the
176 <code class="option">-u</code> option, as chrooting a process
177 running as root doesn't enhance security on most
178 systems; the way <code class="function">chroot(2)</code> is
179 defined allows a process with root privileges to
180 escape a chroot jail.
184 <dt><span class="term">-u <em class="replaceable"><code>user</code></em></span></dt>
186 <code class="function">Setuid</code> to <em class="replaceable"><code>user</code></em> after completing
187 privileged operations, such as creating sockets that
188 listen on privileged ports.
190 <dt><span class="term">-v</span></dt>
192 Report the version number and exit.
196 <div class="refsect1" lang="en">
197 <a name="id2543915"></a><h2>FILES</h2>
198 <div class="variablelist"><dl>
199 <dt><span class="term"><code class="filename">/etc/resolv.conf</code></span></dt>
201 The default configuration file.
203 <dt><span class="term"><code class="filename">/var/run/lwresd.pid</code></span></dt>
205 The default process-id file.
209 <div class="refsect1" lang="en">
210 <a name="id2543955"></a><h2>SEE ALSO</h2>
212 <span class="citerefentry"><span class="refentrytitle">named</span>(8)</span>,
213 <span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>,
214 <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>.
217 <div class="refsect1" lang="en">
218 <a name="id2543993"></a><h2>AUTHOR</h2>
220 <span class="corpauthor">Internet Systems Consortium</span>