kea/src/bin/auth/b10-auth.xml.pre

<!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>October 3, 2012</date>
  </refentryinfo>

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

  <refnamediv>
    <refname>b10-auth</refname>
    <refpurpose>Authoritative DNS server</refpurpose>
  </refnamediv>

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

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

  <refsect1>
    <title>DESCRIPTION</title>
    <para>The <command>b10-auth</command> daemon provides the BIND 10
      authoritative DNS server.
      Normally it is started by the
      <citerefentry><refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      boss 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-auth</command> will exit.
<!-- TODO what if msgq connection closes later, will b10-auth exit? -->
      It receives its configurations from
<citerefentry><refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>.

    </para>

<!-- TODO: mention xfrin, xfrout, zonemgr ? -->

  </refsect1>

  <refsect1>
    <title>OPTIONS</title>

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

    <variablelist>
      <varlistentry>
        <term><option>-v</option></term>
        <listitem><para>
	  Enable verbose logging mode. This enables logging of
	  diagnostic messages at the maximum debug level.
        </para></listitem>
      </varlistentry>

    </variablelist>

  </refsect1>

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

    <para>
      <varname>database_file</varname> defines the path to the
      SQLite3 zone file when using the sqlite datasource.
      The default is
      <filename>@@LOCALSTATEDIR@@/bind10-devel/zone.sqlite3</filename>.
    </para>

    <para>
      <varname>datasources</varname> configures data sources.
      The list items include:
      <varname>type</varname> to define the required data source type
      (such as <quote>memory</quote>);
      <varname>class</varname> to optionally select the class
      (it defaults to <quote>IN</quote>);
      and
      <varname>zones</varname> to define the
      <varname>file</varname> path name,
      <varname>origin</varname> (default domain), and optional
      <varname>filetype</varname>.
      By default, <varname>zones</varname> is empty.
      For the in-memory data source (i.e., the <varname>type</varname>
      is <quote>memory</quote>), the optional <varname>filetype</varname>
      configuration item for <varname>zones</varname> can be
      specified so the in-memory zone data can be built from another
      data source that is based on a database backend (in practice
      with current implementation, it would be an SQLite3 database
      file for the SQLite3 data source).
      See the <citetitle>BIND 10 Guide</citetitle> for configuration
      details.

      <note><simpara>
        Only the IN class is supported at this time.
        By default, the memory data source is disabled.
        Also, currently the zone file must be canonical such as
        generated by <command>named-compilezone -D</command>.
      </simpara></note>
    </para>

    <para>
      <varname>listen_on</varname> is a list of addresses and ports for
      <command>b10-auth</command> to listen on.
      The list items are the <varname>address</varname> string
      and <varname>port</varname> number.
      By default, <command>b10-auth</command> listens on port 53
      on the IPv6 (::) and IPv4 (0.0.0.0) wildcard addresses.
    </para>

    <para>
      <varname>tcp_recv_timeout</varname> is the timeout used on
      incoming TCP connections, in milliseconds. If the query
      is not sent within this time, the connection is closed.
      Setting this to 0 will disable TCP timeouts completely.
    </para>

<!-- TODO: formating -->
    <para>
      The configuration commands are:
    </para>

    <para>
      <command>loadzone</command> tells <command>b10-auth</command>
      to load or reload a zone file. The arguments include:
      <varname>class</varname> which optionally defines the class
      (it defaults to <quote>IN</quote>);
      <varname>origin</varname> is the domain name of the zone;
      and
      <varname>datasrc</varname> optionally defines the type of datasource
      (it defaults to <quote>memory</quote>).

      <note><simpara>
        In this development version, currently this only supports the
        IN class and the memory data source.
      </simpara></note>
    </para>

    <para>
      <command>getstats</command> tells <command>b10-auth</command>
      to send its statistics data.
    </para>

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

  </refsect1>

  <refsect1>
    <title>STATISTICS DATA</title>

    <para>
      The statistics data collected by the <command>b10-stats</command>
      daemon for <quote>Auth</quote> include:
    </para>

<!-- ### STATISTICS DATA PLACEHOLDER ### -->

    <note>
      <para>
        Opcode of a request message will not be counted if:
        <itemizedlist>
          <listitem><para>
            The request message is too short to parse the message header
          </para></listitem>
          <listitem><para>
            The request message is a response (i.e. QR bit is set)
          </para></listitem>
        </itemizedlist>
      </para>

      <para>
        Request attributes except for opcode will not be counted if TSIG
        validation failed as they are not reliable.
        We always count opcode mainly for compatibility with BIND 9,
        but remember that if there's any error related to TSIG, some
        of the counted opcode may not be trustworthy.
      </para>
    </note>

  </refsect1>

  <refsect1>
    <title>FILES</title>
    <para>
      <filename>@@LOCALSTATEDIR@@/bind10-devel/zone.sqlite3</filename>
      &mdash; Location for the SQLite3 zone database
      when <emphasis>database_file</emphasis> configuration is not
      defined.
    </para>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-loadzone</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-stats</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-zonemgr</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-auth</command> daemon was first coded in October 2009.
    </para>
  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->