Commit 0f95a919 authored by Jeremy C. Reed's avatar Jeremy C. Reed
Browse files

Split up into more chapters. Add more content for cfgmgr and cmdctl.


git-svn-id: svn://bind10.isc.org/svn/bind10/trunk@1472 e5f2f494-b856-4b98-b285-d166d9295462
parent b95100e3
......@@ -399,30 +399,150 @@ $ <userinput>./configure</userinput></screen>
</para>
<sect1 id="cmdctl">
<title>Remote control daemon</title>
<sect1 id="start">
<title>Starting BIND 10</title>
<para>
To start the BIND 10 service, simply 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 -->
</sect1>
</chapter>
<chapter 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.</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.
</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>
<!-- TODO: show examples, test this -->
<!--
, so an admin can simply run bindctl,
do config show, and it shows all modules; config show >module> shows all
options for that module
-->
<!--
Well the specfiles have a more fixed format (they must contain specific
stuff), but those are also directly parseable python structures (and
'coincidentally', our data::element string representation is the same)
loosely based on json, tweaked to be directly parseable in python, but a
subset of that.
wiki page is http://bind10.isc.org/wiki/DataElementDesign
nope, spec files are written by module developers, and db should be done
through bindctl and friends
-->
<para>
<command>b10-cmdctl</command> is the gateway between
administrators and the whole system; when it starts it firsts
The configuration manager does not have any command line arguments.
Normally it is not started manually, but is automatically
started using the <command>bind10</command> master process
(as covered in <xref linkend="bind10"/>).
</para>
<!-- TODO: upcoming plans:
configuration for configuration manager itself. And perhaps we might
change the messaging protocol, but an admin should never see any of that
-->
</chapter>
<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>
<!-- TODO: copy examples from wiki, try with wget -->
<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 (i.e. <command>bindctl</command>).
<command>msgq</command> channel). Then it will start listening
on HTTPS for clients, such as <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
<para>The HTTPS server requires a private key,
such as a RSA PRIVATE KEY.
The default location is at
<filename>/usr/local/etc/bind10/cmdctl-keyfile.pem</filename>.
(A sample key is at
<filename>/usr/local/share/bind10/cmdctl-keyfile.pem</filename>.)
It also uses a certificate located at
<filename>/usr/local/etc/bind10/cmdctl-certfile.pem</filename>.
(A sample certificate is at
<filename>/usr/local/share/bind10/cmdctl-certfile.pem</filename>.)
This may be a self-signed certificate or purchased from a
certification authority.
</para>
</sect1>
<note><para>
The HTTPS server is configured to require a PEM certificate from
the client.
The BIND 10 installation provides a PEM bundle that matches
the sample key and certificate.
</para></note>
<!-- TODO: cross-ref -->
<!-- TODO: why is this required? -->
<!--
<para>
......@@ -430,46 +550,71 @@ $ <userinput>./configure</userinput></screen>
(08:21:02) shane: I think we discussed this.
</para>
-->
<sect1 id="cfgmgr">
<title>Configuration manager</title>
<!-- TODO: Please check https://bind10.isc.org/wiki/cmd-ctrld -->
<para>
The <command>b10-cmdctl</command> daemon also requires
the user account file located at
<filename>/usr/local/etc/bind10/cmdctl-accounts.csv</filename>.
This comma-delimited file lists the accounts with a user name,
hashed password, and salt.
(A sample file is at
<filename>/usr/local/share/bind10/cmdctl-accounts.csv</filename>.
It contains the user named <quote>root</quote> with the password
<quote>bind10</quote>.)
</para>
<!-- TODO
openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes
but that is a single file, maybethis should go back to that format?
-->
<para>
The administrator may create a user account with the
<command>b10-cmdctl-usermgr</command> tool.
</para>
<!-- TODO: show example -->
<!-- TODO: does cmdctl need to be restarted to change cert or key
or accounts database -->
<para>
By default the HTTPS server listens on the localhost port 8080.
The port can be set by using the --port command line option.
The address to listen on can be set using the --address command
line argument.
Each HTTPS connection is stateless and timesout in 1200 seconds
by default. This can be
redefined by using the --idle-timeout command line argument.
</para>
<sect1 id="cmdctl.spec">
<title>Configuration specification for b10-cmdctl</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.
The configuration items for <command>b10-cmdctl</command> are:
key_file
cert_file
accounts_file
</para>
<!--
<!-- TODO -->
<para>
The stored configuration file is ...
TODO
The control commands are:
print_settings
shutdown
print_message
</para>
-->
<!-- TODO -->
</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
(12:21:30) jinmei: I'd like to have sample session using a command line www client such as wget
(12:21:33) jinmei: btw
-->
<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>
<chapter id="authserver">
......
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