Add more docs, fix some docs.

(This updates bind10.xml with comments, but the generated bind10.8
didn't change so now that didn't get committed, so the timestamps
are behind so a "make" may end up trying to build it. I need to fix
the build of this to not require xsltproc for others.)


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

doc/userguide/userguide.xml

@@ -575,36 +575,24 @@ Unix domain sockets
 	 persistent storage for configuration, and notifies running
 	 modules of configuration changes.</para>
 
-      <para>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>
-
-<!-- TODO: what about run time config to change this? -->
-<!-- jelte: > config set cfgmgr/config_database <file> -->
-<!-- TODO: what about command line switch to change this? -->
       <para>
-        The stored configuration file is at
-        <filename>/usr/local/var/bind10/b10-config.db</filename>.
-        (The full path is what was defined at build configure time for
-        --localstatedir. The default is <filename>/usr/local/var/</filename>.)
-	The format is loosely based on JSON and is directly parseable
-	python, but this may change in a future version.
-	This configuration data file is not manually edited by the
-	administrator.
+	The <command>b10-auth</command> and <command>b10-xfrin</command>
+	daemons and other components receive their configurations
+	from the configuration manager over the <command>msgq</command>
+	command channel.
       </para>
 
-      <para>
-        The direct communication with the configuration manager is
-        <command>b10-cmdctl</command> using its REST-ful interface.
-        This is covered in <xref linkend="cmdctl"/>.
+      <para>The administrator doesn't connect to it directly, but
+        uses a user interface to communicate with the configuration
+        manager via <command>b10-cmdctl</command>'s REST-ful interface.
+        <command>b10-cmdctl</command> is covered in <xref linkend="cmdctl"/>.
       </para>
 
 <!-- TODO -->
       <note><para>
 	The Y1 prototype release only provides the
-	<command>bindctl</command> as a user interface to it.
+	<command>bindctl</command> as a user interface to
+        <command>b10-cmdctl</command>.
         Upcoming releases will provide another interactive command-line
         interface and a web-based interface.
       </para></note>
@@ -616,6 +604,32 @@ Unix domain sockets
 	<command>b10-cmdctl</command>).
       </para>
 
+      <para>
+        <command>b10-cfgmgr</command> relays configurations received
+        from <command>b10-cmdctl</command> to the appropriate modules.
+      </para>
+<!-- TODO:
+        Configuration settings for itself are defined as ConfigManager.
+TODO: show examples
+-->
+
+<!-- TODO:
+config changes are actually commands to cfgmgr
+-->
+
+<!-- TODO: what about run time config to change this? -->
+<!-- jelte: > config set cfgmgr/config_database <file> -->
+<!-- TODO: what about command line switch to change this? -->
+      <para>
+        The stored configuration file is at
+        <filename>/usr/local/var/bind10/b10-config.db</filename>.
+        (The full path is what was defined at build configure time for
+        --localstatedir. The default is <filename>/usr/local/var/</filename>.)
+	The format is loosely based on JSON and is directly parseable
+	python, but this may change in a future version.
+	This configuration data file is not manually edited by the
+	administrator.
+      </para>
 
 <!--
 
@@ -644,9 +658,6 @@ configuration for configuration manager itself. And perhaps we might
 change the messaging protocol, but an admin should never see any of that
 -->
 
-     <para>
-     </para>
-
 <!-- TODO: show examples, test this -->
 <!--
 , so an admin can simply run bindctl,
@@ -659,24 +670,45 @@ options for that module
   <chapter id="cmdctl">
     <title>Remote control daemon</title>
 
-      <para>
-        <command>b10-cmdctl</command> is the gateway between
-        administrators and the BIND 10 system.
-        It is a HTTPS server that uses standard HTTP Digest
-        Authentication for username and password validation.
-        It provides a REST-ful interface for accessing and controlling
-        BIND 10.
-      </para>
+    <para>
+      <command>b10-cmdctl</command> is the gateway between
+      administrators and the BIND 10 system.
+      It is a HTTPS server that uses standard HTTP Digest
+      Authentication for username and password validation.
+      It provides a REST-ful interface for accessing and controlling
+      BIND 10.
+    </para>
 <!-- TODO: copy examples from wiki, try with wget -->
 
-      <para>
+    <para>
       When <command>b10-cmdctl</command> 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, such as <command>bindctl</command>.
+      on HTTPS for clients &mdash; the user interface &mdash; such
+      as <command>bindctl</command>.
     </para>
 
+    <para>
+      <command>b10-cmdctl</command> directly sends commands
+      (received from the user interface) to the specified component.
+      Configuration changes are actually commands to
+      <command>b10-cfgmgr</command> so are sent there.
+    </para>
+
+<!--
+TODO:
+"For bindctl to list a module's available configurations and
+available commands, it communicates over the cmdctl REST interface.
+cmdctl then asks cfgmgr over the msgq command channel. Then cfgmgr
+asks the module for its specification and also cfgmgr looks in its
+own configuration database for current values."
+
+(05:32:03) jelte: i think cmdctl doesn't request it upon a incoming
+GET, but rather requests it once and then listens in for updates,
+but you might wanna check with likun
+-->
+
 <!-- TODO: replace /usr/local -->
 <!-- TODO: permissions -->
     <para>The HTTPS server requires a private key,
@@ -779,6 +811,44 @@ TODO
 
   </chapter>
 
+  <chapter id="bindctl">
+    <title>Control and configure user interface</title>
+
+    <note><para>
+      For the Y1 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
+      configuring BIND 10.
+    </para></note>
+
+    <para>
+      The <command>bindctl</command> tool provides an interactive
+      prompt for configuring, controlling, and querying the BIND 10
+      components.
+      It communicates directly with a RESTful interface over HTTPS
+      provided by <command>b10-cmdctl</command>. It doesn't
+      communicate to any other components directly.
+    </para>
+
+<!-- TODO: explain and show interface -->
+
+    <para>
+      Configuration changes are actually commands to
+      <command>b10-cfgmgr</command>. So when <command>bindctl</command>
+      sends a configuration, it is sent to <command>b10-cmdctl</command>
+      (over a HTTPS connection); then <command>b10-cmdctl</command>
+      sends the command (over a <command>msgq</command> command
+      channel) to <command>b10-cfgmgr</command> which then stores
+      the details and relays (over a <command>msgq</command> command
+      channel) the configuration on to the specified module.
+    </para>
+
+    <para>
+    </para>
+
+  </chapter>
+
   <chapter id="authserver">
     <title>Authoritative Server</title>
     <para>

src/bin/auth/b10-auth.8

@@ -31,7 +31,7 @@ daemon provides the BIND 10 authoritative DNS server\&. Normally it is started b
 \fBbind10\fR(8)
 master process\&.
 .PP
-This daemon communicates over a
+This daemon communicates with other BIND 10 components over a
 \fBmsgq\fR(8)
 C\-Channel connection\&. If this connection is not established,
 \fBb10\-auth\fR
@@ -39,8 +39,9 @@ will exit\&.
 .PP
 It also receives its configurations from
 \fBb10-cfgmgr\fR(8)
-using the REST\-ful interface provided by
-\fBb10-cmdctl\fR(8)\&. It will honor the
+(via the
+\fBmsgq\fR(8)
+command channel)\&. It will honor the
 \fIdatabase_file\fR
 configuration to point to the SQLite3 zone file\&.
 .if n \{\

src/bin/auth/b10-auth.xml

@@ -62,19 +62,19 @@
     </para>
 
     <para>
-      This daemon communicates over a
+      This daemon communicates with other BIND 10 components over a
       <citerefentry><refentrytitle>msgq</refentrytitle><manvolnum>8</manvolnum></citerefentry>
       C-Channel connection.  If this connection is not established,
       <command>b10-auth</command> will exit.
-<!-- TODO what if connection closes later, will b10-auth exit? -->
+<!-- TODO what if msgq connection closes later, will b10-auth exit? -->
     </para>
 
-
     <para>
-     It also receives its configurations from
+      It also receives its configurations from
 <citerefentry><refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-      using the REST-ful interface provided by
-      <citerefentry><refentrytitle>b10-cmdctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+      (via the
+      <citerefentry><refentrytitle>msgq</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      command channel).
       It will honor the <emphasis>database_file</emphasis> configuration
       to point to the SQLite3 zone file.
 

src/bin/bind10/bind10.xml

@@ -59,6 +59,8 @@
     BIND 10 required daemons.  It handles restarting of exiting
     programs and also the shutdown of all managed daemons.</para>
 
+<!-- TODO: list what it starts here? -->
+
 <!-- TODO
     <para>The configuration of the <command>bind10</command> daemon
     is defined in the TODO configuration file, as described in the

src/bin/bindctl/bindctl.1

@@ -30,6 +30,13 @@ The
 tool is a user interface to the BIND 10 services\&. The program can be used to control the components and configure the BIND 10 options\&. The options may be specified
 via its interactive command interpreter\&.
 .PP
+
+\fBbindctl\fR
+communicates over the REST\-ful interface provided by
+\fBb10-cmdctl\fR(8)\&. The
+\fBb10-cfgmgr\fR(8)
+daemon stores the configurations and defines the commands\&.
+.PP
 The
 \fBbindctl\fR
 prompt shows

src/bin/bindctl/bindctl.xml

@@ -60,6 +60,15 @@
     </para>
 
     <para>
+      <command>bindctl</command> communicates over the REST-ful
+      interface provided by
+      <citerefentry><refentrytitle>b10-cmdctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+      The
+<citerefentry><refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      daemon stores the configurations and defines the commands.
+    </para>
+
+    <para>
       The <command>bindctl</command> prompt shows
       <quote>&gt; </quote>.
        The prompt will also display the location if changed.