Commit 7560be6a authored by Jeremy C. Reed's avatar Jeremy C. Reed

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
parent 84662a2d
......@@ -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>
......
......@@ -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 \{\
......
......@@ -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.
......
......@@ -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
......
......@@ -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
......
......@@ -59,6 +59,15 @@
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>
The <command>bindctl</command> prompt shows
<quote>&gt; </quote>.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment