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  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.
-->

<!-- $Id$ -->
<refentry>

  <refentryinfo>
    <date>July 29, 2010</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</year>
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
  </docinfo>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>b10-auth</command>
      <arg><option>-4</option></arg>
      <arg><option>-6</option></arg>
      <arg><option>-a <replaceable>address</replaceable></option></arg>
      <arg><option>-n</option></arg>
      <arg><option>-p <replaceable>number</replaceable></option></arg>
      <arg><option>-u <replaceable>username</replaceable></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? -->
    </para>

    <para>
      It also receives its configurations from
<citerefentry><refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
      It will honor the <emphasis>database_file</emphasis> configuration
      to point to the SQLite3 zone file.

<!-- TODO: data source -->
    </para>

    <note><para>
      This prototype version uses SQLite3 as its data source backend.
      Future versions will be configurable, supporting multiple
      data storage types.
    </para></note>
  </refsect1>

  <refsect1>
    <title>OPTIONS</title>

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

    <variablelist>
      <varlistentry>
        <term><option>-4</option></term>
        <listitem><para>
          Enables IPv4 only mode.
          This switch may not be used with <option>-6</option> nor
          <option>-a</option>.
          By default, it listens on both IPv4 and IPv6 (if capable).
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-6</option></term>
        <listitem><para>
          Enables IPv6 only mode.
          This switch may not be used with <option>-4</option> nor
          <option>-a</option>.
          By default, it listens on both IPv4 and IPv6 (if capable).
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-a <replaceable>address</replaceable></option></term>

        <listitem>
          <para>The IPv4 or IPv6 address to listen on.
            This switch may not be used with <option>-4</option> nor
            <option>-6</option>.
            The default is to listen on all addresses.
            (This is a short term workaround. This argument may change.)   
          </para>                      
         </listitem>
      </varlistentry>

      <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>
      </varlistentry>

      <varlistentry>
        <term><option>-p <replaceable>number</replaceable></option></term>
        <listitem><para>
          The port number it listens on.
          The default is 5300.</para>
	  <note><simpara>The Y1 prototype runs on all interfaces
	  and on this nonstandard port.</simpara></note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-u <replaceable>username</replaceable></option></term>
        <listitem>
	  <para>
	    The user name of the <command>b10-auth</command> daemon.
	    If specified, the daemon changes the process owner to the
	    specified user.
	    The <replaceable>username</replaceable> must be either a
	    valid numeric user ID or a valid user name.
	    By default the daemon runs as the user who invokes it.
	  </para>
        </listitem>
      </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>FILES</title>
    <para>
      <filename>/usr/local/var/db/zone.sqlite3</filename>
      &mdash; Location for the SQLite3 zone database
      when <emphasis>database_file</emphasis> configuration is not
      defined.
    </para>
<!-- TODO: this is not correct yet. -->
  </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-loadzone</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-msgq</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:
-->