lwresd.docbook revision 0c27b3fe77ac1d5094ba3521e8142d9e7973133f
b29285b88f95055e1f399247994067f85882041cTinderbox User - Copyright (C) 2000, 2001, 2004, 2005, 2007-2009, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
4a14ce5ba00ab7bc55c99ffdcf59c7a4ab902721Automatic Updater - This Source Code Form is subject to the terms of the Mozilla Public
689023771c563d8660e45d439a207e06e96de28fMark Andrews - License, v. 2.0. If a copy of the MPL was not distributed with this
689023771c563d8660e45d439a207e06e96de28fMark Andrews - file, You can obtain one at http://mozilla.org/MPL/2.0/.
689023771c563d8660e45d439a207e06e96de28fMark Andrews<!-- Converted by db4-upgrade version 1.0 -->
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="man.lwresd">
689023771c563d8660e45d439a207e06e96de28fMark Andrews <refentryinfo>
ea94d370123a5892f6c47a97f21d1b28d44bb168Tinderbox User <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refentryinfo>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refentrytitle><application>lwresd</application></refentrytitle>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refnamediv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refname><application>lwresd</application></refname>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refpurpose>lightweight resolver daemon</refpurpose>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refnamediv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </copyright>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </copyright>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refsynopsisdiv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
5fa6a064b8301e4f274bd132fd577def59e4fb4cTinderbox User <arg choice="opt" rep="norepeat"><option>-C <replaceable class="parameter">config-file</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-f</option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-g</option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-m <replaceable class="parameter">flag</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>
5fa6a064b8301e4f274bd132fd577def59e4fb4cTinderbox User <arg choice="opt" rep="norepeat"><option>-P <replaceable class="parameter">port</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-p <replaceable class="parameter">port</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-s</option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-t <replaceable class="parameter">directory</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-u <replaceable class="parameter">user</replaceable></option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-v</option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-4</option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <arg choice="opt" rep="norepeat"><option>-6</option></arg>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </cmdsynopsis>
5fa6a064b8301e4f274bd132fd577def59e4fb4cTinderbox User </refsynopsisdiv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refsection><info><title>DESCRIPTION</title></info>
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
5fa6a064b8301e4f274bd132fd577def59e4fb4cTinderbox User server that answers queries using the BIND 9 lightweight
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein resolver protocol rather than the DNS protocol.
00124ad0406365d39f4b2d1011ef6a76706e9df0Mark Andrews listens for resolver queries on a
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews UDP port on the IPv4 loopback interface, 127.0.0.1. This
88a2182a1ad4fc7af07272af6b05b74db7f28e52Tinderbox User means that <command>lwresd</command> 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, <command>lwresd</command> encodes
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the answers in the lightweight resolver format and returns
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein them to the client that made the request.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If <filename>/etc/resolv.conf</filename> contains any
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <option>nameserver</option> entries, <command>lwresd</command>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein sends recursive DNS queries to those servers. This is similar
88a2182a1ad4fc7af07272af6b05b74db7f28e52Tinderbox User to the use of forwarders in a caching name server. If no
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <option>nameserver</option> entries are present, or if
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein forwarding fails, <command>lwresd</command> resolves the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein queries autonomously starting at the root name servers, using
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein a built-in list of root server hints.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refsection>
88a2182a1ad4fc7af07272af6b05b74db7f28e52Tinderbox User <refsection><info><title>OPTIONS</title></info>
d060d8669f5558690e7faf4a1c12fe5c02a7c60dAutomatic Updater <variablelist>
d060d8669f5558690e7faf4a1c12fe5c02a7c60dAutomatic Updater <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Use IPv4 only even if the host machine is capable of IPv6.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <option>-4</option> and <option>-6</option> are mutually
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
88a2182a1ad4fc7af07272af6b05b74db7f28e52Tinderbox User Use IPv6 only even if the host machine is capable of IPv4.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <option>-4</option> and <option>-6</option> are mutually
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
4f6469885c3d66367e3f8fb94e1f3c66115990b0Mark Andrews <!-- this is in source but not mentioned? does this matter? -->
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-c <replaceable class="parameter">config-file</replaceable></term>
4f6469885c3d66367e3f8fb94e1f3c66115990b0Mark Andrews Use <replaceable class="parameter">config-file</replaceable> as the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein configuration file instead of the default,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <!-- Should this be an absolute path name? -->
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <option>-c</option> can not be used with <option>-C</option>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-C <replaceable class="parameter">config-file</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Use <replaceable class="parameter">config-file</replaceable> as the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein configuration file instead of the default,
fc74b733bf679e1b3fb1599e32d445dffe325208Tinderbox User <option>-C</option> can not be used with <option>-c</option>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
88a2182a1ad4fc7af07272af6b05b74db7f28e52Tinderbox User <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-d <replaceable class="parameter">debug-level</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Debugging traces from <command>lwresd</command> become
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein more verbose as the debug level increases.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Run the server in the foreground (i.e. do not daemonize).
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Run the server in the foreground and force all logging
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-i <replaceable class="parameter">pid-file</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Use <replaceable class="parameter">pid-file</replaceable> as the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein PID file instead of the default,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <filename>/var/run/lwresd/lwresd.pid</filename>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-m <replaceable class="parameter">flag</replaceable></term>
68b30890ebd441a6a1ae3fdf71744d07d02cd030Mark Andrews Turn on memory usage debugging flags. Possible flags are
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <replaceable class="parameter">usage</replaceable>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <replaceable class="parameter">trace</replaceable>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <replaceable class="parameter">record</replaceable>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <replaceable class="parameter">size</replaceable>, and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <replaceable class="parameter">mctx</replaceable>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein These correspond to the ISC_MEM_DEBUGXXXX flags described in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-n <replaceable class="parameter">#cpus</replaceable></term>
47012ae6dbf18a2503d7b33c1c9583dc38625cb7Mark Andrews Create <replaceable class="parameter">#cpus</replaceable> worker threads
89bc48260b64a8859ae717e9e5bae380e275fef4Mark Andrews to take advantage of multiple CPUs. If not specified,
89bc48260b64a8859ae717e9e5bae380e275fef4Mark Andrews <command>lwresd</command> will try to determine the
89bc48260b64a8859ae717e9e5bae380e275fef4Mark Andrews number of CPUs present and create one thread per CPU.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If it is unable to determine the number of CPUs, a
79cf9524b15ca65f55fd6913e6cf01b5581c588aAutomatic Updater single worker thread will be created.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
276e28f813ffef042d5a6e9f3373ef4e2ad37996Mark Andrews <term>-P <replaceable class="parameter">port</replaceable></term>
538a83db7509d598da95a93bd7b74ef3112123a4Mark Andrews Listen for lightweight resolver queries on port
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <replaceable class="parameter">port</replaceable>. If
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein not specified, the default is port 921.
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews </varlistentry>
22c71c7b86fa57a19f7df0da4222eb8593e6ad12Mark Andrews <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-p <replaceable class="parameter">port</replaceable></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Send DNS lookups to port <replaceable class="parameter">port</replaceable>. If not
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein specified, the default is port 53. This provides a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein way of testing the lightweight resolver daemon with a
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews name server that listens for queries on a non-standard
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein port number.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews Write memory usage statistics to <filename>stdout</filename>
65ad89971ee9973074cd11c207af92bf5440df01Automatic Updater This option is mainly of interest to BIND 9 developers
65ad89971ee9973074cd11c207af92bf5440df01Automatic Updater and may be removed or changed in a future release.
65ad89971ee9973074cd11c207af92bf5440df01Automatic Updater </varlistentry>
1586d8cbac5d73031716561386f60758c6c332d5Mark Andrews <varlistentry>
1586d8cbac5d73031716561386f60758c6c332d5Mark Andrews <term>-t <replaceable class="parameter">directory</replaceable></term>
1586d8cbac5d73031716561386f60758c6c332d5Mark Andrews <para>Chroot
1586d8cbac5d73031716561386f60758c6c332d5Mark Andrews to <replaceable class="parameter">directory</replaceable> after
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein processing the command line arguments, but before
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein reading the configuration file.
68b30890ebd441a6a1ae3fdf71744d07d02cd030Mark Andrews This option should be used in conjunction with the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <option>-u</option> option, as chrooting a process
68b30890ebd441a6a1ae3fdf71744d07d02cd030Mark Andrews running as root doesn't enhance security on most
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein systems; the way <function>chroot(2)</function> is
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein defined allows a process with root privileges to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein escape a chroot jail.
43b94483957d3168796a816ed86cf097518817dcTinderbox User </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term>-u <replaceable class="parameter">user</replaceable></term>
7526edc7677371c366232de5f39a678b7dcda747Mark Andrews <para>Setuid
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein to <replaceable class="parameter">user</replaceable> after completing
d9c707589ade5d69fb59b6837555adc4cd24d34fAutomatic Updater privileged operations, such as creating sockets that
d9c707589ade5d69fb59b6837555adc4cd24d34fAutomatic Updater listen on privileged ports.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Report the version number and exit.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </variablelist>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refsection>
aeb7938001b22e811a910e1b36cdf452f9193865Automatic Updater <refsection><info><title>FILES</title></info>
aeb7938001b22e811a910e1b36cdf452f9193865Automatic Updater <variablelist>
aeb7938001b22e811a910e1b36cdf452f9193865Automatic Updater <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term><filename>/etc/resolv.conf</filename></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The default configuration file.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <varlistentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <term><filename>/var/run/lwresd.pid</filename></term>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The default process-id file.
b29285b88f95055e1f399247994067f85882041cTinderbox User </varlistentry>
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews </variablelist>
d060d8669f5558690e7faf4a1c12fe5c02a7c60dAutomatic Updater <refsection><info><title>SEE ALSO</title></info>
d060d8669f5558690e7faf4a1c12fe5c02a7c60dAutomatic Updater <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
d060d8669f5558690e7faf4a1c12fe5c02a7c60dAutomatic Updater </citerefentry>,
731cc132f22dbc9e0ecd7035dce314a61076d31bAutomatic Updater <citerefentry>
731cc132f22dbc9e0ecd7035dce314a61076d31bAutomatic Updater <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </citerefentry>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <citerefentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </citerefentry>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refsection>