kea/src/bin/auth/b10-auth.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>March 1, 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>-n</option></arg>
      <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>-n</option></term>
        <listitem><para>
          Do not cache answers in memory.
          The default is to use the cache for faster responses.
	  The cache keeps the most recent 30,000 answers (positive
	  and negative) in memory for 30 seconds (instead of querying
	  the data source, such as SQLite3 database, each time).
        </para></listitem>
<!-- TODO: this is SQLite3 only -->
      </varlistentry>

      <varlistentry>
        <term><option>-v</option></term>
        <listitem><para>
          Enabled verbose mode. This enables diagnostic messages to
          STDERR.
        </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>/usr/local/var/bind10-devel/zone.sqlite3</filename>.
    </para>

    <para>
      <varname>datasources</varname> configures data sources.
      The list items include:
      <varname>type</varname> to optionally choose the 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 and the
      <varname>origin</varname> (default domain).

      By default, this is empty.

      <note><simpara>
        In this development version, currently this is only used for the
        memory data source.
        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>statistics-interval</varname> is the timer interval
      in seconds for <command>b10-auth</command> to share its
      statistics information to
      <citerefentry><refentrytitle>b10-stats</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
      Statistics updates can be disabled by setting this to 0.
      The default is 60.
    </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>sendstats</command> tells <command>b10-auth</command>
      to send its statistics data to
      <citerefentry><refentrytitle>b10-stats</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      immediately.
    </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>

    <variablelist>

      <varlistentry>
        <term>queries.tcp</term>
        <listitem><simpara>Total count of queries received by the
          <command>b10-auth</command> server over TCP since startup.
        </simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>queries.udp</term>
        <listitem><simpara>Total count of queries received by the
          <command>b10-auth</command> server over UDP since startup.
        </simpara></listitem>
      </varlistentry>

    </variablelist>

<!-- TODO: missing stats docs. See ticket #1721 -->

  </refsect1>

  <refsect1>
    <title>FILES</title>
    <para>
      <filename>/usr/local/var/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:
-->