lwresd.html revision b0e8629055a766d4555a005a283c2889a5974945
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
229ea4644b3a7d9c7fdaa43888e7f55ba01e2ee3Automatic Updater - Copyright (C) 2000, 2001 Internet Software Consortium.
1167fc7904c5f0a472f8df207ac46dd52c7f1ec8Automatic Updater - Permission to use, copy, modify, and distribute this software for any
0c39b3ed9409ecb277d5e32fa763a4e4d6598df8Automatic Updater - purpose with or without fee is hereby granted, provided that the above
46da3117812814a29432a8d9a9ccf8acdbfdadceAutomatic Updater - copyright notice and this permission notice appear in all copies.
0519188c8e1ae76978fc4e0f799620cd36eba07aAutomatic Updater - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
79b273c187a4aa1016a62181983dfdd0521681aeMark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
90ff38a0d8deaf5f9c2aa5916d99b2e572d28738Automatic Updater - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
6c6a121295b30772cbf3dd75a51fb9d883051a0eAutomatic Updater - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington - PERFORMANCE OF THIS SOFTWARE.
e171a4137c6ba348957e61b7c4c3541493c0da02Automatic Updater<!-- $Id: lwresd.html,v 1.21 2007/01/30 00:24:59 marka Exp $ -->
e130ab53e992670e2a2ecf043976ac09f21358d1Automatic Updater<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
e171a4137c6ba348957e61b7c4c3541493c0da02Automatic Updater<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
831f79c4310a7d38fc3475ccfff531b2b2535641Automatic Updater<a name="id2476275"></a><div class="titlepage"></div>
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews<p><span class="application">lwresd</span> — lightweight resolver daemon</p>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic 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">-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">-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>]</p></div>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<a name="id2543435"></a><h2>DESCRIPTION</h2>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<p><span><strong class="command">lwresd</strong></span>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt is the daemon providing name lookup
e130ab53e992670e2a2ecf043976ac09f21358d1Automatic Updater services to clients that use the BIND 9 lightweight resolver
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater library. It is essentially a stripped-down, caching-only name
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt server that answers queries using the BIND 9 lightweight
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater resolver protocol rather than the DNS protocol.
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<p><span><strong class="command">lwresd</strong></span>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt listens for resolver queries on a
e130ab53e992670e2a2ecf043976ac09f21358d1Automatic Updater UDP port on the IPv4 loopback interface, 127.0.0.1. This
2d2dc37599979c83495510f8af8d1756753aa2c5Automatic Updater means that <span><strong class="command">lwresd</strong></span> can only be used by
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt processes running on the local machine. By default UDP port
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater number 921 is used for lightweight resolver requests and
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater Incoming lightweight resolver requests are decoded by the
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater server which then resolves them using the DNS protocol. When
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater the DNS lookup completes, <span><strong class="command">lwresd</strong></span> encodes
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater the answers in the lightweight resolver format and returns
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater them to the client that made the request.
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews If <code class="filename">/etc/resolv.conf</code> contains any
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews <code class="option">nameserver</code> entries, <span><strong class="command">lwresd</strong></span>
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews sends recursive DNS queries to those servers. This is similar
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington to the use of forwarders in a caching name server. If no
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic Updater <code class="option">nameserver</code> entries are present, or if
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews forwarding fails, <span><strong class="command">lwresd</strong></span> resolves the
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater queries autonomously starting at the root name servers, using
8e9f3b69914ee02a80b87c97b1f8093edb3e9ae0Automatic Updater a built-in list of root server hints.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<dt><span class="term">-C <em class="replaceable"><code>config-file</code></em></span></dt>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews Use <em class="replaceable"><code>config-file</code></em> as the
930f6069e5aa157cf6987cdafd412f5757a5a558Automatic Updater configuration file instead of the default,
693c4232dfdffaff672197d4b9fea944c64cf80aAutomatic Updater <code class="filename">/etc/resolv.conf</code>.
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater<dt><span class="term">-d <em class="replaceable"><code>debug-level</code></em></span></dt>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater Set the daemon's debug level to <em class="replaceable"><code>debug-level</code></em>.
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater Debugging traces from <span><strong class="command">lwresd</strong></span> become
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews more verbose as the debug level increases.
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater Run the server in the foreground (i.e. do not daemonize).
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater Run the server in the foreground and force all logging
11af78f7dc35741bdab68dbab11b03daab005b28Automatic Updater<dt><span class="term">-n <em class="replaceable"><code>#cpus</code></em></span></dt>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont Create <em class="replaceable"><code>#cpus</code></em> worker threads
e130ab53e992670e2a2ecf043976ac09f21358d1Automatic Updater to take advantage of multiple CPUs. If not specified,
8ccd7da886e93cd490fcb6f4c4e98a6514f35820Automatic Updater <span><strong class="command">lwresd</strong></span> will try to determine the
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont number of CPUs present and create one thread per CPU.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews If it is unable to determine the number of CPUs, a
e130ab53e992670e2a2ecf043976ac09f21358d1Automatic Updater single worker thread will be created.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<dt><span class="term">-P <em class="replaceable"><code>port</code></em></span></dt>
08e3b6797706a13054bad749dea04e94b514b8e7Automatic Updater Listen for lightweight resolver queries on port
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater <em class="replaceable"><code>port</code></em>. If
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews not specified, the default is port 921.
a308b69ac66fadf66863484f301314d6e6a3f1d2Automatic Updater<dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt>
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews Send DNS lookups to port <em class="replaceable"><code>port</code></em>. If not
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews specified, the default is port 53. This provides a
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater way of testing the lightweight resolver daemon with a
82447d835d3ff5c658749b4e9b4f66166407b3eaAutomatic Updater name server that listens for queries on a non-standard
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews port number.
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater Write memory usage statistics to <code class="filename">stdout</code>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater This option is mainly of interest to BIND 9 developers
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson and may be removed or changed in a future release.
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater<dt><span class="term">-t <em class="replaceable"><code>directory</code></em></span></dt>
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater to <em class="replaceable"><code>directory</code></em> after
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater processing the command line arguments, but before
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater reading the configuration file.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
8711e5c73ca872d59810760af0332194cbdd619bAutomatic Updater This option should be used in conjunction with the
229ea4644b3a7d9c7fdaa43888e7f55ba01e2ee3Automatic Updater <code class="option">-u</code> option, as chrooting a process
0ce87e5749aabb8eef1e0a37e4bd6e6ffa1d7196Automatic Updater running as root doesn't enhance security on most
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater systems; the way <code class="function">chroot()</code> is
229ea4644b3a7d9c7fdaa43888e7f55ba01e2ee3Automatic Updater defined allows a process with root privileges to
765c97d56ccddc9d7904c7d9ff2e2d825d9687e4Automatic Updater escape a chroot jail.
e130ab53e992670e2a2ecf043976ac09f21358d1Automatic Updater<dt><span class="term">-u <em class="replaceable"><code>user</code></em></span></dt>
d145b64cacc8d9cda51f9924ec70cd4661c3e2cfAutomatic Updater<dd><p><code class="function">setuid()</code>
8711e5c73ca872d59810760af0332194cbdd619bAutomatic Updater to <em class="replaceable"><code>user</code></em> after completing
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater privileged operations, such as creating sockets that
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater listen on privileged ports.
e85565067cf73f8cc21ee29b11761659f1d47ee9Automatic Updater Report the version number and exit.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="term"><code class="filename">/etc/resolv.conf</code></span></dt>
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater The default configuration file.
3f616e6f846be57b1717c6beaba0f74de9d5a7c6Automatic Updater<dt><span class="term"><code class="filename">/var/run/lwresd.pid</code></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The default process-id file.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<p><span class="citerefentry"><span class="refentrytitle">named</span>(8)</span>,
f7a71eef29bcbf892270460269c79664f600cffdAutomatic Updater <span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>,
e130ab53e992670e2a2ecf043976ac09f21358d1Automatic Updater <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>.
96ea71632887c58a9d00f47eb318bf76b35903c3Mark Andrews<p><span class="corpauthor">Internet Systems Consortium</span>