<!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>June 20, 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>/usr/local/var/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>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:
-->
