contrib/bind-9.2.4rc7/bin/named/lwresd.html

   1 <!--
   2  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2000, 2001  Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and distribute this software for any
   6  - purpose with or without fee is hereby granted, provided that the above
   7  - copyright notice and this permission notice appear in all copies.
   8  -
   9  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  - PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17
  18 <!-- $Id: lwresd.html,v 1.4.2.3 2004/06/03 05:21:13 marka Exp $ -->
  19
  20 <HTML
  21 ><HEAD
  22 ><TITLE
  23 >lwresd</TITLE
  24 ><META
  25 NAME="GENERATOR"
  26 CONTENT="Modular DocBook HTML Stylesheet Version 1.73
  27 "></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 BGCOLOR="#FFFFFF"
  31 TEXT="#000000"
  32 LINK="#0000FF"
  33 VLINK="#840084"
  34 ALINK="#0000FF"
  35 ><H1
  36 ><A
  37 NAME="AEN1"
  38 ><SPAN
  39 CLASS="APPLICATION"
  40 >lwresd</SPAN
  41 ></A
  42 ></H1
  43 ><DIV
  44 CLASS="REFNAMEDIV"
  45 ><A
  46 NAME="AEN9"
  47 ></A
  48 ><H2
  49 >Name</H2
  50 ><SPAN
  51 CLASS="APPLICATION"
  52 >lwresd</SPAN
  53 >&nbsp;--&nbsp;lightweight resolver daemon</DIV
  54 ><DIV
  55 CLASS="REFSYNOPSISDIV"
  56 ><A
  57 NAME="AEN13"
  58 ></A
  59 ><H2
  60 >Synopsis</H2
  61 ><P
  62 ><B
  63 CLASS="COMMAND"
  64 >lwresd</B
  65 >  [<TT
  66 CLASS="OPTION"
  67 >-C <TT
  68 CLASS="REPLACEABLE"
  69 ><I
  70 >config-file</I
  71 ></TT
  72 ></TT
  73 >] [<TT
  74 CLASS="OPTION"
  75 >-d <TT
  76 CLASS="REPLACEABLE"
  77 ><I
  78 >debug-level</I
  79 ></TT
  80 ></TT
  81 >] [<TT
  82 CLASS="OPTION"
  83 >-f</TT
  84 >] [<TT
  85 CLASS="OPTION"
  86 >-g</TT
  87 >] [<TT
  88 CLASS="OPTION"
  89 >-i <TT
  90 CLASS="REPLACEABLE"
  91 ><I
  92 >pid-file</I
  93 ></TT
  94 ></TT
  95 >] [<TT
  96 CLASS="OPTION"
  97 >-n <TT
  98 CLASS="REPLACEABLE"
  99 ><I
 100 >#cpus</I
 101 ></TT
 102 ></TT
 103 >] [<TT
 104 CLASS="OPTION"
 105 >-P <TT
 106 CLASS="REPLACEABLE"
 107 ><I
 108 >port</I
 109 ></TT
 110 ></TT
 111 >] [<TT
 112 CLASS="OPTION"
 113 >-p <TT
 114 CLASS="REPLACEABLE"
 115 ><I
 116 >port</I
 117 ></TT
 118 ></TT
 119 >] [<TT
 120 CLASS="OPTION"
 121 >-s</TT
 122 >] [<TT
 123 CLASS="OPTION"
 124 >-t <TT
 125 CLASS="REPLACEABLE"
 126 ><I
 127 >directory</I
 128 ></TT
 129 ></TT
 130 >] [<TT
 131 CLASS="OPTION"
 132 >-u <TT
 133 CLASS="REPLACEABLE"
 134 ><I
 135 >user</I
 136 ></TT
 137 ></TT
 138 >] [<TT
 139 CLASS="OPTION"
 140 >-v</TT
 141 >]</P
 142 ></DIV
 143 ><DIV
 144 CLASS="REFSECT1"
 145 ><A
 146 NAME="AEN48"
 147 ></A
 148 ><H2
 149 >DESCRIPTION</H2
 150 ><P
 151 >       <B
 152 CLASS="COMMAND"
 153 >lwresd</B
 154 > is the daemon providing name lookup
 155         services to clients that use the BIND 9 lightweight resolver
 156         library.  It is essentially a stripped-down, caching-only name
 157         server that answers queries using the BIND 9 lightweight
 158         resolver protocol rather than the DNS protocol.
 159     </P
 160 ><P
 161 >       <B
 162 CLASS="COMMAND"
 163 >lwresd</B
 164 > listens for resolver queries on a
 165         UDP port on the IPv4 loopback interface, 127.0.0.1.  This
 166         means that <B
 167 CLASS="COMMAND"
 168 >lwresd</B
 169 > can only be used by
 170         processes running on the local machine.  By default UDP port
 171         number 921 is used for lightweight resolver requests and
 172         responses.
 173     </P
 174 ><P
 175 >       Incoming lightweight resolver requests are decoded by the
 176         server which then resolves them using the DNS protocol.  When
 177         the DNS lookup completes, <B
 178 CLASS="COMMAND"
 179 >lwresd</B
 180 > encodes
 181         the answers in the lightweight resolver format and returns
 182         them to the client that made the request.
 183     </P
 184 ><P
 185 >       If <TT
 186 CLASS="FILENAME"
 187 >/etc/resolv.conf</TT
 188 > contains any
 189         <TT
 190 CLASS="OPTION"
 191 >nameserver</TT
 192 > entries, <B
 193 CLASS="COMMAND"
 194 >lwresd</B
 195 >
 196         sends recursive DNS queries to those servers.  This is similar
 197         to the use of forwarders in a caching name server.  If no
 198         <TT
 199 CLASS="OPTION"
 200 >nameserver</TT
 201 > entries are present, or if
 202         forwarding fails, <B
 203 CLASS="COMMAND"
 204 >lwresd</B
 205 > resolves the
 206         queries autonomously starting at the root name servers, using
 207         a built-in list of root server hints.
 208     </P
 209 ></DIV
 210 ><DIV
 211 CLASS="REFSECT1"
 212 ><A
 213 NAME="AEN63"
 214 ></A
 215 ><H2
 216 >OPTIONS</H2
 217 ><P
 218 ></P
 219 ><DIV
 220 CLASS="VARIABLELIST"
 221 ><DL
 222 ><DT
 223 >-C <TT
 224 CLASS="REPLACEABLE"
 225 ><I
 226 >config-file</I
 227 ></TT
 228 ></DT
 229 ><DD
 230 ><P
 231 >               Use <TT
 232 CLASS="REPLACEABLE"
 233 ><I
 234 >config-file</I
 235 ></TT
 236 > as the
 237                 configuration file instead of the default,
 238                 <TT
 239 CLASS="FILENAME"
 240 >/etc/resolv.conf</TT
 241 >.
 242           </P
 243 ></DD
 244 ><DT
 245 >-d <TT
 246 CLASS="REPLACEABLE"
 247 ><I
 248 >debug-level</I
 249 ></TT
 250 ></DT
 251 ><DD
 252 ><P
 253 >               Set the daemon's debug level to <TT
 254 CLASS="REPLACEABLE"
 255 ><I
 256 >debug-level</I
 257 ></TT
 258 >.
 259                 Debugging traces from <B
 260 CLASS="COMMAND"
 261 >lwresd</B
 262 > become
 263                 more verbose as the debug level increases.
 264           </P
 265 ></DD
 266 ><DT
 267 >-f</DT
 268 ><DD
 269 ><P
 270 >               Run the server in the foreground (i.e. do not daemonize).
 271           </P
 272 ></DD
 273 ><DT
 274 >-g</DT
 275 ><DD
 276 ><P
 277 >               Run the server in the foreground and force all logging
 278                 to <TT
 279 CLASS="FILENAME"
 280 >stderr</TT
 281 >.
 282           </P
 283 ></DD
 284 ><DT
 285 >-n <TT
 286 CLASS="REPLACEABLE"
 287 ><I
 288 >#cpus</I
 289 ></TT
 290 ></DT
 291 ><DD
 292 ><P
 293 >               Create <TT
 294 CLASS="REPLACEABLE"
 295 ><I
 296 >#cpus</I
 297 ></TT
 298 > worker threads
 299                 to take advantage of multiple CPUs.  If not specified,
 300                 <B
 301 CLASS="COMMAND"
 302 >lwresd</B
 303 > will try to determine the
 304                 number of CPUs present and create one thread per CPU.
 305                 If it is unable to determine the number of CPUs, a
 306                 single worker thread will be created.
 307           </P
 308 ></DD
 309 ><DT
 310 >-P <TT
 311 CLASS="REPLACEABLE"
 312 ><I
 313 >port</I
 314 ></TT
 315 ></DT
 316 ><DD
 317 ><P
 318 >               Listen for lightweight resolver queries on port
 319                 <TT
 320 CLASS="REPLACEABLE"
 321 ><I
 322 >port</I
 323 ></TT
 324 >.  If
 325                 not specified, the default is port 921.
 326           </P
 327 ></DD
 328 ><DT
 329 >-p <TT
 330 CLASS="REPLACEABLE"
 331 ><I
 332 >port</I
 333 ></TT
 334 ></DT
 335 ><DD
 336 ><P
 337 >               Send DNS lookups to port <TT
 338 CLASS="REPLACEABLE"
 339 ><I
 340 >port</I
 341 ></TT
 342 >.  If not
 343                 specified, the default is port 53.  This provides a
 344                 way of testing the lightweight resolver daemon with a
 345                 name server that listens for queries on a non-standard
 346                 port number.
 347           </P
 348 ></DD
 349 ><DT
 350 >-s</DT
 351 ><DD
 352 ><P
 353 >               Write memory usage statistics to <TT
 354 CLASS="FILENAME"
 355 >stdout</TT
 356 >
 357                 on exit.
 358           </P
 359 ><DIV
 360 CLASS="NOTE"
 361 ><BLOCKQUOTE
 362 CLASS="NOTE"
 363 ><P
 364 ><B
 365 >Note: </B
 366 >               This option is mainly of interest to BIND 9 developers
 367                 and may be removed or changed in a future release.
 368             </P
 369 ></BLOCKQUOTE
 370 ></DIV
 371 ></DD
 372 ><DT
 373 >-t <TT
 374 CLASS="REPLACEABLE"
 375 ><I
 376 >directory</I
 377 ></TT
 378 ></DT
 379 ><DD
 380 ><P
 381 >               <TT
 382 CLASS="FUNCTION"
 383 >chroot()</TT
 384 > to <TT
 385 CLASS="REPLACEABLE"
 386 ><I
 387 >directory</I
 388 ></TT
 389 > after
 390                 processing the command line arguments, but before
 391                 reading the configuration file.
 392           </P
 393 ><DIV
 394 CLASS="WARNING"
 395 ><P
 396 ></P
 397 ><TABLE
 398 CLASS="WARNING"
 399 BORDER="1"
 400 WIDTH="90%"
 401 ><TR
 402 ><TD
 403 ALIGN="CENTER"
 404 ><B
 405 >Warning</B
 406 ></TD
 407 ></TR
 408 ><TR
 409 ><TD
 410 ALIGN="LEFT"
 411 ><P
 412 >               This option should be used in conjunction with the
 413                 <TT
 414 CLASS="OPTION"
 415 >-u</TT
 416 > option, as chrooting a process
 417                 running as root doesn't enhance security on most
 418                 systems; the way <TT
 419 CLASS="FUNCTION"
 420 >chroot()</TT
 421 > is
 422                 defined allows a process with root privileges to
 423                 escape a chroot jail.
 424             </P
 425 ></TD
 426 ></TR
 427 ></TABLE
 428 ></DIV
 429 ></DD
 430 ><DT
 431 >-u <TT
 432 CLASS="REPLACEABLE"
 433 ><I
 434 >user</I
 435 ></TT
 436 ></DT
 437 ><DD
 438 ><P
 439 >               <TT
 440 CLASS="FUNCTION"
 441 >setuid()</TT
 442 > to <TT
 443 CLASS="REPLACEABLE"
 444 ><I
 445 >user</I
 446 ></TT
 447 > after completing
 448                 privileged operations, such as creating sockets that
 449                 listen on privileged ports.
 450           </P
 451 ></DD
 452 ><DT
 453 >-v</DT
 454 ><DD
 455 ><P
 456 >               Report the version number and exit.
 457           </P
 458 ></DD
 459 ></DL
 460 ></DIV
 461 ></DIV
 462 ><DIV
 463 CLASS="REFSECT1"
 464 ><A
 465 NAME="AEN137"
 466 ></A
 467 ><H2
 468 >FILES</H2
 469 ><P
 470 ></P
 471 ><DIV
 472 CLASS="VARIABLELIST"
 473 ><DL
 474 ><DT
 475 ><TT
 476 CLASS="FILENAME"
 477 >/etc/resolv.conf</TT
 478 ></DT
 479 ><DD
 480 ><P
 481 >               The default configuration file.
 482           </P
 483 ></DD
 484 ><DT
 485 ><TT
 486 CLASS="FILENAME"
 487 >/var/run/lwresd.pid</TT
 488 ></DT
 489 ><DD
 490 ><P
 491 >               The default process-id file.
 492           </P
 493 ></DD
 494 ></DL
 495 ></DIV
 496 ></DIV
 497 ><DIV
 498 CLASS="REFSECT1"
 499 ><A
 500 NAME="AEN150"
 501 ></A
 502 ><H2
 503 >SEE ALSO</H2
 504 ><P
 505 >       <SPAN
 506 CLASS="CITEREFENTRY"
 507 ><SPAN
 508 CLASS="REFENTRYTITLE"
 509 >named</SPAN
 510 >(8)</SPAN
 511 >,
 512         <SPAN
 513 CLASS="CITEREFENTRY"
 514 ><SPAN
 515 CLASS="REFENTRYTITLE"
 516 >lwres</SPAN
 517 >(3)</SPAN
 518 >,
 519         <SPAN
 520 CLASS="CITEREFENTRY"
 521 ><SPAN
 522 CLASS="REFENTRYTITLE"
 523 >resolver</SPAN
 524 >(5)</SPAN
 525 >.
 526     </P
 527 ></DIV
 528 ><DIV
 529 CLASS="REFSECT1"
 530 ><A
 531 NAME="AEN162"
 532 ></A
 533 ><H2
 534 >AUTHOR</H2
 535 ><P
 536 >       Internet Systems Consortium
 537     </P
 538 ></DIV
 539 ></BODY
 540 ></HTML
 541 >