<!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>October 12, 2011</date>
  </refentryinfo>

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

  <refnamediv>
    <refname>b10-xfrin</refname>
    <refpurpose>Incoming DNS zone transfer service</refpurpose>
  </refnamediv>

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

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>b10-xfrin</command>
<!--
      <arg><option>-p <replaceable>number</replaceable></option></arg>
      <arg><option>-v</option></arg>
-->
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para>The <command>b10-xfrin</command> daemon provides the BIND 10
      incoming DNS zone transfer service.
      Normally it is started by the
      <citerefentry><refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      boss process.
      When triggered it can request and receive a zone transfer and store
      the zone in a BIND 10 zone data source.
    </para>

<!-- TODO:
xfrin only does the transfer to make it as simple as possible.
The logic for handling transfer triggers or zone management is handled
in separate zonemgr process.
-->

    <para>
      The <command>b10-xfrin</command> daemon supports both AXFR and
      IXFR.  Due to some implementation limitations of the current
      development release, however, it only tries AXFR by default,
      and care should be taken to enable IXFR.
      See the BIND 10 Guide for more details.
    </para>
<!-- TODO: http://bind10.isc.org/ticket/1279 -->

    <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-xfrin</command> will exit.
<!-- TODO what if connection closes later, will b10-xfrin exit? -->
    </para>

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

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

    <para><varname>transfers_in</varname>
      defines the maximum number of inbound zone transfers
      that can run concurrently. The default is 10.
    </para>

<!-- TODO: is name okay for master_addr or just IP? -->
    <para>
      <varname>zones</varname> is a list of zones known to the
      <command>b10-xfrin</command> daemon.
      The list items are:
      <varname>name</varname> (the zone name),
      <varname>class</varname> (defaults to <quote>IN</quote>),
      <varname>master_addr</varname> (the zone master to transfer from),
      <varname>master_port</varname> (defaults to 53),
      <varname>use_ixfr</varname> (defaults to false), and
      <varname>tsig_key</varname> (optional TSIG key name to use).
      The <varname>tsig_key</varname> is specified using a name that
      corresponds to one of the TSIG keys configured in the global
      TSIG key ring (<quote>/tsig_keys/keys</quote>).
    </para>
<!-- TODO: document this better -->

    <para>
      (The site-wide <varname>master_addr</varname> and
      <varname>master_port</varname> configurations are deprecated;
      use the <varname>zones</varname> list configuration instead.)
    </para>

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

    <para>
      <command>notify</command> is sent by
      <citerefentry><refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      when a DNS NOTIFY message is received to initiate a zone
      transfer.
<!-- TODO: document that zonemgr or xfrin checks if it needs to or not -->
      This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
    </para>

    <para>
      <command>refresh</command> triggers the transfer in for
      a single zone.
      It is the same as <command>retransfer</command> except it
      checks the SOA serial first.
<!-- TODO more detail -->
      This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
<!-- TODO: refresh is code but not in spec, see trac ticket #328 -->
    </para>

    <para>
      <command>refresh_from_zonemgr</command> is sent by
      <citerefentry><refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      according to the SOA's REFRESH time
      to tell <command>b10-xfrin</command> that the zone needs to do
      a zone refresh.
      This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
    </para>

    <para>
      <command>retransfer</command> triggers the transfer in for
      a single zone without checking the zone's serial number.
      It has the following arguments: <varname>zone_name</varname>
      to define the zone to request,
      <varname>zone_class</varname> to define the class (defaults to
      <quote>IN</quote>),
      <varname>master</varname> to define the IP address of
      the authoritative server to transfer from,
      and <varname>port</varname> to define the port number on the
      authoritative server (defaults to 53).
      If the address or port is not specified, it will use the
      value previously defined in the <varname>zones</varname>
      configuration.
     </para>
<!-- TODO: later hostname for master? -->

    <para>
      <command>shutdown</command> stops all incoming zone transfers
      and exits <command>b10-xfrin</command>. (Note that the BIND 10
      boss process will restart this service.)
    </para>
<!-- TODO:
add a usage example of xfrin -->

<!-- TODO:

 later it will can be triggered by :
1.  Notify message from auth server.
2.  Schedule zone transfer (determined by Refresh/Expire time in SOA record)

> - what is planned to add to or change for xfrin?
1.  Support IXFR.
2.  Add command "refresh"
3.  Process zone NOTIFY message.
4.  Schedule zone maintenance for all zones.

-->

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

<!-- TODO:
 it can handle more than one XFR in now,
but the problem is If SQLITE3 datasource part support multiple write
operation
-->

  </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>
    </para>
  </refsect1>
-->

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>b10-cfgmgr</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-xfrin</command> daemon was implemented in March 2010
      by Zhang Likun of CNNIC for the ISC BIND 10 project.
    </para>
  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->
