lwresd.html revision 9a5087bf58f651bfff841192aba5afd06760d6ce
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<!--
19c7b1a0293498a3e36692c59646ed6e15ffc8d0Tinderbox User - Copyright (C) 2004, 2005, 2007-2009, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt - Copyright (C) 2000, 2001 Internet Software Consortium.
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt -
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt - Permission to use, copy, modify, and/or distribute this software for any
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt - purpose with or without fee is hereby granted, provided that the above
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt - copyright notice and this permission notice appear in all copies.
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt -
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt - PERFORMANCE OF THIS SOFTWARE.
19c7b1a0293498a3e36692c59646ed6e15ffc8d0Tinderbox User-->
6715db6593ce9a271ac3131cd7a886feaa386a2eEvan Hunt<!-- $Id$ -->
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<html>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<head>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<title>lwresd</title>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</head>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<a name="man.lwresd"></a><div class="titlepage"></div>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<div class="refnamediv">
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<h2>Name</h2>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<p><span class="application">lwresd</span> &#8212; lightweight resolver daemon</p>
be0982e9e4b0631670a4c449ddf8a2bfaf04eb92Evan Hunt</div>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<div class="refsynopsisdiv">
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<h2>Synopsis</h2>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<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>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt</div>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<div class="refsect1" lang="en">
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<a name="id2543484"></a><h2>DESCRIPTION</h2>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<p><span><strong class="command">lwresd</strong></span>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt is the daemon providing name lookup
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt services to clients that use the BIND 9 lightweight resolver
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt library. It is essentially a stripped-down, caching-only name
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt server that answers queries using the BIND 9 lightweight
9f40a783228eed48531756a6ab510d1e9c51648cTinderbox User resolver protocol rather than the DNS protocol.
938440694b33cd752e9e4b71a526368b4811c177Tinderbox User </p>
19c7b1a0293498a3e36692c59646ed6e15ffc8d0Tinderbox User<p><span><strong class="command">lwresd</strong></span>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt listens for resolver queries on a
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt UDP port on the IPv4 loopback interface, 127.0.0.1. This
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt means that <span><strong class="command">lwresd</strong></span> can only be used by
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt processes running on the local machine. By default, UDP port
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt number 921 is used for lightweight resolver requests and
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt responses.
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt </p>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<p>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Incoming lightweight resolver requests are decoded by the
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt server which then resolves them using the DNS protocol. When
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt the DNS lookup completes, <span><strong class="command">lwresd</strong></span> encodes
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt the answers in the lightweight resolver format and returns
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt them to the client that made the request.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </p>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<p>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt If <code class="filename">/etc/resolv.conf</code> contains any
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt <code class="option">nameserver</code> entries, <span><strong class="command">lwresd</strong></span>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt sends recursive DNS queries to those servers. This is similar
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt to the use of forwarders in a caching name server. If no
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt <code class="option">nameserver</code> entries are present, or if
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt forwarding fails, <span><strong class="command">lwresd</strong></span> resolves the
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt queries autonomously starting at the root name servers, using
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt a built-in list of root server hints.
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt </p>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt</div>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<div class="refsect1" lang="en">
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<a name="id2543531"></a><h2>OPTIONS</h2>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<div class="variablelist"><dl>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<dt><span class="term">-4</span></dt>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<dd><p>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt Use IPv4 only even if the host machine is capable of IPv6.
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt <code class="option">-4</code> and <code class="option">-6</code> are mutually
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt exclusive.
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt </p></dd>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<dt><span class="term">-6</span></dt>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<dd><p>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt Use IPv6 only even if the host machine is capable of IPv4.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <code class="option">-4</code> and <code class="option">-6</code> are mutually
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt exclusive.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </p></dd>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<dt><span class="term">-c <em class="replaceable"><code>config-file</code></em></span></dt>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<dd><p>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt Use <em class="replaceable"><code>config-file</code></em> as the
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt configuration file instead of the default,
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt <code class="filename">/etc/lwresd.conf</code>.
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt <code class="option">-c</code> can not be used with <code class="option">-C</code>.
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt </p></dd>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<dt><span class="term">-C <em class="replaceable"><code>config-file</code></em></span></dt>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<dd><p>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt Use <em class="replaceable"><code>config-file</code></em> as the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt configuration file instead of the default,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <code class="filename">/etc/resolv.conf</code>.
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt <code class="option">-C</code> can not be used with <code class="option">-c</code>.
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt </p></dd>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<dt><span class="term">-d <em class="replaceable"><code>debug-level</code></em></span></dt>
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt<dd><p>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Set the daemon's debug level to <em class="replaceable"><code>debug-level</code></em>.
0f66aced2640d964aeb6db41210711ba0640d7f2Evan Hunt Debugging traces from <span><strong class="command">lwresd</strong></span> become
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt more verbose as the debug level increases.
</p></dd>
<dt><span class="term">-f</span></dt>
<dd><p>
Run the server in the foreground (i.e. do not daemonize).
</p></dd>
<dt><span class="term">-g</span></dt>
<dd><p>
Run the server in the foreground and force all logging
to <code class="filename">stderr</code>.
</p></dd>
<dt><span class="term">-i <em class="replaceable"><code>pid-file</code></em></span></dt>
<dd><p>
Use <em class="replaceable"><code>pid-file</code></em> as the
PID file instead of the default,
<code class="filename">/var/run/lwresd/lwresd.pid</code>.
</p></dd>
<dt><span class="term">-m <em class="replaceable"><code>flag</code></em></span></dt>
<dd><p>
Turn on memory usage debugging flags. Possible flags are
<em class="replaceable"><code>usage</code></em>,
<em class="replaceable"><code>trace</code></em>,
<em class="replaceable"><code>record</code></em>,
<em class="replaceable"><code>size</code></em>, and
<em class="replaceable"><code>mctx</code></em>.
These correspond to the ISC_MEM_DEBUGXXXX flags described in
<code class="filename">&lt;isc/mem.h&gt;</code>.
</p></dd>
<dt><span class="term">-n <em class="replaceable"><code>#cpus</code></em></span></dt>
<dd><p>
Create <em class="replaceable"><code>#cpus</code></em> worker threads
to take advantage of multiple CPUs. If not specified,
<span><strong class="command">lwresd</strong></span> will try to determine the
number of CPUs present and create one thread per CPU.
If it is unable to determine the number of CPUs, a
single worker thread will be created.
</p></dd>
<dt><span class="term">-P <em class="replaceable"><code>port</code></em></span></dt>
<dd><p>
Listen for lightweight resolver queries on port
<em class="replaceable"><code>port</code></em>. If
not specified, the default is port 921.
</p></dd>
<dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt>
<dd><p>
Send DNS lookups to port <em class="replaceable"><code>port</code></em>. If not
specified, the default is port 53. This provides a
way of testing the lightweight resolver daemon with a
name server that listens for queries on a non-standard
port number.
</p></dd>
<dt><span class="term">-s</span></dt>
<dd>
<p>
Write memory usage statistics to <code class="filename">stdout</code>
on exit.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
This option is mainly of interest to BIND 9 developers
and may be removed or changed in a future release.
</p>
</div>
</dd>
<dt><span class="term">-t <em class="replaceable"><code>directory</code></em></span></dt>
<dd>
<p>Chroot
to <em class="replaceable"><code>directory</code></em> after
processing the command line arguments, but before
reading the configuration file.
</p>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p>
This option should be used in conjunction with the
<code class="option">-u</code> option, as chrooting a process
running as root doesn't enhance security on most
systems; the way <code class="function">chroot(2)</code> is
defined allows a process with root privileges to
escape a chroot jail.
</p>
</div>
</dd>
<dt><span class="term">-u <em class="replaceable"><code>user</code></em></span></dt>
<dd><p>Setuid
to <em class="replaceable"><code>user</code></em> after completing
privileged operations, such as creating sockets that
listen on privileged ports.
</p></dd>
<dt><span class="term">-v</span></dt>
<dd><p>
Report the version number and exit.
</p></dd>
</dl></div>
</div>
<div class="refsect1" lang="en">
<a name="id2543948"></a><h2>FILES</h2>
<div class="variablelist"><dl>
<dt><span class="term"><code class="filename">/etc/resolv.conf</code></span></dt>
<dd><p>
The default configuration file.
</p></dd>
<dt><span class="term"><code class="filename">/var/run/lwresd.pid</code></span></dt>
<dd><p>
The default process-id file.
</p></dd>
</dl></div>
</div>
<div class="refsect1" lang="en">
<a name="id2543988"></a><h2>SEE ALSO</h2>
<p><span class="citerefentry"><span class="refentrytitle">named</span>(8)</span>,
<span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>,
<span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id2544022"></a><h2>AUTHOR</h2>
<p><span class="corpauthor">Internet Systems Consortium</span>
</p>
</div>
</div></body>
</html>