config-backend.dox 5.96 KB
Newer Older
// Copyright (C) 2014-2015 Internet Systems Consortium, Inc. ("ISC")
3 4 5
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at
6 7 8


 @page configBackend Kea Configuration Backends

@section configBackendIntro Introduction

13 14 15 16 17 18 19 20 21 22 23 24 25 26
Kea started as a sub-project in BIND10 that used a program (called
bindctl) to deliver configuration information to its modules. This
potentially allowed for modules to get their configuration information
in a variaty of ways using what were known as configuration backends.
After BIND10 was cancelled, the Kea project briefly tried to maintain
backward compatibility with the BIND10 framework, but the effort
was discontinued due to lack of interest.

Currently the Kea team does not plan to develop any additional
configuration backends. Instead, effort is being focused on enhancing
the current control channel (see @ref ctrlSocket) to be as flexible
as possible. If you are thinking about developing new ways to
configure Kea, the recommendation is to write an external piece of
software that will communicate with Kea using this channel.
27 28 29

@section configBackendHistoric Historic Notes

While this section currently has no practical value, it may become useful
31 32 33 34
one day to develop a minimalistic, stripped down Kea version that does
not have any command interface at all. This could prove useful for running
Kea in embedded regime.

35 36 37 38
The following steps are needed for the DHCPv4 server to be able to
process a new method of configuration. (It is assumed that the
modified component is DHCPv4. Similar approach applies to the other
components: DHCPv6 or DHCP-DDNS):
39 40

-# Write your own implementation of isc::dhcp::ControlledDhcpv4Srv::init(),
   isc::dhcp::ControlledDhcpv4Srv::init() and isc::dhcp::ControlledDhcpv4Srv::cleanup(),
42 43 44 45 46 47 48 49 50
   and put it in the src/bin/dhcp4 directory (e.g. as
-# Modify src/bin/dhcp4/ to include your file (e.g. in
   the build.
-# Modify the AC_ARG_WITH(kea-config,...) macro in to include an
   entry for your configuration backend.
   AC_DEFINE(CONFIG_BACKEND_FOO, ...) macros to (following the
   above-mentioned AC_ARG_WITH macro) to set the C++ macro for your backend.
-# Modify the sanity check in to allow your configuration backend name.
51 52 53

Optionally you can also:

54 55 56
-# Implement unit tests for your backend in the src/bin/dhcp4/tests directory.
-# Modify src/bin/dhcp4/tests/ to include the file(s) containing the
   unit tests.

@section configBackendJSONDesign The JSON Configuration Backend

The following are some details of the JSON backend framework.

-# Each backend uses the common code for configuration and command
63 64
   processing callbacks. They all assume that JSON formatted parameters are sent
   and they are expected to return well formatted JSON responses. The exact
65 66
   format of configuration and commands is module-specific.<br/><br/>
-# A command handler handles the reading the configuration from a
67 68
   file. Its main responsibility is to load the configuration and process
   it. The JSON backend must call that handler when starting up the server.
69 70 71 72 73 74
   This is implemented in configure() in the files
   in src/bin/dhcp4 and src/bin/dhcp6 directories.<br/><br/>
-# The current JSON parser in @ref
   isc::data::Element::fromJSON() has been extended to allow optional
   preprocessing.  For now, that capability simply removes  whole-line
   comments starting 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.<br/><br/>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
-# The current format of the BIND10 configuration file (BIND 10 stored its
   configuration in (installation directory) /var/bind10/b10-config.db) has been
Tomek Mrugalski's avatar
Tomek Mrugalski committed
79 80 81 82
   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
Jeremy C. Reed's avatar
Jeremy C. Reed committed
   the daemon processes. Nowadays the whole configuration is passed. To take a
Tomek Mrugalski's avatar
Tomek Mrugalski committed
   specific example, the following is how b10-config.db looks today:
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104
     "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" }]
   The Kea components used to receive only relevant parts of it (e.g. Kea4
106 107 108 109 110 111
   received configuration data that only contained the content of the Dhcp4 element).
   Now each component receives all of it: the code
   iterates over the top level elements and picks the appropriate
   tree (or get the element by name). That approach makes the common configuration
   (such as the logging initialization code) very easy to share among Kea4, Kea6 and
-# The .spec files used in BIND 10 by the control program to validate commands
113 114
   have been retained. They will be kept and maintained even though no use of
   them is currently planned. At some future time syntax validation may be implemented,
   although it is out of scope for Kea 0.9 (and probably
116 117
   for 1.0 as well, as it is a pretty big task).<br/><br/>
-# A shell script has been added (as src/bin/keactrl/keactrl) to
   start, stop and reconfigure the daemons. Its only
119 120 121 122
   job is to pass the configuration file to each daemon and remember its PID file, so
   that sending signals is possible (for configuration reload or shutdown). It is also
   able to print out a status.