1<!-- 2 - Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 - 4 - This Source Code Form is subject to the terms of the Mozilla Public 5 - License, v. 2.0. If a copy of the MPL was not distributed with this 6 - file, you can obtain one at https://mozilla.org/MPL/2.0/. 7 - 8 - See the COPYRIGHT file distributed with this work for additional 9 - information regarding copyright ownership. 10--> 11 12<!-- Converted by db4-upgrade version 1.0 --> 13<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="man.lwresd"> 14 <info> 15 <date>2009-01-20</date> 16 </info> 17 <refentryinfo> 18 <corpname>ISC</corpname> 19 <corpauthor>Internet Systems Consortium, Inc.</corpauthor> 20 </refentryinfo> 21 22 <refmeta> 23 <refentrytitle><application>lwresd</application></refentrytitle> 24 <manvolnum>8</manvolnum> 25 <refmiscinfo>BIND9</refmiscinfo> 26 </refmeta> 27 28 <refnamediv> 29 <refname><application>lwresd</application></refname> 30 <refpurpose>lightweight resolver daemon</refpurpose> 31 </refnamediv> 32 33 <docinfo> 34 <copyright> 35 <year>2000</year> 36 <year>2001</year> 37 <year>2004</year> 38 <year>2005</year> 39 <year>2007</year> 40 <year>2008</year> 41 <year>2009</year> 42 <year>2014</year> 43 <year>2015</year> 44 <year>2016</year> 45 <year>2017</year> 46 <year>2018</year> 47 <year>2019</year> 48 <year>2020</year> 49 <year>2021</year> 50 <year>2022</year> 51 <holder>Internet Systems Consortium, Inc. ("ISC")</holder> 52 </copyright> 53 </docinfo> 54 55 <refsynopsisdiv> 56 <cmdsynopsis sepchar=" "> 57 <command>lwresd</command> 58 <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">config-file</replaceable></option></arg> 59 <arg choice="opt" rep="norepeat"><option>-C <replaceable class="parameter">config-file</replaceable></option></arg> 60 <arg choice="opt" rep="norepeat"><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg> 61 <arg choice="opt" rep="norepeat"><option>-f</option></arg> 62 <arg choice="opt" rep="norepeat"><option>-g</option></arg> 63 <arg choice="opt" rep="norepeat"><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg> 64 <arg choice="opt" rep="norepeat"><option>-m <replaceable class="parameter">flag</replaceable></option></arg> 65 <arg choice="opt" rep="norepeat"><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg> 66 <arg choice="opt" rep="norepeat"><option>-P <replaceable class="parameter">port</replaceable></option></arg> 67 <arg choice="opt" rep="norepeat"><option>-p <replaceable class="parameter">port</replaceable></option></arg> 68 <arg choice="opt" rep="norepeat"><option>-s</option></arg> 69 <arg choice="opt" rep="norepeat"><option>-t <replaceable class="parameter">directory</replaceable></option></arg> 70 <arg choice="opt" rep="norepeat"><option>-u <replaceable class="parameter">user</replaceable></option></arg> 71 <arg choice="opt" rep="norepeat"><option>-v</option></arg> 72 <group choice="opt" rep="norepeat"> 73 <arg choice="opt" rep="norepeat"><option>-4</option></arg> 74 <arg choice="opt" rep="norepeat"><option>-6</option></arg> 75 </group> 76 </cmdsynopsis> 77 </refsynopsisdiv> 78 79 <refsection><info><title>DESCRIPTION</title></info> 80 81 82 <para><command>lwresd</command> 83 is the daemon providing name lookup 84 services to clients that use the BIND 9 lightweight resolver 85 library. It is essentially a stripped-down, caching-only name 86 server that answers queries using the BIND 9 lightweight 87 resolver protocol rather than the DNS protocol. 88 </para> 89 90 <para><command>lwresd</command> 91 listens for resolver queries on a 92 UDP port on the IPv4 loopback interface, 127.0.0.1. This 93 means that <command>lwresd</command> can only be used by 94 processes running on the local machine. By default, UDP port 95 number 921 is used for lightweight resolver requests and 96 responses. 97 </para> 98 <para> 99 Incoming lightweight resolver requests are decoded by the 100 server which then resolves them using the DNS protocol. When 101 the DNS lookup completes, <command>lwresd</command> encodes 102 the answers in the lightweight resolver format and returns 103 them to the client that made the request. 104 </para> 105 <para> 106 If <filename>/etc/resolv.conf</filename> contains any 107 <option>nameserver</option> entries, <command>lwresd</command> 108 sends recursive DNS queries to those servers. This is similar 109 to the use of forwarders in a caching name server. If no 110 <option>nameserver</option> entries are present, or if 111 forwarding fails, <command>lwresd</command> resolves the 112 queries autonomously starting at the root name servers, using 113 a built-in list of root server hints. 114 </para> 115 </refsection> 116 117 <refsection><info><title>OPTIONS</title></info> 118 119 120 <variablelist> 121 122 <varlistentry> 123 <term>-4</term> 124 <listitem> 125 <para> 126 Use IPv4 only even if the host machine is capable of IPv6. 127 <option>-4</option> and <option>-6</option> are mutually 128 exclusive. 129 </para> 130 </listitem> 131 </varlistentry> 132 133 <varlistentry> 134 <term>-6</term> 135 <listitem> 136 <para> 137 Use IPv6 only even if the host machine is capable of IPv4. 138 <option>-4</option> and <option>-6</option> are mutually 139 exclusive. 140 </para> 141 </listitem> 142 </varlistentry> 143 144 <!-- this is in source but not mentioned? does this matter? --> 145 <varlistentry> 146 <term>-c <replaceable class="parameter">config-file</replaceable></term> 147 <listitem> 148 <para> 149 Use <replaceable class="parameter">config-file</replaceable> as the 150 configuration file instead of the default, 151 <filename>/etc/lwresd.conf</filename>. 152 <!-- Should this be an absolute path name? --> 153 <option>-c</option> can not be used with <option>-C</option>. 154 </para> 155 </listitem> 156 </varlistentry> 157 158 <varlistentry> 159 <term>-C <replaceable class="parameter">config-file</replaceable></term> 160 <listitem> 161 <para> 162 Use <replaceable class="parameter">config-file</replaceable> as the 163 configuration file instead of the default, 164 <filename>/etc/resolv.conf</filename>. 165 <option>-C</option> can not be used with <option>-c</option>. 166 </para> 167 </listitem> 168 </varlistentry> 169 170 <varlistentry> 171 <term>-d <replaceable class="parameter">debug-level</replaceable></term> 172 <listitem> 173 <para> 174 Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>. 175 Debugging traces from <command>lwresd</command> become 176 more verbose as the debug level increases. 177 </para> 178 </listitem> 179 </varlistentry> 180 181 <varlistentry> 182 <term>-f</term> 183 <listitem> 184 <para> 185 Run the server in the foreground (i.e. do not daemonize). 186 </para> 187 </listitem> 188 </varlistentry> 189 190 <varlistentry> 191 <term>-g</term> 192 <listitem> 193 <para> 194 Run the server in the foreground and force all logging 195 to <filename>stderr</filename>. 196 </para> 197 </listitem> 198 </varlistentry> 199 200 <varlistentry> 201 <term>-i <replaceable class="parameter">pid-file</replaceable></term> 202 <listitem> 203 <para> 204 Use <replaceable class="parameter">pid-file</replaceable> as the 205 PID file instead of the default, 206 <filename>/var/run/lwresd/lwresd.pid</filename>. 207 </para> 208 </listitem> 209 </varlistentry> 210 211 <varlistentry> 212 <term>-m <replaceable class="parameter">flag</replaceable></term> 213 <listitem> 214 <para> 215 Turn on memory usage debugging flags. Possible flags are 216 <replaceable class="parameter">usage</replaceable>, 217 <replaceable class="parameter">trace</replaceable>, 218 <replaceable class="parameter">record</replaceable>, 219 <replaceable class="parameter">size</replaceable>, and 220 <replaceable class="parameter">mctx</replaceable>. 221 These correspond to the ISC_MEM_DEBUGXXXX flags described in 222 <filename><isc/mem.h></filename>. 223 </para> 224 </listitem> 225 </varlistentry> 226 227 <varlistentry> 228 <term>-n <replaceable class="parameter">#cpus</replaceable></term> 229 <listitem> 230 <para> 231 Create <replaceable class="parameter">#cpus</replaceable> worker threads 232 to take advantage of multiple CPUs. If not specified, 233 <command>lwresd</command> will try to determine the 234 number of CPUs present and create one thread per CPU. 235 If it is unable to determine the number of CPUs, a 236 single worker thread will be created. 237 </para> 238 </listitem> 239 </varlistentry> 240 241 <varlistentry> 242 <term>-P <replaceable class="parameter">port</replaceable></term> 243 <listitem> 244 <para> 245 Listen for lightweight resolver queries on port 246 <replaceable class="parameter">port</replaceable>. If 247 not specified, the default is port 921. 248 </para> 249 </listitem> 250 </varlistentry> 251 252 <varlistentry> 253 <term>-p <replaceable class="parameter">port</replaceable></term> 254 <listitem> 255 <para> 256 Send DNS lookups to port <replaceable class="parameter">port</replaceable>. If not 257 specified, the default is port 53. This provides a 258 way of testing the lightweight resolver daemon with a 259 name server that listens for queries on a non-standard 260 port number. 261 </para> 262 </listitem> 263 </varlistentry> 264 265 <varlistentry> 266 <term>-s</term> 267 <listitem> 268 <para> 269 Write memory usage statistics to <filename>stdout</filename> 270 on exit. 271 </para> 272 <note> 273 <para> 274 This option is mainly of interest to BIND 9 developers 275 and may be removed or changed in a future release. 276 </para> 277 </note> 278 </listitem> 279 </varlistentry> 280 281 <varlistentry> 282 <term>-t <replaceable class="parameter">directory</replaceable></term> 283 <listitem> 284 <para>Chroot 285 to <replaceable class="parameter">directory</replaceable> after 286 processing the command line arguments, but before 287 reading the configuration file. 288 </para> 289 <warning> 290 <para> 291 This option should be used in conjunction with the 292 <option>-u</option> option, as chrooting a process 293 running as root doesn't enhance security on most 294 systems; the way <function>chroot(2)</function> is 295 defined allows a process with root privileges to 296 escape a chroot jail. 297 </para> 298 </warning> 299 </listitem> 300 </varlistentry> 301 302 <varlistentry> 303 <term>-u <replaceable class="parameter">user</replaceable></term> 304 <listitem> 305 <para>Setuid 306 to <replaceable class="parameter">user</replaceable> after completing 307 privileged operations, such as creating sockets that 308 listen on privileged ports. 309 </para> 310 </listitem> 311 </varlistentry> 312 313 <varlistentry> 314 <term>-v</term> 315 <listitem> 316 <para> 317 Report the version number and exit. 318 </para> 319 </listitem> 320 </varlistentry> 321 322 </variablelist> 323 324 </refsection> 325 326 <refsection><info><title>FILES</title></info> 327 328 329 <variablelist> 330 331 <varlistentry> 332 <term><filename>/etc/resolv.conf</filename></term> 333 <listitem> 334 <para> 335 The default configuration file. 336 </para> 337 </listitem> 338 </varlistentry> 339 340 <varlistentry> 341 <term><filename>/var/run/lwresd.pid</filename></term> 342 <listitem> 343 <para> 344 The default process-id file. 345 </para> 346 </listitem> 347 </varlistentry> 348 349 </variablelist> 350 351 </refsection> 352 353 <refsection><info><title>SEE ALSO</title></info> 354 355 <para><citerefentry> 356 <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum> 357 </citerefentry>, 358 <citerefentry> 359 <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> 360 </citerefentry>, 361 <citerefentry> 362 <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum> 363 </citerefentry>. 364 </para> 365 </refsection> 366 367</refentry> 368