bind10-guide.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash  "&#x2014;" >
<!ENTITY % version SYSTEM "version.ent">
%version;
]>

<!--
 - Copyright (C) 2010-2014  Internet Systems Consortium, Inc. ("ISC")
 -
 - Permission to use, copy, modify, and/or distribute this software for any
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 -
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
-->

<book>
  <?xml-stylesheet href="bind10-guide.css" type="text/css"?>

  <bookinfo>
    <title>Kea Guide</title>
    <subtitle>Administrator Reference for Kea</subtitle>

    <copyright>
      <year>2010-2014</year><holder>Internet Systems Consortium, Inc.</holder>
    </copyright>

    <abstract>
      <para>
        Kea is an open source implementation of the Dynamic Host Configuration
        Protocol (DHCP) servers, developed and maintained by Internet Systems
        Consortium (ISC).
      </para>

      <!-- TODO: The VERSION needs to be updated -->
      <para>
        This is the reference guide for Kea version &__VERSION__;.
        The most up-to-date version of this document (in PDF, HTML,
        and plain text formats), along with other documents for
        Kea, can be found at <ulink url="http://kea.isc.org/docs"/>.
        </para> </abstract>

      <releaseinfo>This is the reference guide for Kea version
        &__VERSION__;.</releaseinfo>

  </bookinfo>

  <!-- todo: Preface is now empty, but leave it around now
  <preface>
    <title>Preface</title>
  </preface>
-->
  <chapter id="intro">
    <title>Introduction</title>
    <para>
      Kea is the next generation of DHCP servers developed by ISC.
      It supports both DHCPv4 and DHCPv6 protocols along with their
      extensions (e.g. prefix delegation). It also supports the dynamic
      updates to DNS.
    </para>

    <para>
      Kea has been initially developed as a part of the BIND 10 framework
      (<ulink url="http://bind10.isc.org"/>). In early 2014, ISC
      made the decision to discontinue active development of BIND 10 and
      continue development of Kea as standalone DHCP servers. As a result,
      the components and libraries related to the BIND10 framework and DNS
      are going to be removed from the Kea source tree over time.
      In order to remove the dependency on Python 3, the BIND 10 framework
      will be replaced by the server startup and configuration mechanisms
      written in C++.
    </para>

    <note>
      <simpara>Kea has been implemented in BIND 10 framework and to certain extent
      it still depends on various BIND 10 libraries. It also requires the BIND 10
      framework to run, because BIND 10 configuration mechanisms are used to
      configure Kea. As a result, this document still refers to BIND 10 in many
      paragraphs. The term "BIND 10" in the context of this document means
      "BIND 10 libraries and applications which are necessary for Kea to run
      and configure". The term "Kea" means "the collection of binaries and libraries
      which, as a whole, implement the DHCP protocols.
      </simpara>
    </note>

    <para>
      This guide covers Kea version &__VERSION__;.
    </para>

    <section>
      <!-- todo: revisit (maybe extend) the list of supported platforms -->
      <title>Supported Platforms</title>
      <para>
        Kea builds have been tested on (in no particular order)
        Debian GNU/Linux 6 and unstable, Ubuntu 9.10, NetBSD 5,
        Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3,
        MacOS 10.6 and 10.7, and OpenBSD 5.1.

        It has been tested on Sparc, i386, and amd64 hardware
        platforms.

        It is planned for Kea to build, install and run on
        Windows and standard Unix-type platforms.
      </para>
    </section>

    <section id="required-software">
      <title>Required Software at Run-time</title>

      <para>
        Running Kea uses various extra software which may
        not be provided in some operating systems' default
        installations nor standard packages collections. You may
        need to install this required software separately.
        (For the build requirements, also see
        <xref linkend="build-requirements"/>.)
      </para>

      <para>
        Kea was developed as a collection of applications within
        BIND 10 framework and it still relies on the remaining parts
        of this framework. In particular, the servers' configuration
        and startup are still facilitated by the modules which originate
        in BIND 10. These modules require at least Python 3.1 to run.
        They also work with Python 3.2
        (<ulink url="http://www.python.org/"/>)). The dependency
        on Python will be removed once a replacing configuration
        and startup mechanisms are developed for Kea. At this point
        Kea will be written in pure C++.
      </para>

      <para>
        Kea uses the Botan crypto library for C++
        (<ulink url="http://botan.randombit.net/"/>).
        It requires at least Botan version 1.8.
      </para>

      <para>
        Kea uses the log4cplus C++ logging library
        (<ulink url="http://log4cplus.sourceforge.net/"/>).
        It requires at least log4cplus version 1.0.3.
<!-- TODO: It is recommended to use at least version .... -->
      </para>
    </section>

    <section id="starting_stopping">
      <title>Starting and Stopping the Server</title>
      <para>
        Kea is modular.  Part of this modularity is
        accomplished using multiple cooperating processes which, together,
        provide the server functionality.
      </para>

      <!-- todo: Rename processes here, once they are renamed in the source -->
      <para>
        At first, running many different processes may seem confusing.
        However, these processes are started by running a single
	command, <command>bind10</command>.  This command starts
	a master process, <command>b10-init</command>, which will
	start other required processes and other processes when
	configured.  The processes that may be started have names
	starting with "b10-", including:
      </para>

      <para>

        <itemizedlist>

          <listitem>
            <simpara>
              <command>b10-cfgmgr</command> &mdash;
              Configuration manager.
              This process maintains all of the configuration for BIND 10.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
              <command>b10-cmdctl</command> &mdash;
              Command and control service.
              This process allows external control of the BIND 10 system.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
              <command>b10-dhcp4</command> &mdash;
              DHCPv4 server process.
              This process responds to DHCPv4 queries from clients.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
              <command>b10-dhcp6</command> &mdash;
              DHCPv6 server process.
              This process responds to DHCPv6 queries from clients.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
              <command>b10-dhcp-ddns</command> &mdash;
              DHCP-DDNS process.
              This process acts as an intermediary between the DHCP servers
              and DNS server. It receives name update requests from the DHCP
              servers and sends DNS Update messages to the DNS servers.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
              <command>b10-msgq</command> &mdash;
              Message bus daemon.
              This process coordinates communication between all of the other
              BIND 10 processes.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
              <command>b10-sockcreator</command> &mdash;
              Socket creator daemon.
              This process creates sockets used by
              network-listening BIND 10 processes.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
              <command>b10-stats</command> &mdash;
              Statistics collection daemon.
              This process collects and reports statistics data.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
              <command>b10-stats-httpd</command> &mdash;
              HTTP server for statistics reporting.
              This process reports statistics data in XML format over HTTP.
            </simpara>
          </listitem>

        </itemizedlist>
      </para>

      <para>
        These do not need to be manually started independently.
      </para>

    </section>

    <section id="managing_once_running">
      <title>Managing BIND 10</title>

      <para>
        Once BIND 10 is running, a few commands are used to interact
        directly with the system:
        <itemizedlist>
          <listitem>
            <simpara>
              <command>bindctl</command> &mdash;
              Interactive administration interface.
              This is a low-level command-line tool which allows
              a developer or an experienced administrator to control
              Kea.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>b10-cmdctl-usermgr</command> &mdash;
              User access control.
              This tool allows an administrator to authorize additional users
              to manage Kea.
            </simpara>
          </listitem>
  <!-- TODO usermgr -->
        </itemizedlist>
      </para>
    </section>

    <para>
      The tools and modules are covered in full detail in this guide.
<!-- TODO point to these -->
      In addition, manual pages are also provided in the default installation.
    </para>

<!--
bin/
  bindctl*
  host*
lib/
  libauth
  libdns
  libexceptions
  python3.1/site-packages/isc/{cc,config}
sbin/
  bind10
share/
  share/bind10/
    auth.spec
    b10-cmdctl.pem
    init.spec
    passwd.csv
  man/
var/
  bind10/b10-config.db
-->

    <para>
      BIND 10 also provides libraries and programmer interfaces
      for C++ and Python for the message bus and configuration backend,
      and, of course, DHCP. These include detailed developer
      documentation and code examples.
<!-- TODO point to this -->
    </para>

  </chapter>

  <chapter id="quickstart">
    <title>Quick start</title>

    <para>
        This quickly covers the standard steps for installing
        and deploying Kea.
        For further details, full customizations, and troubleshooting,
        see the respective chapters in the Kea guide.
    </para>

    <section id="quick-start-dhcp6">
      <title>Quick start guide for DHCPv6 service</title>

      <orderedlist>

        <listitem>
          <simpara>
            Install required run-time and build dependencies.
          </simpara>
        </listitem>

        <!-- We may need to replace it with the link to a downloadable tarball
        once we have it. -->
        <listitem>
          <simpara>
            Checkout the latest Kea revision from the Git repository:
            <screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput> </screen>
          </simpara>
        </listitem>

        <listitem>
          <para>Go into the source and run configure:
            <screen>$ <userinput>cd kea</userinput>
$ <userinput>autoreconf --install</userinput>
$ <userinput>./configure</userinput></screen>
          </para>
        </listitem>

        <listitem>
          <para>Build it:
            <screen>$ <userinput>make</userinput></screen>
          </para>
        </listitem>

        <listitem>
          <para>Install it as root (by default to prefix
          <filename>/usr/local/</filename>):
            <screen>$ <userinput>make install</userinput></screen>
          </para>
        </listitem>

        <listitem>
          <para>Change directory to the install prefix (by default
          <filename>/usr/local/</filename>):
            <screen>$ <userinput>cd /usr/local/</userinput></screen>
          </para>
        </listitem>

        <listitem>
          <para>Create a user for yourself:
            <screen>$ <userinput>sbin/b10-cmdctl-usermgr add root</userinput></screen>
	  and enter a newly chosen password when prompted.
          </para>
        </listitem>

        <listitem>
          <para>Start the server (as root):
            <screen>$ <userinput>sbin/bind10</userinput></screen>
          </para>
        </listitem>

        <listitem>
          <para>DHCP components are not started in the default
	    configuration.  In another console, enable the DHCPv6
	    service (by using the <command>bindctl</command> utility
	    to configure the <command>b10-dhcp6</command> component to
	    run): <screen>$ <userinput>bin/bindctl</userinput></screen>
	    (Login with the username and password you used above to create a user.)
            <screen>
&gt; <userinput>config add Init/components b10-dhcp6</userinput>
<!-- todo: Should the kind be needed or dispensable? -->
&gt; <userinput>config set Init/components/b10-dhcp6/kind dispensable</userinput>
&gt; <userinput>config commit</userinput>
&gt; <userinput>quit</userinput>
            </screen>
          </para>
        </listitem>

        <listitem>
         <para>Test it; for example, use the
         <ulink url="http://www.isc.org/downloads/DHCP/">ISC DHCP client</ulink>
         to send DHCPv6 queries to the server and verify that the client receives a
         configuration from the server:
            <screen>$ <userinput>dhclient -6</userinput></screen>
         </para>
        </listitem>
      </orderedlist>

    </section>

  </chapter>

  <chapter id="installation">
    <title>Installation</title>

    <section id="packages">
      <title>Packages</title>

      <para>
        Some operating systems or software package vendors may
        provide ready-to-use, pre-built software packages for Kea.
        Installing a pre-built package means you do not need to
        install build-only prerequisites and do not need to
        <emphasis>make</emphasis> the software.
      </para>

      <para>
        FreeBSD ports, NetBSD pkgsrc, and Debian
        <emphasis>testing</emphasis> package collections provide
        all the prerequisite packages.
      </para>
    </section>

    <section id="install-hierarchy">
      <title>Install Hierarchy</title>
      <para>
        The following is the standard, common layout of the
        complete Kea installation:
        <itemizedlist>
          <listitem>
           <simpara>
              <filename>bin/</filename> &mdash;
              general tools and diagnostic clients.
            </simpara>
          </listitem>
          <listitem>
          <simpara>
            <filename>etc/bind10/</filename> &mdash;
            configuration files.
          </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>lib/</filename> &mdash;
              libraries and python modules.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>libexec/bind10/</filename> &mdash;
              executables that a user wouldn't normally run directly and
              are not run independently.
              These are the BIND 10 and Kea modules which are daemons started by
              the <command>b10-init</command> master process.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>sbin/</filename> &mdash;
              commands used by the system administrator.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>share/bind10/</filename> &mdash;
              configuration specifications.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>share/doc/bind10/</filename> &mdash;
              this guide and other supplementary documentation.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>share/man/</filename> &mdash;
              manual pages (online documentation).
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>var/bind10/</filename> &mdash;
              data source and configuration databases.
            </simpara>
          </listitem>
        </itemizedlist>
      </para>
    </section>

    <section id="build-requirements">
      <title>Building Requirements</title>

        <para>
          In addition to the run-time requirements (listed in
          <xref linkend="required-software"/>), building Kea
          from source code requires various development include headers and
          program development tools.
        </para>

        <note>
          <simpara>
            Some operating systems have split their distribution packages into
            a run-time and a development package.  You will need to install
            the development package versions, which include header files and
            libraries, to build Kea from source code.
          </simpara>
        </note>

        <para>
          Building from source code requires the Boost
          build-time headers
          (<ulink url="http://www.boost.org/"/>).
          At least Boost version 1.35 is required.
  <!-- TODO: we don't check for this version -->
  <!-- NOTE: jreed has tested with 1.34, 1.38, and 1.41. -->
        </para>

        <para>
          To build Kea, also install the Botan (at least version
          1.8) and the log4cplus (at least version 1.0.3)
          development include headers.
        </para>

<!--
TODO
Debian and Ubuntu:
 libgmp3-dev and libbz2-dev required for botan too
-->

<!-- NOTE: _sqlite3 is only needed at test time; it is already listed
as a dependency earlier -->

        <para>
          Building Kea also requires a C++ compiler and
          standard development headers, make, and pkg-config.
          Kea builds have been tested with GCC g++ 3.4.3, 4.1.2,
          4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
        </para>

        <para>
          Visit the user-contributed wiki at <ulink
          url="http://kea.isc.org/wiki/SystemSpecificNotes" />
          for system-specific installation tips.
        </para>

    </section>

    <section id="install">
      <title>Installation from source</title>
      <para>
        Kea is open source software written in C++ (some components of the
        BIND 10 framework are written in Python).
        It is freely available in source code form from ISC as a
        downloadable tar file or via Kea Git code revision control
        service. (It may also be available in pre-compiled ready-to-use
        packages from operating system vendors.)
      </para>

      <section>

        <title>Download Tar File</title>
        <para>
          Kea 0.8 is available as a part of BIND10 1.2 release, which is
          a final release of BIND10 from ISC. This release can be downloaded
          from: <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
        </para>
      </section>

      <section>
        <title>Retrieve from Git</title>
        <para>
          Downloading this "bleeding edge" code is recommended only for
          developers or advanced users.  Using development code in a production
          environment is not recommended.
        </para>

        <note>
          <para>
            When using source code retrieved via Git, additional
            software will be required:  automake (v1.11 or newer),
            libtoolize, and autoconf (2.59 or newer).
            These may need to be installed.
          </para>
        </note>

        <para>
          The latest development code (and temporary experiments
          and un-reviewed code) is available via the Kea code revision
          control system. This is powered by Git and all the Kea
          development is public.
          The leading development is done in the <quote>master</quote>
          branch.
        </para>
        <para>
          The code can be checked out from
          <filename>git://git.kea.isc.org/kea</filename>;
          for example:

        <screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput></screen>
        </para>

        <para>
          When checking out the code from
          the code version control system, it doesn't include the
          generated configure script, Makefile.in files, nor their
          related build files.
          They can be created by running <command>autoreconf</command>
          with the <option>--install</option> switch.
          This will run <command>autoconf</command>,
          <command>aclocal</command>,
          <command>libtoolize</command>,
          <command>autoheader</command>,
          <command>automake</command>,
          and related commands.
        </para>

      </section>


      <section id="configure">
        <title>Configure before the build</title>
        <para>
          Kea uses the GNU Build System to discover build environment
          details.
          To generate the makefiles using the defaults, simply run:
          <screen>$ <userinput>./configure</userinput></screen>
        </para>
        <para>
          Run <command>./configure</command> with the <option>--help</option>
          switch to view the different options. Some commonly-used options are:

          <variablelist>

          <varlistentry>
            <term>--prefix</term>
            <listitem>
              <simpara>Define the installation location (the
                default is <filename>/usr/local/</filename>).
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--with-boost-include</term>
            <listitem>
              <simpara>Define the path to find the Boost headers.
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--with-pythonpath</term>
            <listitem>
              <simpara>Define the path to Python 3.1 if it is not in the
                standard execution path.
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--with-gtest</term>
            <listitem>
              <simpara>Enable building the C++ Unit Tests using the
                Google Tests framework. Optionally this can define the
                path to the gtest header files and library.
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--without-werror</term>
            <listitem>
              <simpara>Disable the default use of the
		<option>-Werror</option> compiler flag so that
		compiler warnings aren't build failures.
              </simpara>
            </listitem>
          </varlistentry>

          </variablelist>
          <note>
            <para>
              For additional instructions concerning the building and installation of
              Kea, see <xref linkend="dhcp-install-configure"/>.
            </para>
          </note>
        </para>
  <!-- TODO: lcov -->

        <para>
          For example, the following configures it to
    find the Boost headers, find the
    Python interpreter, and sets the installation location:

          <screen>$ <userinput>./configure \
      --with-boost-include=/usr/pkg/include \
      --with-pythonpath=/usr/pkg/bin/python3.1 \
      --prefix=/opt/bind10</userinput></screen>
        </para>

        <para>
          If the configure fails, it may be due to missing or old
          dependencies.
        </para>


      </section>

      <section>
        <title>Build</title>
        <para>
    After the configure step is complete, to build the executables
    from the C++ code and prepare the Python scripts, run:

          <screen>$ <userinput>make</userinput></screen>
        </para>
      </section>

      <section>
        <title>Install</title>
        <para>
          To install the Kea executables, support files,
          and documentation, run:
          <screen>$ <userinput>make install</userinput></screen>
        </para>
        <para>
          Please don't use any form of parallel or job server options
          (such as GNU make's <command>-j</command> option) when
          performing this step. Doing so may cause errors.
        </para>
        <note>
          <para>The install step may require superuser privileges.</para>
        </note>
        <para>
	  If required, run <command>ldconfig</command> as root with
	  <filename>/usr/local/lib</filename> (or with ${prefix}/lib if
	  configured with --prefix) in
	  <filename>/etc/ld.so.conf</filename> (or the relevant linker
	  cache configuration file for your OS):
	  <screen>$ <userinput>ldconfig</userinput></screen>
        </para>
        <note>
          <para>
	    If you do not run <command>ldconfig</command> where it is
	    required, you may see errors like the following:
            <screen>
	      program: error while loading shared libraries: libkea-something.so.1:
	      cannot open shared object file: No such file or directory
	    </screen>
	  </para>
        </note>
      </section>

  <!-- TODO: tests -->

    </section>

  <!--
      <section id="install.troubleshooting">
        <title>Troubleshooting</title>
        <para>
        </para>
      </section>
  -->

  </chapter>

  <chapter id="bind10">
    <title>Starting Kea with <command>bind10</command></title>
    <para>
      Kea is started with the <command>bind10</command> command.
      It runs the <command>b10-init</command> daemon which
      starts up the required processes, and
      will also restart some processes that exit unexpectedly.
      <command>bind10</command> is the only command needed to start Kea.
    </para>

    <para>
      After starting the <command>b10-msgq</command> communications channel,
      <command>b10-init</command> connects to it,
      runs the configuration manager, and reads its own configuration.
      Then it starts the other modules.
    </para>

    <para>
      The <command>b10-sockcreator</command>, <command>b10-msgq</command> and
      <command>b10-cfgmgr</command>
      services make up the core. The <command>b10-msgq</command> daemon
      provides the communication channel between every part of the system.
      The <command>b10-cfgmgr</command> daemon 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. The <command>b10-sockcreator</command> daemon
      can allocate Internet addresses and ports needed by network services
      but is currently unused by DHCP servers.
    </para>

    <para>
      In its default configuration, the <command>b10-init</command>
      master process will also start up
      <command>b10-cmdctl</command> for administration tools to
      communicate with the system, and
      <command>b10-stats</command> for statistics collection.
      The DHCP servers are not started by default.
      The configuration of components to start is covered in
      <xref linkend="kea.components"/>.
    </para>

    <section id="start">
      <title>Starting Kea</title>
      <para>
        To start the BIND 10 service, simply run <command>bind10</command>
        as root.
        It will run in the foreground and your shell prompt will not
        be available. It will output various log messages as it starts up
        and is used.
        Run it with the <option>--verbose</option> switch to
        get additional debugging or diagnostic output.
      </para>

<!-- TODO: user switch -->

<!-- TODO:  example:  nohup /usr/local/sbin/bind10 1>bind10.log 2>&1 -->

      <note>
        <para>
          If the setproctitle Python module is detected at start up,
          the process names for the Python-based daemons will be renamed
          to better identify them instead of just <quote>python</quote>.
          This is not needed on some operating systems.
        </para>
      </note>

    </section>

  </chapter>

  <chapter id="msgq">
    <title>Command channel</title>

      <para>
        The BIND 10 components use the <command>b10-msgq</command>
        message routing daemon to communicate with Kea components.
        The <command>b10-msgq</command> implements what is called the
        <quote>Command Channel</quote>.
        Processes intercommunicate by sending messages on the command
        channel.
        Example messages include shutdown, get configurations, and set
        configurations.
        This Command Channel is not used for DNS message passing.
        It is used only to control and monitor the BIND 10 system.
      </para>

      <para>
        Administrators do not communicate directly with the
        <command>b10-msgq</command> daemon.
        By default, BIND 10 uses a UNIX domain socket file named
        <filename>/usr/local/var/bind10/msg_socket</filename>
        for this interprocess communication.
      </para>

  </chapter>

  <chapter id="cfgmgr">
    <title>Configuration manager</title>

      <para>
         The configuration manager, <command>b10-cfgmgr</command>,
         handles all system configuration.  It provides
         persistent storage for configuration, and notifies running
         modules of configuration changes.
      </para>

      <para>
        The <command>b10-dhcp6</command>, <command>b10-dhcp4</command> and
        <command>b10-dhcp-ddns</command> daemons receive their configurations
        from the configuration manager over the <command>b10-msgq</command>
        command channel.
      </para>

      <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>
          In future releases of Kea, the architecture which originates in
          the BIND 10 project will be replaced by the new mechanisms to start
          and configure Kea. The new mechanisms will use a file based
          configuration.
        </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>).
        <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 directory is what was defined at build configure time for
        <option>--localstatedir</option>.
        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>

<!--

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>
      The configuration manager does not have any command line arguments.
      Normally it is not started manually, but is automatically
      started using the <command>b10-init</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
-->

<!-- 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
-->

  </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>b10-msgq</command> channel). Then it will start listening
      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,
      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>

    <note><para>
      The HTTPS server doesn't support a certificate request from a
      client (at this time).
<!-- TODO: maybe allow request from server side -->
      The <command>b10-cmdctl</command> daemon does not provide a
      public service. If any client wants to control BIND 10, then
      a certificate needs to be first received from the BIND 10
      administrator.
      The Kea installation provides a sample PEM bundle that matches
      the sample key and certificate.
    </para></note>
<!-- TODO: cross-ref -->

<!-- TODO
openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes
but that is a single file, maybe this should go back to that format?
-->

<!--
    <para>
(08:20:56) shane: It is in theory possible to run without cmdctl.
(08:21:02) shane: I think we discussed this.
    </para>
-->

<!-- 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.
    </para>

    <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 <option>--port</option> command line option.
      The address to listen on can be set using the <option>--address</option> command
      line argument.
      Each HTTPS connection is stateless and times out in 1200 seconds
      by default.  This can be
      redefined by using the <option>--idle-timeout</option> command line argument.
    </para>