/contrib/bind9/bin/named/lwresd.docbook

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 374 lines · 337 code · 37 blank · 0 comment · 0 complexity · 01c5ee575ae31d8f6047fb90767c31a0 MD5 · raw file

  1. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  2. "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
  3. [<!ENTITY mdash "&#8212;">]>
  4. <!--
  5. - Copyright (C) 2004, 2005, 2007-2009 Internet Systems Consortium, Inc. ("ISC")
  6. - Copyright (C) 2000, 2001 Internet Software Consortium.
  7. -
  8. - Permission to use, copy, modify, and/or 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. <!-- $Id: lwresd.docbook,v 1.20 2009/01/20 23:47:56 tbox Exp $ -->
  21. <refentry>
  22. <refentryinfo>
  23. <date>June 30, 2000</date>
  24. </refentryinfo>
  25. <refmeta>
  26. <refentrytitle><application>lwresd</application></refentrytitle>
  27. <manvolnum>8</manvolnum>
  28. <refmiscinfo>BIND9</refmiscinfo>
  29. </refmeta>
  30. <refnamediv>
  31. <refname><application>lwresd</application></refname>
  32. <refpurpose>lightweight resolver daemon</refpurpose>
  33. </refnamediv>
  34. <docinfo>
  35. <copyright>
  36. <year>2004</year>
  37. <year>2005</year>
  38. <year>2007</year>
  39. <year>2008</year>
  40. <year>2009</year>
  41. <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  42. </copyright>
  43. <copyright>
  44. <year>2000</year>
  45. <year>2001</year>
  46. <holder>Internet Software Consortium.</holder>
  47. </copyright>
  48. </docinfo>
  49. <refsynopsisdiv>
  50. <cmdsynopsis>
  51. <command>lwresd</command>
  52. <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
  53. <arg><option>-C <replaceable class="parameter">config-file</replaceable></option></arg>
  54. <arg><option>-d <replaceable class="parameter">debug-level</replaceable></option></arg>
  55. <arg><option>-f</option></arg>
  56. <arg><option>-g</option></arg>
  57. <arg><option>-i <replaceable class="parameter">pid-file</replaceable></option></arg>
  58. <arg><option>-m <replaceable class="parameter">flag</replaceable></option></arg>
  59. <arg><option>-n <replaceable class="parameter">#cpus</replaceable></option></arg>
  60. <arg><option>-P <replaceable class="parameter">port</replaceable></option></arg>
  61. <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
  62. <arg><option>-s</option></arg>
  63. <arg><option>-t <replaceable class="parameter">directory</replaceable></option></arg>
  64. <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
  65. <arg><option>-v</option></arg>
  66. <arg><option>-4</option></arg>
  67. <arg><option>-6</option></arg>
  68. </cmdsynopsis>
  69. </refsynopsisdiv>
  70. <refsect1>
  71. <title>DESCRIPTION</title>
  72. <para><command>lwresd</command>
  73. 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><command>lwresd</command>
  80. 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. <refsect1>
  106. <title>OPTIONS</title>
  107. <variablelist>
  108. <varlistentry>
  109. <term>-4</term>
  110. <listitem>
  111. <para>
  112. Use IPv4 only even if the host machine is capable of IPv6.
  113. <option>-4</option> and <option>-6</option> are mutually
  114. exclusive.
  115. </para>
  116. </listitem>
  117. </varlistentry>
  118. <varlistentry>
  119. <term>-6</term>
  120. <listitem>
  121. <para>
  122. Use IPv6 only even if the host machine is capable of IPv4.
  123. <option>-4</option> and <option>-6</option> are mutually
  124. exclusive.
  125. </para>
  126. </listitem>
  127. </varlistentry>
  128. <!-- this is in source but not mentioned? does this matter? -->
  129. <varlistentry>
  130. <term>-c <replaceable class="parameter">config-file</replaceable></term>
  131. <listitem>
  132. <para>
  133. Use <replaceable class="parameter">config-file</replaceable> as the
  134. configuration file instead of the default,
  135. <filename>/etc/lwresd.conf</filename>.
  136. <!-- Should this be an absolute path name? -->
  137. <option>-c</option> can not be used with <option>-C</option>.
  138. </para>
  139. </listitem>
  140. </varlistentry>
  141. <varlistentry>
  142. <term>-C <replaceable class="parameter">config-file</replaceable></term>
  143. <listitem>
  144. <para>
  145. Use <replaceable class="parameter">config-file</replaceable> as the
  146. configuration file instead of the default,
  147. <filename>/etc/resolv.conf</filename>.
  148. <option>-C</option> can not be used with <option>-c</option>.
  149. </para>
  150. </listitem>
  151. </varlistentry>
  152. <varlistentry>
  153. <term>-d <replaceable class="parameter">debug-level</replaceable></term>
  154. <listitem>
  155. <para>
  156. Set the daemon's debug level to <replaceable class="parameter">debug-level</replaceable>.
  157. Debugging traces from <command>lwresd</command> become
  158. more verbose as the debug level increases.
  159. </para>
  160. </listitem>
  161. </varlistentry>
  162. <varlistentry>
  163. <term>-f</term>
  164. <listitem>
  165. <para>
  166. Run the server in the foreground (i.e. do not daemonize).
  167. </para>
  168. </listitem>
  169. </varlistentry>
  170. <varlistentry>
  171. <term>-g</term>
  172. <listitem>
  173. <para>
  174. Run the server in the foreground and force all logging
  175. to <filename>stderr</filename>.
  176. </para>
  177. </listitem>
  178. </varlistentry>
  179. <varlistentry>
  180. <term>-i <replaceable class="parameter">pid-file</replaceable></term>
  181. <listitem>
  182. <para>
  183. Use <replaceable class="parameter">pid-file</replaceable> as the
  184. PID file instead of the default,
  185. <filename>/var/run/lwresd/lwresd.pid</filename>.
  186. </para>
  187. </listitem>
  188. </varlistentry>
  189. <varlistentry>
  190. <term>-m <replaceable class="parameter">flag</replaceable></term>
  191. <listitem>
  192. <para>
  193. Turn on memory usage debugging flags. Possible flags are
  194. <replaceable class="parameter">usage</replaceable>,
  195. <replaceable class="parameter">trace</replaceable>,
  196. <replaceable class="parameter">record</replaceable>,
  197. <replaceable class="parameter">size</replaceable>, and
  198. <replaceable class="parameter">mctx</replaceable>.
  199. These correspond to the ISC_MEM_DEBUGXXXX flags described in
  200. <filename>&lt;isc/mem.h&gt;</filename>.
  201. </para>
  202. </listitem>
  203. </varlistentry>
  204. <varlistentry>
  205. <term>-n <replaceable class="parameter">#cpus</replaceable></term>
  206. <listitem>
  207. <para>
  208. Create <replaceable class="parameter">#cpus</replaceable> worker threads
  209. to take advantage of multiple CPUs. If not specified,
  210. <command>lwresd</command> will try to determine the
  211. number of CPUs present and create one thread per CPU.
  212. If it is unable to determine the number of CPUs, a
  213. single worker thread will be created.
  214. </para>
  215. </listitem>
  216. </varlistentry>
  217. <varlistentry>
  218. <term>-P <replaceable class="parameter">port</replaceable></term>
  219. <listitem>
  220. <para>
  221. Listen for lightweight resolver queries on port
  222. <replaceable class="parameter">port</replaceable>. If
  223. not specified, the default is port 921.
  224. </para>
  225. </listitem>
  226. </varlistentry>
  227. <varlistentry>
  228. <term>-p <replaceable class="parameter">port</replaceable></term>
  229. <listitem>
  230. <para>
  231. Send DNS lookups to port <replaceable class="parameter">port</replaceable>. If not
  232. specified, the default is port 53. This provides a
  233. way of testing the lightweight resolver daemon with a
  234. name server that listens for queries on a non-standard
  235. port number.
  236. </para>
  237. </listitem>
  238. </varlistentry>
  239. <varlistentry>
  240. <term>-s</term>
  241. <listitem>
  242. <para>
  243. Write memory usage statistics to <filename>stdout</filename>
  244. on exit.
  245. </para>
  246. <note>
  247. <para>
  248. This option is mainly of interest to BIND 9 developers
  249. and may be removed or changed in a future release.
  250. </para>
  251. </note>
  252. </listitem>
  253. </varlistentry>
  254. <varlistentry>
  255. <term>-t <replaceable class="parameter">directory</replaceable></term>
  256. <listitem>
  257. <para>Chroot
  258. to <replaceable class="parameter">directory</replaceable> after
  259. processing the command line arguments, but before
  260. reading the configuration file.
  261. </para>
  262. <warning>
  263. <para>
  264. This option should be used in conjunction with the
  265. <option>-u</option> option, as chrooting a process
  266. running as root doesn't enhance security on most
  267. systems; the way <function>chroot(2)</function> is
  268. defined allows a process with root privileges to
  269. escape a chroot jail.
  270. </para>
  271. </warning>
  272. </listitem>
  273. </varlistentry>
  274. <varlistentry>
  275. <term>-u <replaceable class="parameter">user</replaceable></term>
  276. <listitem>
  277. <para>Setuid
  278. to <replaceable class="parameter">user</replaceable> after completing
  279. privileged operations, such as creating sockets that
  280. listen on privileged ports.
  281. </para>
  282. </listitem>
  283. </varlistentry>
  284. <varlistentry>
  285. <term>-v</term>
  286. <listitem>
  287. <para>
  288. Report the version number and exit.
  289. </para>
  290. </listitem>
  291. </varlistentry>
  292. </variablelist>
  293. </refsect1>
  294. <refsect1>
  295. <title>FILES</title>
  296. <variablelist>
  297. <varlistentry>
  298. <term><filename>/etc/resolv.conf</filename></term>
  299. <listitem>
  300. <para>
  301. The default configuration file.
  302. </para>
  303. </listitem>
  304. </varlistentry>
  305. <varlistentry>
  306. <term><filename>/var/run/lwresd.pid</filename></term>
  307. <listitem>
  308. <para>
  309. The default process-id file.
  310. </para>
  311. </listitem>
  312. </varlistentry>
  313. </variablelist>
  314. </refsect1>
  315. <refsect1>
  316. <title>SEE ALSO</title>
  317. <para><citerefentry>
  318. <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
  319. </citerefentry>,
  320. <citerefentry>
  321. <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
  322. </citerefentry>,
  323. <citerefentry>
  324. <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
  325. </citerefentry>.
  326. </para>
  327. </refsect1>
  328. <refsect1>
  329. <title>AUTHOR</title>
  330. <para><corpauthor>Internet Systems Consortium</corpauthor>
  331. </para>
  332. </refsect1>
  333. </refentry><!--
  334. - Local variables:
  335. - mode: sgml
  336. - End:
  337. -->