From 0f95a919fa1ff708386a44aa0a57b0878c886e2e Mon Sep 17 00:00:00 2001 From: "Jeremy C. Reed" Date: Wed, 17 Mar 2010 02:39:19 +0000 Subject: [PATCH] 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 --- doc/userguide/userguide.xml | 237 +++++++++++++++++++++++++++++------- 1 file changed, 191 insertions(+), 46 deletions(-) diff --git a/doc/userguide/userguide.xml b/doc/userguide/userguide.xml index f0837a2b81..321acf2578 100644 --- a/doc/userguide/userguide.xml +++ b/doc/userguide/userguide.xml @@ -399,30 +399,150 @@ $ ./configure - - Remote control daemon + + Starting BIND 10 + + To start the BIND 10 service, simply run bind10. + Run it with the --verbose switch to + get additional debugging or diagnostic output. + + + + + + + + Configuration manager + + + The configuration manager, b10-cfgmgr, + 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 + bindctl (or other GUI or web interface) + to communicate with the configuration manager. + + + + + + + The stored configuration file is at + /usr/local/var/bind10/b10-config.db. + (The full path is what was defined at build configure time for + --localstatedir. The default is /usr/local/var/.) + 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 direct communication with the configuration manager is + b10-cmdctl using its REST-ful interface. + This is covered in . + + + + + The Y1 prototype release only provides the + bindctl as a user interface to it. + Upcoming releases will provide another interactive command-line + interface and a web-based interface. + + + + The b10-cfgmgr daemon can send all + specifications and all current settings to the + bindctl client (via + b10-cmdctl). + + + + + + + - b10-cmdctl 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 bind10 master process + (as covered in ). + + + + + + + + Remote control daemon + + + b10-cmdctl 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. + + + + + When b10-cmdctl starts, it firsts asks b10-cfgmgr about what modules are running and what their configuration is (over the - msgq channel), then it will start listening - on HTTPS for clients (i.e. bindctl). + msgq channel). Then it will start listening + on HTTPS for clients, such as bindctl. + - /usr/local/share/bind10/cmdctl-keyfile.pem - contains the Private key, such as a RSA PRIVATE KEY. - - /usr/local/share/bind10/cmdctl-certfile.pem - contains the Certificate. - - - This could be a self-signed certificate or purchased from a + The HTTPS server requires a private key, + such as a RSA PRIVATE KEY. + The default location is at + /usr/local/etc/bind10/cmdctl-keyfile.pem. + (A sample key is at + /usr/local/share/bind10/cmdctl-keyfile.pem.) + It also uses a certificate located at + /usr/local/etc/bind10/cmdctl-certfile.pem. + (A sample certificate is at + /usr/local/share/bind10/cmdctl-certfile.pem.) + This may be a self-signed certificate or purchased from a certification authority. - + + + 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. + + + - - Configuration manager - - The configuration manager, b10-cfgmgr - 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 - bindctl (or other GUI or web interface) - to communicate with the configuration manager. - - + + + + The b10-cmdctl daemon also requires + the user account file located at + /usr/local/etc/bind10/cmdctl-accounts.csv. + This comma-delimited file lists the accounts with a user name, + hashed password, and salt. + (A sample file is at + /usr/local/share/bind10/cmdctl-accounts.csv. + It contains the user named root with the password + bind10.) + + + + + + The administrator may create a user account with the + b10-cmdctl-usermgr tool. + + + + + + + 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. + + + + Configuration specification for b10-cmdctl + + The configuration items for b10-cmdctl are: +key_file +cert_file +accounts_file + + + + + The control commands are: +print_settings +shutdown +print_message + + - - To start the BIND 10 service, run bind10. - Run it with the --verbose switch to - get additional debugging or diagnostic output. - - -