Add and cleanup some more documention. Thank you jelte for some of the

comments.


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

doc/userguide/userguide.xml

@@ -32,7 +32,9 @@
     <para>
       BIND 10 provides separate executables for different tasks.
       The standard components include:
+
       <itemizedlist>
+
       <listitem>
       <simpara><command>msgq</command> &mdash; message bus</simpara>
       </listitem>
@@ -40,11 +42,16 @@
       <simpara><command>b10-auth</command> &mdash; authoritative DNS server</simpara>
       </listitem>
       <listitem>
-      <simpara><command>b10-cfgmgr</command> &mdash; configuration daemon</simpara>
+      <simpara><command>b10-cfgmgr</command> &mdash; configuration manager</simpara>
       </listitem>
       <listitem>
       <simpara><command>b10-cmdctl</command> <!-- TODO --></simpara>
       </listitem>
+
+      <listitem>
+      <simpara><command>b10-xfrin</command> <!-- TODO --></simpara>
+      </listitem>
+
       </itemizedlist>
     </para>
 
@@ -163,26 +170,46 @@ var/
 	and <command>automake</command> version 1.11 or better (for
 	working Python 3.1 tests).
       </para>
+      <note><para>
+        Some operating systems do not provide these in their
+        default installation nor standard packages collections.
+        You may need to install them separately.
+      </para></note>
       </sect2>
     </sect1>
 
     <sect1>
-      <title>Dependencies</title>
+      <title>Required Software</title>
       <para>
         BIND 10 requires Python 3.1, SQLite 3.3.9 or newer,
         and the Python _sqlite3.so module.
+<!-- TODO: list where to get these from -->
 <!-- TODO: this will change ... -->
+      </para>
+      <note><para>
+        Some operating systems do not provide these in their
+        default installation nor standard packages collections.
+        You may need to install them separately.
+      </para></note>
+      <para>
         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.
+<!-- TODO: what about boost? ship with it or not? -->
       </para>
     </sect1>
 
     <sect1>
       <title>Supported Platforms</title>
       <para>
-        BIND 10 builds have been tested on Debian GNU/Linux 5,
-        NetBSD 5, Solaris 10, and FreeBSD 7. It has been tested on
-        Sparc, i386, and amd64 hardware platforms.
+	BIND 10 builds have been tested on Debian GNU/Linux 5,
+	Ubuntu 9.10, NetBSD 5, Solaris 10, FreeBSD 7, and CentOS
+	Linux 5.3.
+
+	It has been tested on Sparc, i386, and amd64 hardware
+	platforms.
+
         It is planned for BIND 10 to build, install and run on
         Windows and standard Unix-type platforms.
       </para>
@@ -227,43 +254,48 @@ var/
       <itemizedlist>
       <listitem>
       <simpara><filename>bin/</filename> &mdash; general tools and
-      diagnostic clients</simpara>
+      diagnostic clients.</simpara>
       </listitem>
       <listitem>
       <simpara><filename>lib/</filename> &mdash; libraries and
-      python modules</simpara>
+      python modules.</simpara>
       </listitem>
       <listitem>
       <simpara><filename>libexec/bind10/</filename> &mdash; executables that
       a user wouldn't normally run directly. Nor would they be used
-      independently. These are the BIND 10 modules.
+      independently. These are the BIND 10 modules which are daemons
+      started by the <command>bind10</command> tool.
       </simpara>
       </listitem>
       <listitem>
       <simpara><filename>sbin/</filename> &mdash; commands used by
-      the system administrator
+      the system administrator.
       </simpara>
       </listitem>
       <listitem>
       <simpara><filename>share/bind10/</filename> &mdash; configuration
-        specifications
+        specifications.
       </simpara>
       </listitem>
       <listitem>
       <simpara><filename>share/man/</filename> &mdash; manual pages (online
-        documentation)
+        documentation).
       </simpara>
       </listitem>
       <listitem>
-      <simpara><filename>var/bind10/</filename> &mdash; configuration database
+      <simpara><filename>var/bind10/</filename> &mdash; configuration and
+        data source databases.
+<!-- TODO: move the sqlite3 database there -->
       </simpara>
       </listitem>
       </itemizedlist>
     </para>
     </sect1>
+  
+  </chapter>
 
-    <sect1>
-    <title>Starting BIND 10</title>
+  <chapter id="bind10">
+    <title>Starting BIND10 with bind10</title>
     <para>
       BIND 10 provides the <command>bind10</command> command which 
       starts up the required daemons to provide the message
@@ -278,8 +310,87 @@ var/
       <command>bind10</command> connects to it, 
       runs the configuration manager, and reads its own configuration.
       Then it starts the other modules.
-   </para>
-   </sect1>
+    </para>
+
+    <para>
+      The <command>msgq</command> and <command>b10-cfgmgr</command>
+      services make up the core. The <command>msgq</command> daemon
+      provides the communication channel between every part of the system.
+      And <command>b10-cfgmgr</command> is always needed by every
+      module, if only to send information about themselves somewhere,
+      but more importantly to ask about their own settings, and
+      about other modules.
+    </para>
+
+
+    <sect1 id="cmdctl">
+      <title>Remote control daemon</title>
+
+    <para>
+      <command>b10-cmdctl</command> is the gateway between
+      administrators and the whole system; when it starts it firsts
+      asks <command>b10-cfgmgr</command> about what modules are
+      running and what their configuration is (over the
+      <command>msgq</command> channel), then it will start listening
+      on HTTPS for clients (i.e. <command>bindctl</command>).
+    </para>
+<!-- TODO: replace /usr/local -->
+<!-- TODO: permissions -->
+    <para><filename>/usr/local/share/bind10/cmdctl-keyfile.pem</filename>
+      contains the Private key, such as a RSA PRIVATE KEY.
+    </para>
+    <para><filename>/usr/local/share/bind10/cmdctl-certfile.pem</filename>
+      contains the Certificate.
+    </para>
+    <para>
+      This could be a self-signed certificate or purchased from a
+      certification authority.
+    </para>
+    </sect1>
+
+<!--
+    <para>
+(08:20:56) shane: It is in theory possible to run without cmdctl.
+(08:21:02) shane: I think we discussed this.
+    </para>
+-->
+    <sect1 id="cfgmgr">
+      <title>Configuration manager</title>
+      <para>
+	 The configuration manager, <command>b10-cfgmgr</command>
+	 handles all BIND 10 system configuration.  It provides
+	 persistent storage for configuration, and notifies running
+	 modules of configuration changes.  The administrator
+	 doesn't use it directly, but uses a tool like
+	 <command>bindctl</command> (or other GUI or web interface)
+         to communicate with the configuration manager.
+      </para>
+<!--
+      <para>
+        The stored configuration file is ...
+TODO
+      </para>
+-->
+    </sect1>
+
+<!--
+TODO
+    <para>
+bindctl talks to b10-cmdctl
+    </para>
+cfgmanager can send all specifications (and all current settings)
+to bindctl (through cmdctl in fact), so an admin can simply run bindctl,
+do config show, and it shows all modules; config show >module> shows all
+options for that module
+
+-->
+
+    <para>
+      To start the BIND 10 service, run <command>bind10</command>.
+      Run it with the <command>--verbose</command> switch to
+      get additional debugging or diagnostic output.
+    </para>
+<!-- TODO: note it doesn't go into background -->
 
   </chapter>
 

src/bin/cmdctl/b10-cmdctl.xml

@@ -98,15 +98,18 @@ NO command line arguments
 <!-- TODO: permissions -->
 <!-- TODO: what about multiple accounts? -->
 <!-- TODO: shouldn't the password file name say cmdctl in it? -->
-    <para><filename>/usr/local/share/bind10/passwd.csv</filename>
+    <para><filename>/usr/local/share/bind10/cmdctl-accounts.csv</filename>
       &mdash; account database containing the name, hashed password,
       and the salt.
     </para>
 <!-- TODO: replace /usr/local -->
 <!-- TODO: permissions -->
 <!-- TODO: shouldn't have both in same file, will be configurable -->
-    <para><filename>/usr/local/share/bind10/b10-cmdctl.pem</filename>
-      &mdash; contains the RSA Private key and the Certificate.
+    <para><filename>/usr/local/share/bind10/cmdctl-keyfile.pem</filename>
+      &mdash; contains the Private key.
+    </para>
+    <para><filename>/usr/local/share/bind10/cmdctl-certfile.pem</filename>
+      &mdash; contains the Certificate.
     </para>
   </refsect1>