[svn] commit: r1303 - in /trunk: doc/userguide/userguide.xml src/bin/cmdctl/b10-cmdctl.xml
BIND 10 source code commits
bind10-changes at lists.isc.org
Wed Mar 10 23:50:24 UTC 2010
Author: jreed
Date: Wed Mar 10 23:50:24 2010
New Revision: 1303
Log:
Add and cleanup some more documention. Thank you jelte for some of the
comments.
Modified:
trunk/doc/userguide/userguide.xml
trunk/src/bin/cmdctl/b10-cmdctl.xml
Modified: trunk/doc/userguide/userguide.xml
==============================================================================
--- trunk/doc/userguide/userguide.xml (original)
+++ trunk/doc/userguide/userguide.xml Wed Mar 10 23:50:24 2010
@@ -32,7 +32,9 @@
<para>
BIND 10 provides separate executables for different tasks.
The standard components include:
+
<itemizedlist>
+
<listitem>
<simpara><command>msgq</command> — message bus</simpara>
</listitem>
@@ -40,11 +42,16 @@
<simpara><command>b10-auth</command> — authoritative DNS server</simpara>
</listitem>
<listitem>
- <simpara><command>b10-cfgmgr</command> — configuration daemon</simpara>
+ <simpara><command>b10-cfgmgr</command> — 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 @@
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 @@
<itemizedlist>
<listitem>
<simpara><filename>bin/</filename> — general tools and
- diagnostic clients</simpara>
+ diagnostic clients.</simpara>
</listitem>
<listitem>
<simpara><filename>lib/</filename> — libraries and
- python modules</simpara>
+ python modules.</simpara>
</listitem>
<listitem>
<simpara><filename>libexec/bind10/</filename> — 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> — commands used by
- the system administrator
+ the system administrator.
</simpara>
</listitem>
<listitem>
<simpara><filename>share/bind10/</filename> — configuration
- specifications
+ specifications.
</simpara>
</listitem>
<listitem>
<simpara><filename>share/man/</filename> — manual pages (online
- documentation)
+ documentation).
</simpara>
</listitem>
<listitem>
- <simpara><filename>var/bind10/</filename> — configuration database
+ <simpara><filename>var/bind10/</filename> — configuration and
+ data source databases.
+<!-- TODO: move the sqlite3 database there -->
</simpara>
</listitem>
</itemizedlist>
</para>
</sect1>
-
- <sect1>
- <title>Starting BIND 10</title>
+
+ </chapter>
+
+ <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 @@
<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>
Modified: trunk/src/bin/cmdctl/b10-cmdctl.xml
==============================================================================
--- trunk/src/bin/cmdctl/b10-cmdctl.xml (original)
+++ trunk/src/bin/cmdctl/b10-cmdctl.xml Wed Mar 10 23:50:24 2010
@@ -98,15 +98,18 @@
<!-- 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>
— 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>
- — contains the RSA Private key and the Certificate.
+ <para><filename>/usr/local/share/bind10/cmdctl-keyfile.pem</filename>
+ — contains the Private key.
+ </para>
+ <para><filename>/usr/local/share/bind10/cmdctl-certfile.pem</filename>
+ — contains the Certificate.
</para>
</refsect1>
More information about the bind10-changes
mailing list