kea/doc/devel/config-backend.dox

// Copyright (C) 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.

/**

 @page configBackend Kea Configuration Backends

@section configBackendIntro Introduction

Kea is a flexible DHCP protocol engine. It offers a selection of lease database
backends, extensibility via the hooks API and the definition of custom options.
Depending on the environment, one lease database backend may be better than
other. Similarly, because the best way of configuring the server can depend on
the environment, Kea provides different ways of obtaining configuration
information, through the Configuration Backend. Since the means by which
configuration information is received cannot be part of the configuration itself, it
has to be chosen at the compilation time (when configuring the sources).

This page explains the background to the Configuration Backend and how
it is implemented. It is aimed at people who want to develop and
maintain their own backends.

@section configBackendMotivation Motivation for Different Backends

BIND10 (the project under which the first stages of Kea were developed)
used to maintain an extensive framework that was responsible for the
configuration of components.  After BIND10 was cancelled, two projects
were created: <a href="http://kea.isc.org">Kea</a> (focused on DHCP)
and <a href="http://www.bundy-dns.de">Bundy</a> (aimed at DNS). The
Kea team decided to remove the BIND10 framework, while the Bundy team
decided to keep it. However, even though the Kea team is focused on a
backend that reads a JSON configuration file from disk, it decided to
make it easy for others to use different backends.

While ISC currently (May 2014) plans to maintain only one configuration backend
(a JSON file read from disk), there may be other organizations (e.g.
the Bundy project community) that will maintain other backends. It is quite
possible that additional backends (e.g. using LDAP or XML) will be
developed and maintained by other organizations.

@section configBackendAdding How to Add a New Configuration Backend

The configuration backend concept was designed to make external (i.e. not
maintained by ISC) configurations backends easy to maintain. In particular,
the set of patches vs. separate files required strongly favors separate
files. This is important if an external organization wants to develop its
own configuration backend and then needs to apply it every ISC release
of Kea.

The following steps are needed to add new configuration backend (it is assumed
that the modified component is DHCPv4. Similar approach applies to other
components: DHCPv6 or D2):

-# Modify AC_ARG_WITH(kea-config,...) macro in configure.ac
-# Add your own AM_CONDITIONAL(CONFIG_BACKEND_FOO, ...) macro in configure.ac
-# Add your own conditional AC_DEFINE(CONFIG_BACKEND_FOO, ...) invocation
   in configure.ac
-# Modify the sanity check in configure.ac to allow your configuration backend name.
-# Modify src/bin/dhcp4/Makefile.am to include your own backend
   implementation (e.g. foo_controller.cc).
-# Write your own implementation of isc::dhcp::ControlledDhcpv4Srv::init(),
   isc::dhcp::ControlledDhcpv4Srv::init() and isc::dhcp::ControlledDhcpv4Srv::cleanup()
   and put it in foo_controller.cc

Optionally you can also:

-# Modify src/bin/dhcp4/tests/Makefile.am to include foo_controller_unittest.cc if
   selected backend is foo.
-# Implement unit-tests for your backend in foo_controller_unittest.cc file.

@section configBackendJSONDesign The JSON Configuration Backend

The following are some considerations that shaped the design of the configuration
backend framework.

-# A new parameter called --with-kea-config was implemented in the
   configure script. It allows the selection at compilation time of how the
   servers will be configured. Currently (June 2014),
   there are two values: JSON (the default, read configuration from a JSON file)
   and BUNDY (use the BUNDY/BIND10 framework).  The Bundy/BIND10 framework was removed
   from the Kea repository. Other projects
   (e.g. Bundy) who want to maintain Bundy framework, are advised to maintain
   the framework in their repositories, import Kea modules and compile them
   with Bundy backend.
   This switchable backend concept is quite simple. There are just different
   implementations of ControlledXSrv class, each backend keeping its code
   in a separate file. It is a matter of compiling/linking
   one file or another. Hence it is easy to remove the old backend (and for
   external projects, like Bundy, to keep it if they desire so). It is also easy
   for other organizations to add and maintain their own backends (e.g. LDAP).

-# Each backend must use the common code for configuration and command
   processing callbacks. They all assume that JSON formatted parameters are sent
   and they are expected to return well formatted JSON responses. The exact
   format of configuration and commands is module specific.

-# After Kea 0.9 is released, a form of secure socket will be implemented
   through which commands can be sent. Whatever the design, it will allow the
   sending of configurations and commands in JSON format and the receiving of
   responses.  Once that is done, Kea will have the same capability the BIND10
   framework to send additional parameters. One obvious use case will be to send
   a new configuration file name as the parameter for "reload".

-# A command handler needs to be added for reading the configuration from a
   file. Its main responsibility is to load the configuration and process
   it. The JSON backend must call that handler when starting up the server.
   This is implemented in configure() function in kea_controller.cc files
   in src/bin/dhcp4 and src/bin/dhcp6 directories.

-# Extend the existing JSON parser. The current JSON parser in @ref
   isc::data::Element::fromJSON() needs to be extended to allow optional
   preprocessing.  For now that capability simply removes  whole-line
   comments staring with the hash character, but it is expected to grow over
   time (in-line comments and file inclusions are the obvious envisaged
   additions). This is implemented in @ref isc::data::Element::fromJSONFile.

-# Implement a common base class for the Kea4, Kea6, and D2 servers. Some
   operations will be common for all three components: logger initialization,
   handling and, at some future point, control socket. This calls for a small
   base class that @ref isc::dhcp::Dhcpv4Srv "Dhcpv4Srv", @ref
   isc::dhcp::Dhcpv6Srv "Dhcpv6Srv" and the @ref isc::d2::D2Controller
   "D2Controller" classes can use.  It is expected that the base class (@ref
   isc::dhcp::Daemon) will be a small one but will grow over time as the code is
   unified. This has been implemented in @ref isc::dhcp::Daemon.

-# A way is needed to initialize stand-alone logging (i.e. each
   Kea component will initialize it on its own).

-# The current format of the BIND10 configuration file (BIND 10 stored its
   configuration in (installation directory)/var/bind10/b10-config.db) will be
   retained as the configuration file format. Its actual naming is now arbitrary
   and left up to the user (it is passed as a parameter to the -c command line
   option). From the implementation perspective, this is slight change
   from the BIND10 days, as back then a subset of the configuration was received by
   the daemon processes. Nowadays the whole configuration is pased. To take a
   specific example, the following is how b10-config.db looks today:
   @code
   {
     "Init": { ... }
     "Dhcp4": {
       "subnet4" { subnet definitions here },
       "option-data" { option data here },
       "interfaces": [ "eth0" ],
       ...
    },
     "Dhcp6": {
       "subnet6" { subnet definitions here },
       "option-data" { option data here },
       "interfaces": [ "eth0" ],
       ...
     },
     "Logging": {
       "Loggers": [{"name": *, "severity": "DEBUG" }]
      }
   }
   @endcode
   <br/>
   The Kea components used to receive only relevant parts of it (e.g. Kea4
   received config that contained content of the Dhcp4 element). Now they
   will receive all of it. The modification in the code to handle this
   is really minor: just iterate over the top level elements and pick the appropriate
   tree (or get the element by name). Also, that approach makes the logging
   initialization code very easy to share among Kea4, Kea6 and D2.

-# The .spec files used in BIND 10 by the control program to validate commands
   will be retained. They will be kept and maintained even though no use of
   them is planned. At some future time syntax validation may be implemented,
   although it is out of scope for Kea 0.9 (and probably
   for 1.0 as it is pretty big task).

-# Addition of a shell script to start/stop Kea4,Kea6 and D2. There will be a script that will
   start, stop and reconfigure the daemons. Its only
   job will be to pass the configuration file to each daemon and remember its PID file, so
   that sending signals will be be possible (for configuration reload or shutdown). Optionally,
   it could also print out a status based on PID, but that may be tricky to
   implement in a portable way. The minimum set of commands will be:
   -# Start the processes
      - eventually based on configuration, initially start them all
      - it could launch a nanny script which restarts them on a crash (past 0.9)
   -# Prompt the processes to reload configuration
      - for now it will be a matter of sending singal to the right process
      - this could also decide if D2 should still be running or not, and react accordingly (post 0.9)
   -# Stop the processes in an orderly fashion
   -# Perhaps return status of each process

This script has been implemented in src/bin/keactl/keactl.

*/