lwresd.docbook revision 6ea1b817e31b89a627e146fe69e23ea0a64c89ec
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder - Copyright (C) 2000, 2001 Internet Software Consortium.
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner - Permission to use, copy, modify, and distribute this software for any
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner - purpose with or without fee is hereby granted, provided that the above
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - copyright notice and this permission notice appear in all copies.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian Maeder - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
4c7cb5671b356d873d67829ec8062a5083c1ee0eEugen Kuksa - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner - $Id: lwresd.docbook,v 1.1 2001/03/27 17:54:35 halley Exp $
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <refentryinfo>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner </refentryinfo>
4c7cb5671b356d873d67829ec8062a5083c1ee0eEugen Kuksa <refentrytitle><application>lwresd</application></refentrytitle>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <refnamediv>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <refname><application>lwresd</application></refname>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <refpurpose>lightweight resolver daemon</refpurpose>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner </refnamediv>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <refsynopsisdiv>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <cmdsynopsis>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <arg><option>-C <replaceable class="parameter">config-file</replaceable></option></arg>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <arg><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <arg><option>-P <replaceable class="parameter">port</replaceable></option></arg>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner </cmdsynopsis>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner </refsynopsisdiv>
e7757995211bd395dc79d26fe017d99375f7d2a6Christian Maeder <command>lwresd</command> is the daemon providing name lookup
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder services to clients that use the BIND 9 lightweight resolver
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder library. It is essentially a stripped-down, caching-only name
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder server that answers queries using the BIND 9 lightweight
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettich resolver protocol rather than the DNS protocol.
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettich <command>lwresd</command> listens for resolver queries on a
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder UDP port on the IPv4 loopback interface, 127.0.0.1. This
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder means that <command>lwresd</command> can only be used by
1a38107941725211e7c3f051f7a8f5e12199f03acmaeder processes running on the local machine. By default UDP port
ce5b44277ea06257548ff625e928cb1290c6d297cmaeder number 921 is used for lightweight resolver requests and
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder Incoming lightweight resolver requests are decoded by the
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder server which then resolves them using the DNS protocol. When
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder the DNS lookup completes, <command>lwresd</command> encodes
3dde4051c307b609159a097f08a05108fdd036efJonathan von Schroeder the answers in the lightweight resolver format and returns
3dde4051c307b609159a097f08a05108fdd036efJonathan von Schroeder them to the client that made the request.
3dde4051c307b609159a097f08a05108fdd036efJonathan von Schroeder If <filename>/etc/resolv.conf</filename> contains any
3dde4051c307b609159a097f08a05108fdd036efJonathan von Schroeder <option>nameserver</option> entries, <command>lwresd</command>
3dde4051c307b609159a097f08a05108fdd036efJonathan von Schroeder sends recursive DNS queries to those servers. This is similar
3dde4051c307b609159a097f08a05108fdd036efJonathan von Schroeder to the use of forwarders in a caching name server. If no
3dde4051c307b609159a097f08a05108fdd036efJonathan von Schroeder <option>nameserver</option> entries are present, or if
3dde4051c307b609159a097f08a05108fdd036efJonathan von Schroeder forwarding fails, <command>lwresd</command> resolves the
3dde4051c307b609159a097f08a05108fdd036efJonathan von Schroeder queries autonomously starting at the root name servers, using
825a1e4ca1e768de4b4883c65a6cb1dce6aa0002Christian Maeder a built-in list of root server hints.
8b767d09a78927b111f5596fdff9ca7d2c1a439fChristian Maeder <variablelist>
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder <varlistentry>
4b4a0b61b72cf8478a5d4d5002bca9f699401363Christian Maeder <term>-C <replaceable class="parameter">config-file</replaceable></term>
bab2d88d650448628730ed3b65c9f99c52500e8cChristian Maeder Use <replaceable
8cacad2a09782249243b80985f28e9387019fe40Christian Maeder configuration file instead of the default,
014dc30f64ec25e4790cca987d4d1e6635430510Christian Maeder </varlistentry>
6aea82c63ba1d2efc0329bc784a14e521469ec20Christian Maeder <varlistentry>
4ba08bfca0cc8d9da65397b8dfd2654fdb4c0e62Christian Maeder <term>-d <replaceable class="parameter">debug-level</replaceable></term>
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder Set the daemon's debug level to <replaceable
f5c0884429b01e74c6e658ded921fb2e16dfb478Christian Maeder class="parameter">debug-level</replaceable>.
db675e8302ddb0d6528088ce68f5e98a00e890e3Christian Maeder Debugging traces from <command>lwresd</command> become
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder more verbose as the debug level increases.
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder </varlistentry>
961087225d1d2b9534152a346d1a3755ed952fcdJens Elkner <varlistentry>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder Run the server in the foreground (i.e. do not daemonize).
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder </varlistentry>
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner <varlistentry>
dc679edd4ca027663212afdf00926ae2ce19b555Christian Maeder Run the server in the foreground and force all logging
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder </varlistentry>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder <varlistentry>
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder <term>-n <replaceable class="parameter">#cpus</replaceable></term>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder Create <replaceable
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder class="parameter">#cpus</replaceable> worker threads
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder to take advantage of multiple CPUs. If not specified,
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian Maeder <command>lwresd</command> will try to determine the
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian Maeder number of CPUs present and create one thread per CPU.
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian Maeder If it is unable to determine the number of CPUs, a
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian Maeder single worker thread will be created.
a84a8d508a0778b13a4d097a6dd34b95feae78acJens Elkner </varlistentry>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <varlistentry>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <term>-P <replaceable class="parameter">port</replaceable></term>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder Listen for lightweight resolver queries on port
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <replaceable class="parameter">port</replaceable>. If
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder not specified, the default is port 921.
8037b7d21021a94b69e4a092f5c98e491333d939cmaeder </varlistentry>
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder <varlistentry>
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder <term>-p <replaceable class="parameter">port</replaceable></term>
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder Send DNS lookups to port <replaceable
e4f4d096e5e6d60dd91c746d0e833d0ac7a29c50Christian Maeder class="parameter">port</replaceable>. If not
961087225d1d2b9534152a346d1a3755ed952fcdJens Elkner specified, the default is port 53. This provides a
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder way of testing the lightweight resolver daemon with a
961087225d1d2b9534152a346d1a3755ed952fcdJens Elkner name server that listens for queries on a non-standard
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder </varlistentry>
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder <varlistentry>
93f5b72fdb9ee734caa750b43dd79bbb590dcd73Christian Maeder Write memory usage statistics to <filename>stdout</filename> on exit.
254df6f22d01eacf7c57b85729e0445747b630d9Christian Maeder This option is mainly of interest to BIND 9 developers
4ba08bfca0cc8d9da65397b8dfd2654fdb4c0e62Christian Maeder and may be removed or changed in a future release.
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder </varlistentry>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <varlistentry>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <term>-t <replaceable class="parameter">directory</replaceable></term>
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian Maeder <function>chroot()</function> to <replaceable
aded505f9b42cc38975559c2a5d175ae95de436bChristian Maeder class="parameter">directory</replaceable> after
3554301a34639efb6c9961a8571775d0061284c9Christian Maeder processing the command line arguments, but before
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers reading the configuration file.
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder This option should be used in conjunction with the
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder <option>-u</option> option, as chrooting a process
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder running as root doesn't enhance security on most
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder systems; the way <function>chroot()</function> is
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder defined allows a process with root privileges to
3554301a34639efb6c9961a8571775d0061284c9Christian Maeder escape a chroot jail.
aded505f9b42cc38975559c2a5d175ae95de436bChristian Maeder </varlistentry>
aded505f9b42cc38975559c2a5d175ae95de436bChristian Maeder <varlistentry>
aded505f9b42cc38975559c2a5d175ae95de436bChristian Maeder <term>-u <replaceable class="parameter">user</replaceable></term>
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder <function>setuid()</function> to <replaceable
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder class="parameter">user</replaceable> after completing
a14767aeac3e78ed100f5b75e210ba563ee10dbaChristian Maeder privileged operations, such as creating sockets that
a14767aeac3e78ed100f5b75e210ba563ee10dbaChristian Maeder listen on privileged ports.
3554301a34639efb6c9961a8571775d0061284c9Christian Maeder </varlistentry>
54ea981a0503c396c2923a1c06421c6235baf27fChristian Maeder <varlistentry>
db6729e623b4053149084ccf4b35e5308ac7e359Christian Maeder Report the version number and exit.
aded505f9b42cc38975559c2a5d175ae95de436bChristian Maeder </varlistentry>
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder </variablelist>
254df6f22d01eacf7c57b85729e0445747b630d9Christian Maeder <variablelist>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <varlistentry>
254df6f22d01eacf7c57b85729e0445747b630d9Christian Maeder <term><filename>/etc/resolv.conf</filename></term>
aded505f9b42cc38975559c2a5d175ae95de436bChristian Maeder The default configuration file.
ac34194a668399bb8ef238da77c3a09e93fb253bChristian Maeder </varlistentry>
aded505f9b42cc38975559c2a5d175ae95de436bChristian Maeder <varlistentry>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <term><filename>/var/run/lwresd.pid</filename></term>
c208973c890b8f993297720fd0247bc7481d4304Christian Maeder The default process-id file.
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian Maeder </varlistentry>
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian Maeder </variablelist>
01e278bdd7dce13b9303ed3d79683d83c89d09f9Liam O'Reilly <citerefentry>
8c812cd83569e973f10cf69a342424ceabc07af9Christian Maeder </citerefentry>,
8c812cd83569e973f10cf69a342424ceabc07af9Christian Maeder <citerefentry>
31d6d9286988dc31639d105841296759aeb743e0Jonathan von Schroeder </citerefentry>,
1535e1d8c82db5f7e2402261983c4c2ef39f4f39Mihai Codescu <citerefentry>
7a3fe82695aa32657693e05712f84d7f81672f2eJonathan von Schroeder <refentrytitle>resolver</refentrytitle>
7a3fe82695aa32657693e05712f84d7f81672f2eJonathan von Schroeder </citerefentry>.
81f49ee02aaa3bc870401f8883bf52742eb3ea7aJonathan von Schroeder <corpauthor>Internet Software Consortium</corpauthor>
0b349288edfa50fdf38fda1a14e1562d03f92574Christian Maeder - Local variables: