lwresd.docbook revision 153816
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" 2 "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" 3 [<!ENTITY mdash "—">]> 4<!-- 5 - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") 6 - Copyright (C) 2000, 2001 Internet Software Consortium. 7 - 8 - Permission to use, copy, modify, and distribute this software for any 9 - purpose with or without fee is hereby granted, provided that the above 10 - copyright notice and this permission notice appear in all copies. 11 - 12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 14 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 18 - PERFORMANCE OF THIS SOFTWARE. 19--> 20 21<!-- $Id: lwresd.docbook,v 1.6.208.4 2005/05/13 01:22:33 marka Exp $ --> 22 23<refentry> 24 <refentryinfo> 25 <date>June 30, 2000</date> 26 </refentryinfo> 27 28 <refmeta> 29 <refentrytitle><application>lwresd</application></refentrytitle> 30 <manvolnum>8</manvolnum> 31 <refmiscinfo>BIND9</refmiscinfo> 32 </refmeta> 33 34 <docinfo> 35 <copyright> 36 <year>2004</year> 37 <year>2005</year> 38 <holder>Internet Systems Consortium, Inc. ("ISC")</holder> 39 </copyright> 40 <copyright> 41 <year>2000</year> 42 <year>2001</year> 43 <holder>Internet Software Consortium.</holder> 44 </copyright> 45 </docinfo> 46 47 <refnamediv> 48 <refname><application>lwresd</application></refname> 49 <refpurpose>lightweight resolver daemon</refpurpose> 50 </refnamediv> 51 52 <refsynopsisdiv> 53 <cmdsynopsis> 54 <command>lwresd</command> 55 <arg><option>-C <replaceable class="parameter">config-file</replaceable></option></arg> 56 <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg> 57 <arg><option>-f</option></arg> 58 <arg><option>-g</option></arg> 59 <arg><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg> 60 <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg> 61 <arg><option>-P <replaceable class="parameter">port</replaceable></option></arg> 62 <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg> 63 <arg><option>-s</option></arg> 64 <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg> 65 <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg> 66 <arg><option>-v</option></arg> 67 </cmdsynopsis> 68 </refsynopsisdiv> 69 70 <refsect1> 71 <title>DESCRIPTION</title> 72 <para> 73 <command>lwresd</command> is the daemon providing name lookup 74 services to clients that use the BIND 9 lightweight resolver 75 library. It is essentially a stripped-down, caching-only name 76 server that answers queries using the BIND 9 lightweight 77 resolver protocol rather than the DNS protocol. 78 </para> 79 <para> 80 <command>lwresd</command> listens for resolver queries on a 81 UDP port on the IPv4 loopback interface, 127.0.0.1. This 82 means that <command>lwresd</command> can only be used by 83 processes running on the local machine. By default UDP port 84 number 921 is used for lightweight resolver requests and 85 responses. 86 </para> 87 <para> 88 Incoming lightweight resolver requests are decoded by the 89 server which then resolves them using the DNS protocol. When 90 the DNS lookup completes, <command>lwresd</command> encodes 91 the answers in the lightweight resolver format and returns 92 them to the client that made the request. 93 </para> 94 <para> 95 If <filename>/etc/resolv.conf</filename> contains any 96 <option>nameserver</option> entries, <command>lwresd</command> 97 sends recursive DNS queries to those servers. This is similar 98 to the use of forwarders in a caching name server. If no 99 <option>nameserver</option> entries are present, or if 100 forwarding fails, <command>lwresd</command> resolves the 101 queries autonomously starting at the root name servers, using 102 a built-in list of root server hints. 103 </para> 104 </refsect1> 105 106 <refsect1> 107 <title>OPTIONS</title> 108 109 <variablelist> 110 <varlistentry> 111 <term>-C <replaceable class="parameter">config-file</replaceable></term> 112 <listitem> 113 <para> 114 Use <replaceable 115 class="parameter">config-file</replaceable> as the 116 configuration file instead of the default, 117 <filename>/etc/resolv.conf</filename>. 118 </para> 119 </listitem> 120 </varlistentry> 121 122 <varlistentry> 123 <term>-d <replaceable class="parameter">debug-level</replaceable></term> 124 <listitem> 125 <para> 126 Set the daemon's debug level to <replaceable 127 class="parameter">debug-level</replaceable>. 128 Debugging traces from <command>lwresd</command> become 129 more verbose as the debug level increases. 130 </para> 131 </listitem> 132 </varlistentry> 133 134 <varlistentry> 135 <term>-f</term> 136 <listitem> 137 <para> 138 Run the server in the foreground (i.e. do not daemonize). 139 </para> 140 </listitem> 141 </varlistentry> 142 143 <varlistentry> 144 <term>-g</term> 145 <listitem> 146 <para> 147 Run the server in the foreground and force all logging 148 to <filename>stderr</filename>. 149 </para> 150 </listitem> 151 </varlistentry> 152 153 <varlistentry> 154 <term>-n <replaceable class="parameter">#cpus</replaceable></term> 155 <listitem> 156 <para> 157 Create <replaceable 158 class="parameter">#cpus</replaceable> worker threads 159 to take advantage of multiple CPUs. If not specified, 160 <command>lwresd</command> will try to determine the 161 number of CPUs present and create one thread per CPU. 162 If it is unable to determine the number of CPUs, a 163 single worker thread will be created. 164 </para> 165 </listitem> 166 </varlistentry> 167 168 <varlistentry> 169 <term>-P <replaceable class="parameter">port</replaceable></term> 170 <listitem> 171 <para> 172 Listen for lightweight resolver queries on port 173 <replaceable class="parameter">port</replaceable>. If 174 not specified, the default is port 921. 175 </para> 176 </listitem> 177 </varlistentry> 178 179 <varlistentry> 180 <term>-p <replaceable class="parameter">port</replaceable></term> 181 <listitem> 182 <para> 183 Send DNS lookups to port <replaceable 184 class="parameter">port</replaceable>. If not 185 specified, the default is port 53. This provides a 186 way of testing the lightweight resolver daemon with a 187 name server that listens for queries on a non-standard 188 port number. 189 </para> 190 </listitem> 191 </varlistentry> 192 193 <varlistentry> 194 <term>-s</term> 195 <listitem> 196 <para> 197 Write memory usage statistics to <filename>stdout</filename> 198 on exit. 199 </para> 200 <note> 201 <para> 202 This option is mainly of interest to BIND 9 developers 203 and may be removed or changed in a future release. 204 </para> 205 </note> 206 </listitem> 207 </varlistentry> 208 209 <varlistentry> 210 <term>-t <replaceable class="parameter">directory</replaceable></term> 211 <listitem> 212 <para> 213 <function>chroot()</function> to <replaceable 214 class="parameter">directory</replaceable> after 215 processing the command line arguments, but before 216 reading the configuration file. 217 </para> 218 <warning> 219 <para> 220 This option should be used in conjunction with the 221 <option>-u</option> option, as chrooting a process 222 running as root doesn't enhance security on most 223 systems; the way <function>chroot()</function> is 224 defined allows a process with root privileges to 225 escape a chroot jail. 226 </para> 227 </warning> 228 </listitem> 229 </varlistentry> 230 231 <varlistentry> 232 <term>-u <replaceable class="parameter">user</replaceable></term> 233 <listitem> 234 <para> 235 <function>setuid()</function> to <replaceable 236 class="parameter">user</replaceable> after completing 237 privileged operations, such as creating sockets that 238 listen on privileged ports. 239 </para> 240 </listitem> 241 </varlistentry> 242 243 <varlistentry> 244 <term>-v</term> 245 <listitem> 246 <para> 247 Report the version number and exit. 248 </para> 249 </listitem> 250 </varlistentry> 251 252 </variablelist> 253 254 </refsect1> 255 256 <refsect1> 257 <title>FILES</title> 258 259 <variablelist> 260 261 <varlistentry> 262 <term><filename>/etc/resolv.conf</filename></term> 263 <listitem> 264 <para> 265 The default configuration file. 266 </para> 267 </listitem> 268 </varlistentry> 269 270 <varlistentry> 271 <term><filename>/var/run/lwresd.pid</filename></term> 272 <listitem> 273 <para> 274 The default process-id file. 275 </para> 276 </listitem> 277 </varlistentry> 278 279 </variablelist> 280 281 </refsect1> 282 283 <refsect1> 284 <title>SEE ALSO</title> 285 <para> 286 <citerefentry> 287 <refentrytitle>named</refentrytitle> 288 <manvolnum>8</manvolnum> 289 </citerefentry>, 290 <citerefentry> 291 <refentrytitle>lwres</refentrytitle> 292 <manvolnum>3</manvolnum> 293 </citerefentry>, 294 <citerefentry> 295 <refentrytitle>resolver</refentrytitle> 296 <manvolnum>5</manvolnum> 297 </citerefentry>. 298 </para> 299 </refsect1> 300 301 <refsect1> 302 <title>AUTHOR</title> 303 <para> 304 <corpauthor>Internet Systems Consortium</corpauthor> 305 </para> 306 </refsect1> 307 308</refentry> 309 310 311<!-- 312 - Local variables: 313 - mode: sgml 314 - End: 315--> 316