/contrib/bind9/bin/named/lwresd.html

https://bitbucket.org/freebsd/freebsd-head/ · HTML · 225 lines · 207 code · 1 blank · 17 comment · 0 complexity · b7a73d22a11cca50b2e5e6ac602a5741 MD5 · raw file 

    

  1. <!--
    2. 

  2.  - Copyright (C) 2004, 2005, 2007-2009 Internet Systems Consortium, Inc. ("ISC")
    3. 

  3.  - Copyright (C) 2000, 2001 Internet Software Consortium.
    4. 

  4.  - 
    5. 

  5.  - Permission to use, copy, modify, and/or distribute this software for any
    6. 

  6.  - purpose with or without fee is hereby granted, provided that the above
    7. 

  7.  - copyright notice and this permission notice appear in all copies.
    8. 

  8.  - 
    9. 

  9.  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
    10. 

  10.  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
    11. 

  11.  - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
    12. 

  12.  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
    13. 

  13.  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
    14. 

  14.  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
    15. 

  15.  - PERFORMANCE OF THIS SOFTWARE.
    16. 

  16. -->
    17. 

  17. <!-- $Id$ -->
    18. 

  18. <html>
    19. 

  19. <head>
    20. 

  20. <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
    21. 

  21. <title>lwresd</title>
    22. 

  22. <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
    23. 

  23. </head>
    24. 

  24. <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
    25. 

  25. <a name="id2476274"></a><div class="titlepage"></div>
    26. 

  26. <div class="refnamediv">
    27. 

  27. <h2>Name</h2>
    28. 

  28. <p><span class="application">lwresd</span> &#8212; lightweight resolver daemon</p>
    29. 

  29. </div>
    30. 

  30. <div class="refsynopsisdiv">
    31. 

  31. <h2>Synopsis</h2>
    32. 

  32. <div class="cmdsynopsis"><p><code class="command">lwresd</code>  [<code class="option">-c <em class="replaceable"><code>config-file</code></em></code>] [<code class="option">-C <em class="replaceable"><code>config-file</code></em></code>] [<code class="option">-d <em class="replaceable"><code>debug-level</code></em></code>] [<code class="option">-f</code>] [<code class="option">-g</code>] [<code class="option">-i <em class="replaceable"><code>pid-file</code></em></code>] [<code class="option">-m <em class="replaceable"><code>flag</code></em></code>] [<code class="option">-n <em class="replaceable"><code>#cpus</code></em></code>] [<code class="option">-P <em class="replaceable"><code>port</code></em></code>] [<code class="option">-p <em class="replaceable"><code>port</code></em></code>] [<code class="option">-s</code>] [<code class="option">-t <em class="replaceable"><code>directory</code></em></code>] [<code class="option">-u <em class="replaceable"><code>user</code></em></code>] [<code class="option">-v</code>] [<code class="option">-4</code>] [<code class="option">-6</code>]</p></div>
    33. 

  33. </div>
    34. 

  34. <div class="refsect1" lang="en">
    35. 

  35. <a name="id2543469"></a><h2>DESCRIPTION</h2>
    36. 

  36. <p><span><strong class="command">lwresd</strong></span>
    37. 

  37.       is the daemon providing name lookup
    38. 

  38.       services to clients that use the BIND 9 lightweight resolver
    39. 

  39.       library.  It is essentially a stripped-down, caching-only name
    40. 

  40.       server that answers queries using the BIND 9 lightweight
    41. 

  41.       resolver protocol rather than the DNS protocol.
    42. 

  42.     </p>
    43. 

  43. <p><span><strong class="command">lwresd</strong></span> 
    44. 

  44.       listens for resolver queries on a
    45. 

  45.       UDP port on the IPv4 loopback interface, 127.0.0.1.  This
    46. 

  46.       means that <span><strong class="command">lwresd</strong></span> can only be used by
    47. 

  47.       processes running on the local machine.  By default, UDP port
    48. 

  48.       number 921 is used for lightweight resolver requests and
    49. 

  49.       responses.
    50. 

  50.     </p>
    51. 

  51. <p>
    52. 

  52.       Incoming lightweight resolver requests are decoded by the
    53. 

  53.       server which then resolves them using the DNS protocol.  When
    54. 

  54.       the DNS lookup completes, <span><strong class="command">lwresd</strong></span> encodes
    55. 

  55.       the answers in the lightweight resolver format and returns
    56. 

  56.       them to the client that made the request.
    57. 

  57.     </p>
    58. 

  58. <p>
    59. 

  59.       If <code class="filename">/etc/resolv.conf</code> contains any
    60. 

  60.       <code class="option">nameserver</code> entries, <span><strong class="command">lwresd</strong></span>
    61. 

  61.       sends recursive DNS queries to those servers.  This is similar
    62. 

  62.       to the use of forwarders in a caching name server.  If no
    63. 

  63.       <code class="option">nameserver</code> entries are present, or if
    64. 

  64.       forwarding fails, <span><strong class="command">lwresd</strong></span> resolves the
    65. 

  65.       queries autonomously starting at the root name servers, using
    66. 

  66.       a built-in list of root server hints.
    67. 

  67.     </p>
    68. 

  68. </div>
    69. 

  69. <div class="refsect1" lang="en">
    70. 

  70. <a name="id2543516"></a><h2>OPTIONS</h2>
    71. 

  71. <div class="variablelist"><dl>
    72. 

  72. <dt><span class="term">-4</span></dt>
    73. 

  73. <dd><p>
    74. 

  74.             Use IPv4 only even if the host machine is capable of IPv6.
    75. 

  75.             <code class="option">-4</code> and <code class="option">-6</code> are mutually
    76. 

  76.             exclusive.
    77. 

  77.           </p></dd>
    78. 

  78. <dt><span class="term">-6</span></dt>
    79. 

  79. <dd><p>
    80. 

  80.             Use IPv6 only even if the host machine is capable of IPv4.
    81. 

  81.             <code class="option">-4</code> and <code class="option">-6</code> are mutually
    82. 

  82.             exclusive.
    83. 

  83.           </p></dd>
    84. 

  84. <dt><span class="term">-c <em class="replaceable"><code>config-file</code></em></span></dt>
    85. 

  85. <dd><p>
    86. 

  86.             Use <em class="replaceable"><code>config-file</code></em> as the
    87. 

  87.             configuration file instead of the default,
    88. 

  88.             <code class="filename">/etc/lwresd.conf</code>.
    89. 

  89. 	    
    90. 

  90. 	    <code class="option">-c</code> can not be used with <code class="option">-C</code>.
    91. 

  91.           </p></dd>
    92. 

  92. <dt><span class="term">-C <em class="replaceable"><code>config-file</code></em></span></dt>
    93. 

  93. <dd><p>
    94. 

  94.             Use <em class="replaceable"><code>config-file</code></em> as the
    95. 

  95.             configuration file instead of the default,
    96. 

  96.             <code class="filename">/etc/resolv.conf</code>.
    97. 

  97. 	    <code class="option">-C</code> can not be used with <code class="option">-c</code>.
    98. 

  98.           </p></dd>
    99. 

  99. <dt><span class="term">-d <em class="replaceable"><code>debug-level</code></em></span></dt>
    100. 

  100. <dd><p>
    101. 

  101.             Set the daemon's debug level to <em class="replaceable"><code>debug-level</code></em>.
    102. 

  102.             Debugging traces from <span><strong class="command">lwresd</strong></span> become
    103. 

  103.             		more verbose as the debug level increases.
    104. 

  104.           </p></dd>
    105. 

  105. <dt><span class="term">-f</span></dt>
    106. 

  106. <dd><p>
    107. 

  107.             Run the server in the foreground (i.e. do not daemonize).
    108. 

  108.           </p></dd>
    109. 

  109. <dt><span class="term">-g</span></dt>
    110. 

  110. <dd><p>
    111. 

  111.             Run the server in the foreground and force all logging
    112. 

  112.             to <code class="filename">stderr</code>.
    113. 

  113.           </p></dd>
    114. 

  114. <dt><span class="term">-i <em class="replaceable"><code>pid-file</code></em></span></dt>
    115. 

  115. <dd><p>
    116. 

  116.             Use <em class="replaceable"><code>pid-file</code></em> as the
    117. 

  117.             PID file instead of the default,
    118. 

  118.             <code class="filename">/var/run/lwresd/lwresd.pid</code>.
    119. 

  119.           </p></dd>
    120. 

  120. <dt><span class="term">-m <em class="replaceable"><code>flag</code></em></span></dt>
    121. 

  121. <dd><p>
    122. 

  122.             Turn on memory usage debugging flags.  Possible flags are
    123. 

  123.             <em class="replaceable"><code>usage</code></em>,
    124. 

  124.             <em class="replaceable"><code>trace</code></em>,
    125. 

  125.             <em class="replaceable"><code>record</code></em>,
    126. 

  126.             <em class="replaceable"><code>size</code></em>, and
    127. 

  127.             <em class="replaceable"><code>mctx</code></em>.  
    128. 

  128.             These correspond to the ISC_MEM_DEBUGXXXX flags described in
    129. 

  129.             <code class="filename">&lt;isc/mem.h&gt;</code>.
    130. 

  130.           </p></dd>
    131. 

  131. <dt><span class="term">-n <em class="replaceable"><code>#cpus</code></em></span></dt>
    132. 

  132. <dd><p>
    133. 

  133.             Create <em class="replaceable"><code>#cpus</code></em> worker threads
    134. 

  134.             to take advantage of multiple CPUs.  If not specified,
    135. 

  135.             <span><strong class="command">lwresd</strong></span> will try to determine the
    136. 

  136.             number of CPUs present and create one thread per CPU.
    137. 

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

  138.             single worker thread will be created.
    139. 

  139.           </p></dd>
    140. 

  140. <dt><span class="term">-P <em class="replaceable"><code>port</code></em></span></dt>
    141. 

  141. <dd><p>
    142. 

  142.             Listen for lightweight resolver queries on port
    143. 

  143.             <em class="replaceable"><code>port</code></em>.  If
    144. 

  144.             		not specified, the default is port 921.
    145. 

  145.           </p></dd>
    146. 

  146. <dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt>
    147. 

  147. <dd><p>
    148. 

  148.             Send DNS lookups to port <em class="replaceable"><code>port</code></em>.  If not
    149. 

  149.             specified, the default is port 53.  This provides a
    150. 

  150.             way of testing the lightweight resolver daemon with a
    151. 

  151.             name server that listens for queries on a non-standard
    152. 

  152.             port number.
    153. 

  153.           </p></dd>
    154. 

  154. <dt><span class="term">-s</span></dt>
    155. 

  155. <dd>
    156. 

  156. <p>
    157. 

  157.             Write memory usage statistics to <code class="filename">stdout</code>
    158. 

  158.             on exit.
    159. 

  159.           </p>
    160. 

  160. <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    161. 

  161. <h3 class="title">Note</h3>
    162. 

  162. <p>
    163. 

  163.               This option is mainly of interest to BIND 9 developers
    164. 

  164.               and may be removed or changed in a future release.
    165. 

  165.             </p>
    166. 

  166. </div>
    167. 

  167. </dd>
    168. 

  168. <dt><span class="term">-t <em class="replaceable"><code>directory</code></em></span></dt>
    169. 

  169. <dd>
    170. 

  170. <p>Chroot
    171. 

  171. 	    to <em class="replaceable"><code>directory</code></em> after
    172. 

  172.             processing the command line arguments, but before
    173. 

  173.             reading the configuration file.
    174. 

  174.           </p>
    175. 

  175. <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
    176. 

  176. <h3 class="title">Warning</h3>
    177. 

  177. <p>
    178. 

  178.               This option should be used in conjunction with the
    179. 

  179.               <code class="option">-u</code> option, as chrooting a process
    180. 

  180.               running as root doesn't enhance security on most
    181. 

  181.               systems; the way <code class="function">chroot(2)</code> is
    182. 

  182.               defined allows a process with root privileges to
    183. 

  183.               escape a chroot jail.
    184. 

  184.             </p>
    185. 

  185. </div>
    186. 

  186. </dd>
    187. 

  187. <dt><span class="term">-u <em class="replaceable"><code>user</code></em></span></dt>
    188. 

  188. <dd><p>Setuid
    189. 

  189. 	    to <em class="replaceable"><code>user</code></em> after completing
    190. 

  190.             privileged operations, such as creating sockets that
    191. 

  191.             listen on privileged ports.
    192. 

  192.           </p></dd>
    193. 

  193. <dt><span class="term">-v</span></dt>
    194. 

  194. <dd><p>
    195. 

  195.             Report the version number and exit.
    196. 

  196.           </p></dd>
    197. 

  197. </dl></div>
    198. 

  198. </div>
    199. 

  199. <div class="refsect1" lang="en">
    200. 

  200. <a name="id2543933"></a><h2>FILES</h2>
    201. 

  201. <div class="variablelist"><dl>
    202. 

  202. <dt><span class="term"><code class="filename">/etc/resolv.conf</code></span></dt>
    203. 

  203. <dd><p>
    204. 

  204.             The default configuration file.
    205. 

  205.           </p></dd>
    206. 

  206. <dt><span class="term"><code class="filename">/var/run/lwresd.pid</code></span></dt>
    207. 

  207. <dd><p>
    208. 

  208.             The default process-id file.
    209. 

  209.           </p></dd>
    210. 

  210. </dl></div>
    211. 

  211. </div>
    212. 

  212. <div class="refsect1" lang="en">
    213. 

  213. <a name="id2543973"></a><h2>SEE ALSO</h2>
    214. 

  214. <p><span class="citerefentry"><span class="refentrytitle">named</span>(8)</span>,
    215. 

  215.       <span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>,
    216. 

  216.       <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>.
    217. 

  217.     </p>
    218. 

  218. </div>
    219. 

  219. <div class="refsect1" lang="en">
    220. 

  220. <a name="id2544007"></a><h2>AUTHOR</h2>
    221. 

  221. <p><span class="corpauthor">Internet Systems Consortium</span>
    222. 

  222.     </p>
    223. 

  223. </div>
    224. 

  224. </div></body>
    225. 

  225. </html>
    226.