[svn] commit: r1509 - in /trunk: doc/userguide/userguide.xml src/bin/auth/b10-auth.8 src/bin/auth/b10-auth.xml src/bin/bind10/bind10.xml src/bin/bindctl/bindctl.1 src/bin/bindctl/bindctl.xml
BIND 10 source code commits
bind10-changes at lists.isc.org
Thu Mar 18 11:22:10 UTC 2010
Author: jreed
Date: Thu Mar 18 11:22:10 2010
New Revision: 1509
Log:
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.)
Modified:
trunk/doc/userguide/userguide.xml
trunk/src/bin/auth/b10-auth.8
trunk/src/bin/auth/b10-auth.xml
trunk/src/bin/bind10/bind10.xml
trunk/src/bin/bindctl/bindctl.1
trunk/src/bin/bindctl/bindctl.xml
Modified: trunk/doc/userguide/userguide.xml
==============================================================================
--- trunk/doc/userguide/userguide.xml (original)
+++ trunk/doc/userguide/userguide.xml Thu Mar 18 11:22:10 2010
@@ -575,11 +575,47 @@
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>
+ <para>
+ 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 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
+ <command>b10-cmdctl</command>.
+ Upcoming releases will provide another interactive command-line
+ interface and a web-based interface.
+ </para></note>
+
+ <para>
+ The <command>b10-cfgmgr</command> daemon can send all
+ specifications and all current settings to the
+ <command>bindctl</command> client (via
+ <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> -->
@@ -595,28 +631,6 @@
administrator.
</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>
-
-<!-- TODO -->
- <note><para>
- The Y1 prototype release only provides the
- <command>bindctl</command> as a user interface to it.
- Upcoming releases will provide another interactive command-line
- interface and a web-based interface.
- </para></note>
-
- <para>
- The <command>b10-cfgmgr</command> daemon can send all
- specifications and all current settings to the
- <command>bindctl</command> client (via
- <command>b10-cmdctl</command>).
- </para>
-
-
<!--
Well the specfiles have a more fixed format (they must contain specific
@@ -643,9 +657,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 -->
<!--
@@ -659,23 +670,44 @@
<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>.
- </para>
+ on HTTPS for clients — the user interface — 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 -->
@@ -779,6 +811,44 @@
</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>
Modified: trunk/src/bin/auth/b10-auth.8
==============================================================================
--- trunk/src/bin/auth/b10-auth.8 (original)
+++ trunk/src/bin/auth/b10-auth.8 Thu Mar 18 11:22:10 2010
@@ -31,7 +31,7 @@
\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 @@
.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 \{\
Modified: trunk/src/bin/auth/b10-auth.xml
==============================================================================
--- trunk/src/bin/auth/b10-auth.xml (original)
+++ trunk/src/bin/auth/b10-auth.xml Thu Mar 18 11:22:10 2010
@@ -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.
Modified: trunk/src/bin/bind10/bind10.xml
==============================================================================
--- trunk/src/bin/bind10/bind10.xml (original)
+++ trunk/src/bin/bind10/bind10.xml Thu Mar 18 11:22:10 2010
@@ -58,6 +58,8 @@
<para>The <command>bind10</command> daemon starts up other
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
Modified: trunk/src/bin/bindctl/bindctl.1
==============================================================================
--- trunk/src/bin/bindctl/bindctl.1 (original)
+++ trunk/src/bin/bindctl/bindctl.1 Thu Mar 18 11:22:10 2010
@@ -29,6 +29,13 @@
\fBbindctl\fR
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
Modified: trunk/src/bin/bindctl/bindctl.xml
==============================================================================
--- trunk/src/bin/bindctl/bindctl.xml (original)
+++ trunk/src/bin/bindctl/bindctl.xml Thu Mar 18 11:22:10 2010
@@ -57,6 +57,15 @@
may be specified
<!-- TODO: as command-line arguments, or --> via its
interactive command interpreter.
+ </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>
More information about the bind10-changes
mailing list