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