2454dfa32c93c20a8522c6ed42fe057baaac9f9aStephan Bosch<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen [<!ENTITY mdash "&#8212;">]>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen<refentry>

98720d3b830e8ec762e9bdde94a71c0ef184595dTimo Sirainen <refentryinfo>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen <date>June 30, 2000</date>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen </refentryinfo>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen

d482079eb385cd071bbc9637cacee225e4aff968Timo Sirainen <refmeta>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen <refentrytitle><application>lwresd</application></refentrytitle>

725051a12a40625d79aada33f86993d7b8a18631Timo Sirainen <manvolnum>8</manvolnum>

4da8c6cdefabd31262318c32da3c13de1d9ea953Timo Sirainen <refmiscinfo>BIND9</refmiscinfo>

42abccd9b2a5a4190bd3c14ec2dcc10d51c0f491Timo Sirainen </refmeta>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen

db693bf6fcae96d834567f1782257517b7207655Timo Sirainen <refnamediv>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen <refname><application>lwresd</application></refname>

db693bf6fcae96d834567f1782257517b7207655Timo Sirainen <refpurpose>lightweight resolver daemon</refpurpose>

2fb9ae42f9e36388ec6db24188b9108434043fd0Timo Sirainen </refnamediv>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen <docinfo>

f40228208c910147bf972b98fcdc4b3a3f6d200cTimo Sirainen <copyright>

f40228208c910147bf972b98fcdc4b3a3f6d200cTimo Sirainen <year>2004</year>

f40228208c910147bf972b98fcdc4b3a3f6d200cTimo Sirainen <year>2005</year>

f40228208c910147bf972b98fcdc4b3a3f6d200cTimo Sirainen <year>2007</year>

f40228208c910147bf972b98fcdc4b3a3f6d200cTimo Sirainen <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

f40228208c910147bf972b98fcdc4b3a3f6d200cTimo Sirainen </copyright>

f40228208c910147bf972b98fcdc4b3a3f6d200cTimo Sirainen <copyright>

a4804621ea31f573a68da297ee64bfe1f1d5d9b1Aki Tuomi <year>2000</year>

a4804621ea31f573a68da297ee64bfe1f1d5d9b1Aki Tuomi <year>2001</year>

a4804621ea31f573a68da297ee64bfe1f1d5d9b1Aki Tuomi <holder>Internet Software Consortium.</holder>

a4804621ea31f573a68da297ee64bfe1f1d5d9b1Aki Tuomi </copyright>

efe78d3ba24fc866af1c79b9223dc0809ba26cadStephan Bosch </docinfo>

a4804621ea31f573a68da297ee64bfe1f1d5d9b1Aki Tuomi

a4804621ea31f573a68da297ee64bfe1f1d5d9b1Aki Tuomi <refsynopsisdiv>

f33cd5b8b44175256eb92bec51a60ad8fb98bbe0Timo Sirainen <cmdsynopsis>

f33cd5b8b44175256eb92bec51a60ad8fb98bbe0Timo Sirainen <command>lwresd</command>

f33cd5b8b44175256eb92bec51a60ad8fb98bbe0Timo Sirainen <arg><option>-C <replaceable class="parameter">config-file</replaceable></option></arg>

f40228208c910147bf972b98fcdc4b3a3f6d200cTimo Sirainen <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>

f40228208c910147bf972b98fcdc4b3a3f6d200cTimo Sirainen <arg><option>-f</option></arg>

f40228208c910147bf972b98fcdc4b3a3f6d200cTimo Sirainen <arg><option>-g</option></arg>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen <arg><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>

2fb9ae42f9e36388ec6db24188b9108434043fd0Timo Sirainen <arg><option>-P <replaceable class="parameter">port</replaceable></option></arg>

2fb9ae42f9e36388ec6db24188b9108434043fd0Timo Sirainen <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>

2fb9ae42f9e36388ec6db24188b9108434043fd0Timo Sirainen <arg><option>-s</option></arg>

efe78d3ba24fc866af1c79b9223dc0809ba26cadStephan Bosch <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg>

2fb9ae42f9e36388ec6db24188b9108434043fd0Timo Sirainen <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>

2fb9ae42f9e36388ec6db24188b9108434043fd0Timo Sirainen <arg><option>-v</option></arg>

b1c85a1f889a5e71f491e320bdac95df3c9fe550Martti Rannanjärvi </cmdsynopsis>

b1c85a1f889a5e71f491e320bdac95df3c9fe550Martti Rannanjärvi </refsynopsisdiv>

b1c85a1f889a5e71f491e320bdac95df3c9fe550Martti Rannanjärvi

b1c85a1f889a5e71f491e320bdac95df3c9fe550Martti Rannanjärvi <refsect1>

b1c85a1f889a5e71f491e320bdac95df3c9fe550Martti Rannanjärvi <title>DESCRIPTION</title>

b1c85a1f889a5e71f491e320bdac95df3c9fe550Martti Rannanjärvi

eed56fe22f1fc61f2003d5e66373d03dacbc9aaaTimo Sirainen <para><command>lwresd</command>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen is the daemon providing name lookup

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen services to clients that use the BIND 9 lightweight resolver

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen library. It is essentially a stripped-down, caching-only name

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen server that answers queries using the BIND 9 lightweight

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen resolver protocol rather than the DNS protocol.

42abccd9b2a5a4190bd3c14ec2dcc10d51c0f491Timo Sirainen </para>

42abccd9b2a5a4190bd3c14ec2dcc10d51c0f491Timo Sirainen

725051a12a40625d79aada33f86993d7b8a18631Timo Sirainen <para><command>lwresd</command>

725051a12a40625d79aada33f86993d7b8a18631Timo Sirainen listens for resolver queries on a

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen UDP port on the IPv4 loopback interface, 127.0.0.1. This

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen means that <command>lwresd</command> can only be used by

a3fe8c0c54d87822f4b4f8f0d10caac611861b2bTimo Sirainen processes running on the local machine. By default UDP port

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen number 921 is used for lightweight resolver requests and

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen responses.

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen </para>

458acd7b39c84bae0d18c36ff9ddff9a49b4ae4aTimo Sirainen <para>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen Incoming lightweight resolver requests are decoded by the

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen server which then resolves them using the DNS protocol. When

4fbf59562594dbbbe037f8d4c480dbf88f3fc708Timo Sirainen the DNS lookup completes, <command>lwresd</command> encodes

4fbf59562594dbbbe037f8d4c480dbf88f3fc708Timo Sirainen the answers in the lightweight resolver format and returns

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen them to the client that made the request.

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen </para>

2fb9ae42f9e36388ec6db24188b9108434043fd0Timo Sirainen <para>

419be6cd72f6e11705576bbba683b29c32eaa762Timo Sirainen If <filename>/etc/resolv.conf</filename> contains any

705f6fbad395e6f014838e797b7dbcaceafd2f1dTimo Sirainen <option>nameserver</option> entries, <command>lwresd</command>

646817f0cfb39b0e0eb545900f1566b76a851b20Timo Sirainen sends recursive DNS queries to those servers. This is similar

725051a12a40625d79aada33f86993d7b8a18631Timo Sirainen to the use of forwarders in a caching name server. If no

0e35a99c5a6eaa90fb0459a45f05ebab73348d64Timo Sirainen <option>nameserver</option> entries are present, or if

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen forwarding fails, <command>lwresd</command> resolves the

d176f84ce5ca2073f4dfbafb457b9c74f6bf0d76Timo Sirainen queries autonomously starting at the root name servers, using

d176f84ce5ca2073f4dfbafb457b9c74f6bf0d76Timo Sirainen a built-in list of root server hints.

d176f84ce5ca2073f4dfbafb457b9c74f6bf0d76Timo Sirainen </para>

088643deee2059c5418a7e07733bbfe988639706Timo Sirainen </refsect1>

4fbf59562594dbbbe037f8d4c480dbf88f3fc708Timo Sirainen

d176f84ce5ca2073f4dfbafb457b9c74f6bf0d76Timo Sirainen <refsect1>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen <title>OPTIONS</title>

578ef2538ccf42e2a48234c24a8b709397101d88Timo Sirainen

0e35a99c5a6eaa90fb0459a45f05ebab73348d64Timo Sirainen <variablelist>

0e35a99c5a6eaa90fb0459a45f05ebab73348d64Timo Sirainen <varlistentry>

0e35a99c5a6eaa90fb0459a45f05ebab73348d64Timo Sirainen <term>-C <replaceable class="parameter">config-file</replaceable></term>

0e35a99c5a6eaa90fb0459a45f05ebab73348d64Timo Sirainen <listitem>

0e35a99c5a6eaa90fb0459a45f05ebab73348d64Timo Sirainen <para>

0e35a99c5a6eaa90fb0459a45f05ebab73348d64Timo Sirainen Use <replaceable class="parameter">config-file</replaceable> as the

0e35a99c5a6eaa90fb0459a45f05ebab73348d64Timo Sirainen configuration file instead of the default,

0e35a99c5a6eaa90fb0459a45f05ebab73348d64Timo Sirainen <filename>/etc/resolv.conf</filename>.

0e35a99c5a6eaa90fb0459a45f05ebab73348d64Timo Sirainen </para>

0e35a99c5a6eaa90fb0459a45f05ebab73348d64Timo Sirainen </listitem>

0e35a99c5a6eaa90fb0459a45f05ebab73348d64Timo Sirainen </varlistentry>

f40228208c910147bf972b98fcdc4b3a3f6d200cTimo Sirainen

f0913bab58841032fa0ac719771f78bc3a4fd23eMartti Rannanjärvi <varlistentry>

f0913bab58841032fa0ac719771f78bc3a4fd23eMartti Rannanjärvi <term>-d <replaceable class="parameter">debug-level</replaceable></term>

f0913bab58841032fa0ac719771f78bc3a4fd23eMartti Rannanjärvi <listitem>

725051a12a40625d79aada33f86993d7b8a18631Timo Sirainen <para>

725051a12a40625d79aada33f86993d7b8a18631Timo Sirainen Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.

f40228208c910147bf972b98fcdc4b3a3f6d200cTimo Sirainen Debugging traces from <command>lwresd</command> become

419be6cd72f6e11705576bbba683b29c32eaa762Timo Sirainen more verbose as the debug level increases.

419be6cd72f6e11705576bbba683b29c32eaa762Timo Sirainen </para>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen </listitem>

4da8c6cdefabd31262318c32da3c13de1d9ea953Timo Sirainen </varlistentry>

4da8c6cdefabd31262318c32da3c13de1d9ea953Timo Sirainen

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen <varlistentry>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen <term>-f</term>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen <listitem>

d6b3cfd855c0eebed68be50d3111de1b5a6afeb0Timo Sirainen <para>

4d4d6d4745682790c20d759ba93dbea46b812c5dTimo Sirainen Run the server in the foreground (i.e. do not daemonize).

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen </para>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen </listitem>

4da8c6cdefabd31262318c32da3c13de1d9ea953Timo Sirainen </varlistentry>

4d4d6d4745682790c20d759ba93dbea46b812c5dTimo Sirainen

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen <varlistentry>

315ce5be539bfe8bc7777ab0654499c49583cea2Timo Sirainen <term>-g</term>

<listitem>

<para>

Run the server in the foreground and force all logging

to <filename>stderr</filename>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>-n <replaceable class="parameter">#cpus</replaceable></term>

<listitem>

<para>

Create <replaceable class="parameter">#cpus</replaceable> worker threads

to take advantage of multiple CPUs. If not specified,

<command>lwresd</command> will try to determine the

number of CPUs present and create one thread per CPU.

If it is unable to determine the number of CPUs, a

single worker thread will be created.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>-P <replaceable class="parameter">port</replaceable></term>

<listitem>

<para>

Listen for lightweight resolver queries on port

<replaceable class="parameter">port</replaceable>. If

not specified, the default is port 921.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>-p <replaceable class="parameter">port</replaceable></term>

<listitem>

<para>

Send DNS lookups to port <replaceable class="parameter">port</replaceable>. If not

specified, the default is port 53. This provides a

way of testing the lightweight resolver daemon with a

name server that listens for queries on a non-standard

port number.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>-s</term>

<listitem>

<para>

Write memory usage statistics to <filename>stdout</filename>

on exit.

</para>

<note>

<para>

This option is mainly of interest to BIND 9 developers

and may be removed or changed in a future release.

</para>

</note>

</listitem>

</varlistentry>

<varlistentry>

<term>-t <replaceable class="parameter">directory</replaceable></term>

<listitem>

<para><function>chroot()</function>

to <replaceable class="parameter">directory</replaceable> after

processing the command line arguments, but before

reading the configuration file.

</para>

<warning>

<para>

This option should be used in conjunction with the

<option>-u</option> option, as chrooting a process

running as root doesn't enhance security on most

systems; the way <function>chroot()</function> is

defined allows a process with root privileges to

escape a chroot jail.

</para>

</warning>

</listitem>

</varlistentry>

<varlistentry>

<term>-u <replaceable class="parameter">user</replaceable></term>

<listitem>

<para><function>setuid()</function>

to <replaceable class="parameter">user</replaceable> after completing

privileged operations, such as creating sockets that

listen on privileged ports.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>-v</term>

<listitem>

<para>

Report the version number and exit.

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>FILES</title>

<variablelist>

<varlistentry>

<term><filename>/etc/resolv.conf</filename></term>

<listitem>

<para>

The default configuration file.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>/var/run/lwresd.pid</filename></term>

<listitem>

<para>

The default process-id file.

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>SEE ALSO</title>

<para><citerefentry>

<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>

</citerefentry>.

</para>

</refsect1>

<refsect1>

<title>AUTHOR</title>

<para><corpauthor>Internet Systems Consortium</corpauthor>

</para>

</refsect1>

</refentry><!--