kea/src/bin/zonemgr/b10-zonemgr.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-2011  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>May 19, 2011</date>
  </refentryinfo>

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

  <refnamediv>
    <refname>b10-zonemgr</refname>
    <refpurpose>BIND 10 Secondary zone manager</refpurpose>
  </refnamediv>

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

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>b10-zonemgr</command>
      <arg><option>-v</option></arg>
      <arg><option>--verbose</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para>The <command>b10-zonemgr</command> daemon, also known
      as the BIND 10 secondary manager, keeps track of timers
      and other information necessary for BIND 10 to act as a DNS slave.
      Normally it is started by the
      <citerefentry><refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      boss process.
    </para>

    <para>
      This daemon communicates with BIND 10 over a
      <citerefentry><refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      C-Channel connection.  If this connection is not established,
      <command>b10-zonemgr</command> will exit.
<!-- TODO what if connection closes later, will b10-zonemgr exit? -->
    </para>

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

<!--

            self._send_command(XFRIN_MODULE_NAME, ZONE_NOTIFY_COMMAND, param) 
            self._clear_zone_notifier_master(zone_name_class)
        # Send refresh command to xfrin module
        else:
            param = {"zone_name" : zone_name_class[0],
                     "zone_class" : zone_name_class[1]
                    }
            self._send_command(XFRIN_MODULE_NAME, ZONE_REFRESH_COMMAND, param)

-->

  </refsect1>

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

    <para>
      <varname>lowerbound_refresh</varname>
      defines the minimum SOA REFRESH time in seconds.
      The default is 10.
    </para>

    <para>
      <varname>lowerbound_retry</varname>
      defines the minimum SOA RETRY time in seconds.
      The default is 5.
    </para>

    <para>
      <varname>refresh_jitter</varname>
      This value is a real number.
      The maximum amount is 0.5.
      The default is 0.25.
    </para>
<!-- TODO: needs to be documented -->
<!-- TODO:      Set to 0 to disable the jitter.   -->

    <para>
      <varname>reload_jitter</varname>
      This value is a real number.
      The default is 0.75.
    </para>
<!-- TODO: needs to be documented -->
<!-- TODO:      Set to 0 to disable the jitter.   -->
<!-- what does 0 do? -->
<!-- TODO: no max? -->

<!-- TODO: remove this. This is old removed config
    <para>
      <varname>jitter_scope</varname>
      defines the random jitter range subtracted from the refresh
      and retry timers to avoid many zones from refreshing at the
      same time.
      The refresh or retry time actually used is a random time
      between the defined refresh or retry time and it multiplied
      by the <varname>jitter_scope</varname>.
      This is re-evaluated after each refresh or retry.
      This value is a real number and the maximum is 0.5 (half of the
      refresh or retry time).
      The default is 0.25.
      Set to 0 to disable the jitter.
    </para>
-->

    <para>
      <varname>max_transfer_timeout</varname>
      defines the maximum amount of time in seconds for a transfer.
<!-- TODO: what is the purpose of this? -->
      The default is 14400 (4 hours).
    </para>

<!-- TODO: this duplicates list in Xfrin too -->
    <para>
      <varname>secondary_zones</varname> is a list of slave zones
      that the <command>b10-zonemgr</command> should keep timers for.
      The list items include the <varname>name</varname> (which
      defines the zone name) and the <varname>class</varname>
      (which defaults to <quote>IN</quote>).
    </para>

    <para>
      (A deprecated configuration is <varname>jitter_scope</varname>
      which is superceded by <varname>refresh_jitter</varname>
      and <varname>reload_jitter</varname>.)
    </para>

<!-- TODO: formating -->
    <para>
      The configuration commands are:
    </para>
    <para>
      <command>notify</command> (sent by
      <citerefentry><refentrytitle>b10-auth</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
      tells <command>b10-zonemgr</command>
      the zone name and class, and the IP address for the master
      (source of the NOTIFY message).
      This will set the zone's refresh time to now.
<!-- TODO reword this -->
      This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
    </para>

    <para>
      <command>shutdown</command> exits <command>b10-zonemgr</command>.
      (Note that the BIND 10 boss process will restart this service.)
    </para>

    <para>
      <command>zone_new_data_ready</command> is sent from
      <citerefentry><refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      to indicate that the zone transferred in successfully.
      This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
    </para>

    <para>
      <command>zone_xfrin_failed</command> is sent from
      <citerefentry><refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      to indicate a failure (such as a transfer-in was incomplete).
      The refresh timer for the zone is reset.
<!--
        """Set zone next refresh time after zone refresh fail.
           now + retry*3/4 <= next_refresh_time <= now + retry
-->
      This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
    </para>

  </refsect1>

<!--
  <refsect1>
    <title>OPTIONS</title>

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

    <variablelist>
      <varlistentry>
        <term><option></option></term>
        <listitem><para>
        </para></listitem>
      </varlistentry>

    </variablelist>

  </refsect1>
-->
<!--
  <refsect1>
    <title>FILES</title>
    <para>
    <filename>/tmp/auth_xfrout_conn</filename>
    </para>
  </refsect1>
-->

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>b10-auth</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-xfrout</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-zonemgr</command> daemon was designed in July 2010
      by CNNIC for the ISC BIND 10 project.
    </para>
  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->