kea/src/bin/resolver/b10-resolver.xml

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	       [<!ENTITY mdash "&#8212;">]>
<!--
 - Copyright (C) 2010-2012  Internet Systems Consortium, Inc. ("ISC")
 -
 - Permission to use, copy, modify, and/or distribute this software for any
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 -
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
-->

<refentry>

  <refentryinfo>
    <date>August 16, 2012</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle>b10-resolver</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo>BIND10</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>b10-resolver</refname>
    <refpurpose>Recursive DNS server</refpurpose>
  </refnamediv>

  <docinfo>
    <copyright>
      <year>2010-2012</year>
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
  </docinfo>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>b10-resolver</command>
      <arg><option>-v</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para>The <command>b10-resolver</command> daemon provides the BIND 10
      recursive DNS server.  Normally it is started by the
      <citerefentry><refentrytitle>b10-init</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      process.
    </para>

    <para>
      This daemon communicates with other BIND 10 components over a
      <citerefentry><refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      C-Channel connection.  If this connection is not established,
      <command>b10-resolver</command> will exit.
    </para>

    <para>
      It also receives its configurations from
<citerefentry><refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
    </para>

<!--
    <note><para>
      Future versions will introduce lookup of local authoritative
      data (as in <command>b10-auth</command>) and DNSSEC validation.
    </para></note>
-->

  </refsect1>

  <refsect1>
    <title>OPTIONS</title>

    <para>The arguments are as follows:</para>

    <variablelist>

<!-- TODO: this needs to be fixed as -v on command line
should imply stdout or stderr output also -->
<!-- TODO: can this -v be overidden by configuration or bindctl? -->
      <varlistentry>
        <term><option>-v</option></term>
        <listitem><para>
          Enable verbose mode.
          This sets logging to the maximum debugging level.
        </para></listitem>
      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1>
    <title>CONFIGURATION AND COMMANDS</title>
    <para>
      The configurable settings are:
    </para>

    <para>
      <varname>forward_addresses</varname> defines the list of addresses
      and ports that <command>b10-resolver</command> should forward
      queries to.
      Defining this enables forwarding.
<!-- TODO: list
address
	::1
port
	53
-->
    </para>

<!-- trac384:

once that is merged you can for instance do 'config add Resolver/forward_addresses { "port": 123 } and it will fill in the rest (in this case ::1 for the address)

-->

    <para>
      <varname>listen_on</varname> is a list of addresses and ports for
      <command>b10-resolver</command> to listen on.
      The list items are the <varname>address</varname> string
      and <varname>port</varname> number.
      The defaults are address ::1 port 53 and
      address 127.0.0.1 port 53.
<!-- TODO: but defaults are not used, Trac #518 -->
    </para>

    <para>
<!-- TODO: need more explanation or point to guide. -->
<!-- TODO: what about a netmask or cidr? -->
<!-- TODO: document "key" -->
<!-- TODO: where are the TSIG keys defined? -->
<!-- TODO: key and from are mutually exclusive? what if both defined? -->
      <varname>query_acl</varname> is a list of query access control
      rules. The list items are the <varname>action</varname> string
      and the <varname>from</varname> or <varname>key</varname> strings.
      The possible actions are ACCEPT, REJECT and DROP.
      The <varname>from</varname> is a remote (source) IPv4 or IPv6
      address or special keyword.
      The <varname>key</varname> is a TSIG key name.
      The default configuration accepts queries from 127.0.0.1 and ::1.
      The default action is REJECT for newly added
      <varname>query_acl</varname> items.
    </para>

    <para>
      <varname>retries</varname> is the number of times to retry
      (resend query) after a query timeout
      (<varname>timeout_query</varname>).
      The default is 3.
    </para>

    <para>
      <varname>root_addresses</varname> is a list of addresses and ports
      for <command>b10-resolver</command> to use directly as
      root servers to start resolving.
      The list items are the <varname>address</varname> string
      and <varname>port</varname> number.
      By default, a hardcoded address for l.root-servers.net
      (199.7.83.42 or 2001:500:3::42) is used.
    </para>
<!-- TODO: this is broken, see ticket #1184 -->

    <para>
      <varname>timeout_client</varname> is the number of milliseconds
      to wait before timing out the incoming client query.
      If set to -1, this timeout is disabled.
      The default is 4000.
      After this timeout, a SERVFAIL is sent back to the client asking
      the question.
      (The lookup may continue after the timeout, but a later answer
      is not returned for the now-past query.)
    </para>

    <para>
      <varname>timeout_lookup</varname> is the number of milliseconds
      before it stops trying the query.
      If set to -1, this timeout is disabled.
      The default is 30000.
    </para>

    <para>
<!-- previous timeout was renamed to timeout_query -->
      <varname>timeout_query</varname> is the number of milliseconds to
      wait before it retries a query.
      If set to -1, this timeout is disabled.
      The default is 2000.
    </para>

<!-- TODO: formating -->
    <para>
      The configuration command is:
    </para>

    <para>
      <command>shutdown</command> exits <command>b10-resolver</command>.
      This has an optional <varname>pid</varname> argument to
      select the process ID to stop.
      (Note that the b10-init process may restart this service
      if configured.)
    </para>

  </refsect1>

<!--
  <refsect1>
    <title>FILES</title>
    <para>
      None.
    </para>
  </refsect1>
-->

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-cmdctl</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citetitle>BIND 10 Guide</citetitle>.
    </para>
  </refsect1>

  <refsect1>
    <title>HISTORY</title>
    <para>
      The <command>b10-resolver</command> daemon was first coded in
      September 2010. The initial implementation only provided
      forwarding. Iteration was introduced in January 2011.
      Caching was implemented in February 2011.
      Access control was introduced in June 2011.
<!-- TODO: document when validation was added -->
    </para>
  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->