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