Add b10-xfrout.8 manual page.

Make target added.
Original in DocBook XML.
Also generated roff version added.

Content reviewed by Zhang Likun.

The man page is not complete. Needs more content and improved formatting.


git-svn-id: svn://bind10.isc.org/svn/bind10/trunk@1764 e5f2f494-b856-4b98-b285-d166d9295462

src/bin/xfrout/Makefile.am

@@ -9,6 +9,17 @@ b10_xfrout_DATA = xfrout.spec
 
 CLEANFILES=	b10-xfrout xfrout.pyc xfrout.spec
 
+man_MANS = b10-xfrout.8
+EXTRA_DIST = $(man_MANS) b10-xfrout.xml
+
+if ENABLE_MAN
+
+b10-xfrout.8: b10-xfrout.xml
+	xsltproc --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(srcdir)/b10-xfrout.xml
+
+endif
+
+
 xfrout.spec: xfrout.spec.pre
 	$(SED) -e "s|@@LOCALSTATEDIR@@|$(localstatedir)|" xfrout.spec.pre >$@
 

src/bin/xfrout/b10-xfrout.8

@@ -0,0 +1,116 @@
+'\" t
+.\"     Title: b10-xfrout
+.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
+.\"      Date: April 20, 2010
+.\"    Manual: BIND10
+.\"    Source: BIND10
+.\"  Language: English
+.\"
+.TH "B10\-XFROUT" "8" "April 20, 2010" "BIND10" "BIND10"
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+b10-xfrout \- Outbound DNS zone transfer service
+.SH "SYNOPSIS"
+.HP \w'\fBb10\-xfrout\fR\ 'u
+\fBb10\-xfrout\fR [\fB\-v\fR] [\fB\-\-verbose\fR]
+.SH "DESCRIPTION"
+.PP
+The
+\fBb10\-xfrout\fR
+daemon provides the BIND 10 outgoing DNS zone transfer service\&. Normally it is started by the
+\fBbind10\fR(8)
+boss process\&. When the
+\fBb10\-auth\fR
+DNS server receives a transfer request,
+\fBb10\-xfrout\fR
+sends the zone as found in the BIND 10 zone data store\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+.sp
+This development prototype release only supports AXFR\&. IXFR is not implemented\&.
+.sp .5v
+.RE
+.PP
+
+This daemon communicates with BIND 10 over a
+\fBb10-msgq\fR(8)
+C\-Channel connection\&. If this connection is not established,
+\fBb10\-xfrout\fR
+will exit\&.
+.PP
+
+\fBb10\-xfrout\fR
+receives its configurations from
+\fBb10-cfgmgr\fR(8)\&.
+.SH "CONFIGURATION AND COMMANDS"
+.PP
+The configurable settings are:
+.PP
+
+\fItransfers\-out\fR
+defines the maximum number of outgoing zone transfers that can run concurrently\&. The default is 10\&.
+.PP
+
+\fIdb_file\fR
+defines the path to the SQLite3 data store file\&. The default is
+/usr/local/var/bind10\-devel/zone\&.sqlite3\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+.sp
+This prototype version uses SQLite3 as its data source backend\&. Future versions will be configurable, supporting multiple data storage types\&.
+.sp .5v
+.RE
+.PP
+The configuration command is:
+.PP
+
+\fBshutdown\fR
+stops all outbound zone transfers and exits
+\fBb10\-xfrout\fR\&. (Note that the BIND 10 boss process will restart this service\&.)
+.SH "SEE ALSO"
+.PP
+
+\fBb10-auth\fR(8),
+\fBb10-cfgmgr\fR(8),
+\fBb10-msgq\fR(8),
+\fBbind10\fR(8),
+BIND 10 Guide\&.
+.SH "HISTORY"
+.PP
+The
+\fBb10\-xfrout\fR
+daemon was implemented in March 2010 by Zhang Likun of CNNIC for the ISC BIND 10 project\&.
+.SH "COPYRIGHT"
+.br
+Copyright \(co 2010 Internet Systems Consortium, Inc. ("ISC")
+.br

src/bin/xfrout/b10-xfrout.xml

@@ -0,0 +1,181 @@
+<!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>April 20, 2010</date>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>b10-xfrout</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo>BIND10</refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>b10-xfrout</refname>
+    <refpurpose>Outbound DNS zone transfer service</refpurpose>
+  </refnamediv>
+
+  <docinfo>
+    <copyright>
+      <year>2010</year>
+      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
+    </copyright>
+  </docinfo>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>b10-xfrout</command>
+      <arg><option>-v</option></arg>
+      <arg><option>--verbose</option></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>DESCRIPTION</title>
+    <para>The <command>b10-xfrout</command> daemon provides the BIND 10
+      outgoing DNS zone transfer service.
+      Normally it is started by the
+      <citerefentry><refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      boss process.
+      When the <command>b10-auth</command> DNS server receives
+      a transfer request, <command>b10-xfrout</command> sends the
+      zone as found in the BIND 10 zone data store.
+    </para>
+
+<!-- TODO
+ BTW, do we need to mention that the xfr request is received by auth
+ process?, and then the socket and xfr request is sent to xfrout.
+-->
+
+    <note><simpara>
+      This development prototype release only supports AXFR.
+      IXFR is not implemented.
+    </simpara></note>
+
+    <para>
+<!-- TODO: does it really use msgq? what for? -->
+      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-xfrout</command> will exit.
+<!-- TODO what if connection closes later, will b10-xfrout exit? -->
+    </para>
+
+    <para>
+     <command>b10-xfrout</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-out</varname>
+      defines the maximum number of outgoing zone transfers
+      that can run concurrently. The default is 10.
+    </para>
+    <para>
+      <varname>db_file</varname>
+      defines the path to the SQLite3 data store file.
+      The default is
+      <filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>.
+    </para>
+
+    <note><simpara>
+      This prototype version uses SQLite3 as its data source backend.
+      Future versions will be configurable, supporting multiple
+      data storage types.
+    </simpara></note>
+
+<!-- TODO: formating -->
+    <para>
+      The configuration command is:
+    </para>
+    <para>
+      <command>shutdown</command> stops all outbound zone transfers
+      and exits <command>b10-xfrout</command>. (Note that the BIND 10
+      boss process will restart this service.)
+    </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>bind10</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citetitle>BIND 10 Guide</citetitle>.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>HISTORY</title>
+    <para>
+      The <command>b10-xfrout</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:
+-->