Skip to content

GitLab

Commit 1e5a2021 authored by Jeremy C. Reed's avatar Jeremy C. Reed
Browse files

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
parent e5579aa4
Hide whitespace changes
Inline Side-by-side
doc/userguide/userguide.xml
View file @ 1e5a2021
......@@ -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
View file @ 1e5a2021
......@@ -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>
......
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