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