Some guide cleanups.

Change Y1 references to "development".
Mention more build/run time dependencies.
Fix xfrin sentence.
Add xfrin and xfrout info (needs a lot more).
Change and add some ./configure options.
Comment out broken example.

Jelte reviewed and commented via jabber.


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

doc/guide/bind10-guide.xml

@@ -71,11 +71,12 @@
       </para>
 
       <note><para>
-        For the Y1 prototype release, the only supported data source
-        backend is SQLite3. The authoritative server requires
-        SQLite 3.3.9 or newer,
-        and the <command>b10-xfrin</command> module requires the
-        Python _sqlite3.so module.
+	For this development prototype release, the only supported
+	data source backend is SQLite3. The authoritative server
+	requires SQLite 3.3.9 or newer.
+        The <command>b10-xfrin</command> and <command>b10-xfrout</command>
+	modules require the libboost library, libpython3 library,
+	and the Python _sqlite3.so module.
       </para></note>
 <!-- TODO: this will change ... -->
 
@@ -153,11 +154,21 @@
             <simpara>
               <command>b10-xfrin</command> &mdash;
               Incoming zone transfer service.
-              This process is started as needed to transfer a new copy
+              This process is used to transfer a new copy
               of a zone into BIND 10, when acting as a secondary server.
             </simpara>
           </listitem>
 
+          <listitem>
+            <simpara>
+              <command>b10-xfrout</command> &mdash;
+              Outgoing zone transfer service.
+	      This process is used to handle transfer requests to
+	      send a local zone to a remote secondary server,
+	      when acting as a master server.
+            </simpara>
+          </listitem>
+
         </itemizedlist>
       </para>
     </section>
@@ -258,6 +269,17 @@ var/
         </para>
 
         <para>
+	  The Boost Library, Boost Python library, Python Library,
+	  and Python _sqlite3 module are required to enable the
+	  Xfrout and Xfrin support.
+        </para>
+
+        <note><simpara>
+          The Python related libraries and modules need to be built
+          for Python 3.1.
+        </simpara></note>
+
+        <para>
           If the Boost System Library is detected at configure time,
           BIND 10 will be built using an alternative method for
           networking I/O using Boost ASIO support.  This provides
@@ -278,7 +300,7 @@ implementation in BIND 10.
           Building BIND 10 also requires a C++ compiler and
           standard development headers.
           BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
-          4.2.1, 4.3.2, and 4.4.1.
+          4.1.3, 4.2.1, 4.3.2, and 4.4.1.
         </para>
     </section>
 
@@ -295,7 +317,7 @@ implementation in BIND 10.
 
       <note>
         <simpara>
-          The Y1 prototype of the b10-auth server listens on
+          The development prototype of the b10-auth server listens on
           0.0.0.0 (all interfaces) port 5300. (This is not the standard
           domain service port.)
         </simpara>
@@ -421,9 +443,7 @@ implementation in BIND 10.
           and un-reviewed code, is available via the BIND 10 code revision
           control system. This is powered by Subversion and all the BIND 10
           development is public.
-          The leading development is done in the <quote>trunk</quote>
-          and the reviewed code is in
-          <filename>branches/REVIEWED</filename>.
+          The leading development is done in the <quote>trunk</quote>.
         </para>
         <para>
           The code can be checked out from <filename>svn://bind10.isc.org/svn/bind10</filename>; for example to check out the trunk:
@@ -464,43 +484,61 @@ implementation in BIND 10.
           <variablelist>
 
           <varlistentry>
-            <term>--with-boostlib</term>
+            <term>--prefix</term>
+            <listitem>
+              <simpara>Define the the installation location (the
+                default is <filename>/usr/local/</filename>).
+              </simpara>
+            </listitem> 
+          </varlistentry>
+
+          <varlistentry>
+            <term>--with-boost-include</term>
             <listitem> 
-              <simpara>Define the path to find the Boost system library.
+              <simpara>Define the path to find the Boost headers.
               </simpara>
             </listitem> 
           </varlistentry>
 
           <varlistentry>
-            <term>--without-boostlib</term> or
-            <term>--with-boostlib=no</term>
+            <term>--with-boost-lib</term>
             <listitem> 
-              <simpara>Disable the Boost ASIO support.</simpara>
+              <simpara>Define the path to find the Boost library.
+              </simpara>
             </listitem> 
           </varlistentry>
 
           <varlistentry>
-            <term>--with-pythonpath</term>
+            <term>--with-boost-python</term>
             <listitem> 
-              <simpara>Define the path to Python 3.1 if it is not in the
-                standard execution path.
+              <simpara>Define to use the Boost Python library.
               </simpara>
             </listitem> 
           </varlistentry>
 
           <varlistentry>
-            <term>--with-boost-include</term>
+            <term>--with-boost-system</term>
             <listitem> 
-              <simpara>Define the path to find the Boost headers.
+              <simpara>Define to use the Boost System library.
               </simpara>
             </listitem> 
           </varlistentry>
 
           <varlistentry>
-            <term>--prefix</term>
-            <listitem>
-        <simpara>Define the the installation location (the
-          default is <filename>/usr/local/</filename>).
+            <term>--with-pythonpath</term>
+            <listitem> 
+              <simpara>Define the path to Python 3.1 if it is not in the
+                standard execution path.
+              </simpara>
+            </listitem> 
+          </varlistentry>
+
+          <varlistentry>
+            <term>--with-gtest</term>
+            <listitem> 
+              <simpara>Enable building the C++ Unit Tests using the
+                Google Tests framework. Optionally this can define the
+                path to the gtest header files and library.
               </simpara>
             </listitem> 
           </varlistentry>
@@ -508,15 +546,17 @@ implementation in BIND 10.
           </variablelist>
 
         </para>
-  <!-- TODO: gtest, lcov -->
+  <!-- TODO: lcov -->
 
         <para>
           For example, the following configures it to build
     with BOOST ASIO support, find the Boost headers, find the
     Python interpreter, and sets the installation location:
 
-          <screen>$ <userinput>./configure --with-boostlib=/usr/pkg/lib \
+          <screen>$ <userinput>./configure --with-boost-lib=/usr/pkg/lib \
       --with-boost-include=/usr/pkg/include \
+      --with-boost-python \
+      --with-boost-system \
       --with-pythonpath=/usr/pkg/bin/python3.1 \
       --prefix=/opt/bind10</userinput></screen>
         </para>
@@ -652,7 +692,8 @@ implementation in BIND 10.
       The <command>bind10</command> master process will also start up
       <command>b10-cmdctl</command> for admins to communicate with the
       system, <command>b10-auth</command> for Authoritative DNS service,
-      and <command>b10-xfrin</command> for inbound DNS zone transfers.
+      <command>b10-xfrin</command> for inbound DNS zone transfers.
+      and <command>b10-xfrout</command> for outbound DNS zone transfers.
     </para>
 
     <section id="start">
@@ -691,11 +732,13 @@ implementation in BIND 10.
         It listens on 127.0.0.1.
       </para>
       
+<!-- TODO: this is broken, see Trac #111
       <para>
         To select an alternate port for the <command>b10-msgq</command> to
         use, run <command>bind10</command> specifying the option:
-        <screen> $ <userinput>bind10 --msgq-port 9912</userinput></screen>
+        <screen> $ <userinput>bind10 -TODO-msgq-port 9912</userinput></screen>
       </para>
+-->
 
 <!-- TODO: upcoming plans:
 Unix domain sockets
@@ -729,7 +772,7 @@ Unix domain sockets
 <!-- TODO -->
       <note>
         <para>
-          The Y1 prototype release only provides the
+          The development prototype release only provides the
           <command>bindctl</command> as a user interface to
           <command>b10-cmdctl</command>.
           Upcoming releases will provide another interactive command-line
@@ -955,7 +998,7 @@ TODO
     <title>Control and configure user interface</title>
 
     <note><para>
-      For the Y1 prototype release, <command>bindctl</command>
+      For this development prototype release, <command>bindctl</command>
       is the only user interface. It is expected that upcoming
       releases will provide another interactive command-line
       interface and a web-based interface for controlling and
@@ -1000,8 +1043,8 @@ TODO
     </para>
 
     <note><simpara>
-      The Y1 prototype release listens on all interfaces and the non-standard
-      port 5300.
+      This development prototype release listens on all interfaces
+      and the non-standard port 5300.
     </simpara></note>
 
     <section>
@@ -1061,7 +1104,7 @@ This may be a temporary setting until then.
       <title>Data Source Backends</title>
 
       <note><para>
-        For the Y1 prototype release, <command>b10-auth</command>
+        For the development prototype release, <command>b10-auth</command>
         only supports the SQLite3 data source backend.
         Upcoming versions will be able to use multiple different
         data sources, such as MySQL, Berkeley DB, or in-memory DB.
@@ -1131,7 +1174,8 @@ This may be a temporary setting until then.
 
       <note>
       <para>
-        In the Y1 prototype release, only the SQLite3 back end is used.
+        In the development prototype release, only the SQLite3 back
+        end is used.
         By default, it stores the zone data in
         <filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>
         unless the <option>-d</option> switch is used to set the
@@ -1161,6 +1205,69 @@ TODO
 
   </chapter>
 
+  <chapter id="xfrin">
+    <title>Incoming Zone Transfers</title>
+
+    <para>
+      The <command>b10-xfrin</command> process is started by
+      <command>bind10</command>.
+      It can be manually triggered to request an AXFR zone
+      transfer. When received, it is stored in the BIND 10
+      data store, and its records can be served by
+      <command>b10-auth</command>.
+      This allows the BIND 10 server to provide
+      <quote>secondary</quote> service.
+    </para>
+
+    <note><simpara>
+     The current development release of BIND 10 only supports
+     AXFR. (IXFR is not supported.) 
+     It also does not yet support automated SOA checks.
+    </simpara></note>
+
+    <para>
+       To manually trigger a zone transfer to retrieve a remote zone,
+       you may use the <command>bindctl</command> utility.
+       For example, at the <command>bindctl</command> prompt run:
+
+       <screen>&gt; <userinput>Xfrin retransfer zone_name="<option>foo.example.org</option>" master=<option>192.0.2.99</option></userinput></screen>
+    </para>
+
+  </chapter>
+
+  <chapter id="xfrout">
+    <title>Outbound Zone Transfers</title>
+
+    <para>
+      The <command>b10-xfrout</command> process is started by
+      <command>bind10</command>.
+      When the <command>b10-auth</command> authoritative DNS server
+      receives an AXFR request, <command>b10-xfrout</command>
+      sends the zone.
+      This is used to provide master DNS service to share zones
+      to secondary name servers.
+    </para>
+
+    <note><simpara>
+     The current development release of BIND 10 only supports
+     AXFR. (IXFR is not supported.) 
+     It also does not yet support NOTIFY.
+     Access control is not yet provided.
+    </simpara></note>
+
+
+<!--
+TODO:
+xfrout section:
+auth servers checks for AXFR query
+sends the XFR query to the xfrout module
+uses /tmp/auth_xfrout_conn which is a socket
+what is XfroutClient xfr_client??
+/tmp/auth_xfrout_conn is not removed
+-->
+
+  </chapter>
+
 <!-- TODO: how to help: run unit tests, join lists, review trac tickets -->
 
   <!-- <index>    <title>Index</title> </index> -->