Browse Source

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

Jeremy C. Reed 15 years ago
parent
commit
b37c36a508
1 changed files with 142 additions and 35 deletions
  1. 142 35
      doc/guide/bind10-guide.xml

+ 142 - 35
doc/guide/bind10-guide.xml

@@ -71,11 +71,12 @@
       </para>
       </para>
 
 
       <note><para>
       <note><para>
-        For the Y1 prototype release, the only supported data source
+	For this development prototype release, the only supported
-        backend is SQLite3. The authoritative server requires
+	data source backend is SQLite3. The authoritative server
-        SQLite 3.3.9 or newer,
+	requires SQLite 3.3.9 or newer.
-        and the <command>b10-xfrin</command> module requires the
+        The <command>b10-xfrin</command> and <command>b10-xfrout</command>
-        Python _sqlite3.so module.
+	modules require the libboost library, libpython3 library,
+	and the Python _sqlite3.so module.
       </para></note>
       </para></note>
 <!-- TODO: this will change ... -->
 <!-- TODO: this will change ... -->
 
 
@@ -153,11 +154,21 @@
             <simpara>
             <simpara>
               <command>b10-xfrin</command> &mdash;
               <command>b10-xfrin</command> &mdash;
               Incoming zone transfer service.
               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.
               of a zone into BIND 10, when acting as a secondary server.
             </simpara>
             </simpara>
           </listitem>
           </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>
         </itemizedlist>
       </para>
       </para>
     </section>
     </section>
@@ -258,6 +269,17 @@ var/
         </para>
         </para>
 
 
         <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,
           If the Boost System Library is detected at configure time,
           BIND 10 will be built using an alternative method for
           BIND 10 will be built using an alternative method for
           networking I/O using Boost ASIO support.  This provides
           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
           Building BIND 10 also requires a C++ compiler and
           standard development headers.
           standard development headers.
           BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
           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>
         </para>
     </section>
     </section>
 
 
@@ -295,7 +317,7 @@ implementation in BIND 10.
 
 
       <note>
       <note>
         <simpara>
         <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
           0.0.0.0 (all interfaces) port 5300. (This is not the standard
           domain service port.)
           domain service port.)
         </simpara>
         </simpara>
@@ -421,9 +443,7 @@ implementation in BIND 10.
           and un-reviewed code, is available via the BIND 10 code revision
           and un-reviewed code, is available via the BIND 10 code revision
           control system. This is powered by Subversion and all the BIND 10
           control system. This is powered by Subversion and all the BIND 10
           development is public.
           development is public.
-          The leading development is done in the <quote>trunk</quote>
+          The leading development is done in the <quote>trunk</quote>.
-          and the reviewed code is in
-          <filename>branches/REVIEWED</filename>.
         </para>
         </para>
         <para>
         <para>
           The code can be checked out from <filename>svn://bind10.isc.org/svn/bind10</filename>; for example to check out the trunk:
           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>
           <variablelist>
 
 
           <varlistentry>
           <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> 
             <listitem> 
-              <simpara>Define the path to find the Boost system library.
+              <simpara>Define the path to find the Boost headers.
               </simpara>
               </simpara>
             </listitem> 
             </listitem> 
           </varlistentry>
           </varlistentry>
 
 
           <varlistentry>
           <varlistentry>
-            <term>--without-boostlib</term> or
+            <term>--with-boost-lib</term>
-            <term>--with-boostlib=no</term>
             <listitem> 
             <listitem> 
-              <simpara>Disable the Boost ASIO support.</simpara>
+              <simpara>Define the path to find the Boost library.
+              </simpara>
             </listitem> 
             </listitem> 
           </varlistentry>
           </varlistentry>
 
 
           <varlistentry>
           <varlistentry>
-            <term>--with-pythonpath</term>
+            <term>--with-boost-python</term>
             <listitem> 
             <listitem> 
-              <simpara>Define the path to Python 3.1 if it is not in the
+              <simpara>Define to use the Boost Python library.
-                standard execution path.
               </simpara>
               </simpara>
             </listitem> 
             </listitem> 
           </varlistentry>
           </varlistentry>
 
 
           <varlistentry>
           <varlistentry>
-            <term>--with-boost-include</term>
+            <term>--with-boost-system</term>
             <listitem> 
             <listitem> 
-              <simpara>Define the path to find the Boost headers.
+              <simpara>Define to use the Boost System library.
               </simpara>
               </simpara>
             </listitem> 
             </listitem> 
           </varlistentry>
           </varlistentry>
 
 
           <varlistentry>
           <varlistentry>
-            <term>--prefix</term>
+            <term>--with-pythonpath</term>
-            <listitem>
+            <listitem> 
-        <simpara>Define the the installation location (the
+              <simpara>Define the path to Python 3.1 if it is not in the
-          default is <filename>/usr/local/</filename>).
+                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>
               </simpara>
             </listitem> 
             </listitem> 
           </varlistentry>
           </varlistentry>
@@ -508,15 +546,17 @@ implementation in BIND 10.
           </variablelist>
           </variablelist>
 
 
         </para>
         </para>
-  <!-- TODO: gtest, lcov -->
+  <!-- TODO: lcov -->
 
 
         <para>
         <para>
           For example, the following configures it to build
           For example, the following configures it to build
     with BOOST ASIO support, find the Boost headers, find the
     with BOOST ASIO support, find the Boost headers, find the
     Python interpreter, and sets the installation location:
     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-include=/usr/pkg/include \
+      --with-boost-python \
+      --with-boost-system \
       --with-pythonpath=/usr/pkg/bin/python3.1 \
       --with-pythonpath=/usr/pkg/bin/python3.1 \
       --prefix=/opt/bind10</userinput></screen>
       --prefix=/opt/bind10</userinput></screen>
         </para>
         </para>
@@ -652,7 +692,8 @@ implementation in BIND 10.
       The <command>bind10</command> master process will also start up
       The <command>bind10</command> master process will also start up
       <command>b10-cmdctl</command> for admins to communicate with the
       <command>b10-cmdctl</command> for admins to communicate with the
       system, <command>b10-auth</command> for Authoritative DNS service,
       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>
     </para>
 
 
     <section id="start">
     <section id="start">
@@ -691,11 +732,13 @@ implementation in BIND 10.
         It listens on 127.0.0.1.
         It listens on 127.0.0.1.
       </para>
       </para>
       
       
+<!-- TODO: this is broken, see Trac #111
       <para>
       <para>
         To select an alternate port for the <command>b10-msgq</command> to
         To select an alternate port for the <command>b10-msgq</command> to
         use, run <command>bind10</command> specifying the option:
         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>
       </para>
+-->
 
 
 <!-- TODO: upcoming plans:
 <!-- TODO: upcoming plans:
 Unix domain sockets
 Unix domain sockets
@@ -729,7 +772,7 @@ Unix domain sockets
 <!-- TODO -->
 <!-- TODO -->
       <note>
       <note>
         <para>
         <para>
-          The Y1 prototype release only provides the
+          The development prototype release only provides the
           <command>bindctl</command> as a user interface to
           <command>bindctl</command> as a user interface to
           <command>b10-cmdctl</command>.
           <command>b10-cmdctl</command>.
           Upcoming releases will provide another interactive command-line
           Upcoming releases will provide another interactive command-line
@@ -955,7 +998,7 @@ TODO
     <title>Control and configure user interface</title>
     <title>Control and configure user interface</title>
 
 
     <note><para>
     <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
       is the only user interface. It is expected that upcoming
       releases will provide another interactive command-line
       releases will provide another interactive command-line
       interface and a web-based interface for controlling and
       interface and a web-based interface for controlling and
@@ -1000,8 +1043,8 @@ TODO
     </para>
     </para>
 
 
     <note><simpara>
     <note><simpara>
-      The Y1 prototype release listens on all interfaces and the non-standard
+      This development prototype release listens on all interfaces
-      port 5300.
+      and the non-standard port 5300.
     </simpara></note>
     </simpara></note>
 
 
     <section>
     <section>
@@ -1061,7 +1104,7 @@ This may be a temporary setting until then.
       <title>Data Source Backends</title>
       <title>Data Source Backends</title>
 
 
       <note><para>
       <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.
         only supports the SQLite3 data source backend.
         Upcoming versions will be able to use multiple different
         Upcoming versions will be able to use multiple different
         data sources, such as MySQL, Berkeley DB, or in-memory DB.
         data sources, such as MySQL, Berkeley DB, or in-memory DB.
@@ -1131,7 +1174,8 @@ This may be a temporary setting until then.
 
 
       <note>
       <note>
       <para>
       <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
         By default, it stores the zone data in
         <filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>
         <filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>
         unless the <option>-d</option> switch is used to set the
         unless the <option>-d</option> switch is used to set the
@@ -1161,6 +1205,69 @@ TODO
 
 
   </chapter>
   </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 -->
 <!-- TODO: how to help: run unit tests, join lists, review trac tickets -->
 
 
   <!-- <index>    <title>Index</title> </index> -->
   <!-- <index>    <title>Index</title> </index> -->