Commit 83b2d2b5 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[3398] Rather important file has been omitted. :)

parent 91c64d27
// 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 Configuration backend introdution
Kea is a flexible DHCP protocol engine. It offers a selection of lease database
backends, extensibility via hooks API and definition of custom options.
Depending on the environment, one lease database backend may be better than
other. Similarly, depending on the deployment, it would also make sense to
provide different ways to configure the server. The capability to have different
ways to configure the servers is called Configuration Backend. As the way
how configuration is received cannot be part of the configuration itself, it
has to be chosen at the compilation time (when configuring sources). This page
explains why we chose that path and how it is implemented. It can be used by
people who want to develop and maintain their own configuration backends.
@section configBackendMotivation Motivation for configuration backends
BIND10 used to maintain an extensive framework that was responsible for
components configuration. After BIND10 was cancelled, two projects were
created: Kea and Bundy. Kea team decided to remove BIND10 framework, while Bundy
team decided to keep it. Even though Kea team is focused on JSON backend, which
reads the JSON configuration file from disk, we try to make it easy for others
to use different backends.
While ISC currently (May 2014) plans to maintain only one configuration backend
(JSON: a JSON file read from disk), there may be other organizations (e.g.
possibly Bundy project community) that will maintain other backends. It is quite
possible that other configuration backends (e.g. using LDAP or XML) will be
developed and maintained by other organizations.
@section configBackendAdding How to add a new configuration backend?
@todo: Will be covered in ticket #3400.
@section configBackendJSONDesign Design for JSON configuration backend
-# A new parameter called --with-kea-config will be implemented in
configure script. It will allow selecting at compilation time how the
servers will be configured. For the next 2-3 months (until around June 2014),
we'll have 2 values: JSON (read from file) and BIND10 (use bind10 framework).
Once we have file based configuration implemented and we're ready to switch
(i.e. enough confidence, Forge tests updated for new configuration
mechanism), BIND10 backend will be removed from Kea repo. Other projects
(e.g. Bundy) who want to maintain it, are advisaged to just revert a single
commit that will bring back the BIND10 framework to their repos.
This switchable backend concept is really simple. There are just different
implementations of ControlledXSrv class, so it's a matter with compiling/linking
one file or another. Hence it is easy for us to remove the old backend (and for
Bundy folks to keep it if they desire so). It is also easy for other
organizations to add and maintain their own backends (e.g. LDAP based).
For detailed description of DHCPv6 backend, see @ref dhcpv6ConfigBackend.
-# Retain config and command callbacks. 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. Exact format of configuration and commands is
module specific.
-# After Kea 0.9 is released, we will design some form of secure socket that
we'll be able to send commands over. Whatever the design we end up with, it
will allow to send configs and commands in JSON format and get responses.
Once that is done, we'll have the same capability as we did in BIND10
framework: to send additional parameters. One obvious use case will be
to send new config file name as parameter for "reload".
-# We need to add command handler for reading config from a file. Its main
responsibility is to load config from file and process it. The JSON backend
must call that handler when starting up the server.
-# Extend existing JSON parser. We need to extend current JSON parser in
@ref isc::data::Element::fromJSON() to allow optional preprocessing.
For now that capability will simply remove hash comments, but it is expected
to grow over time (in-line comments and file inclusions are the obvious
envisaged additions).
-# Implement common base class for Kea4, Kea6, D2 server. Some operations will be
common for all 3 components: logger initialization, handling, and some time
later control socket. This calls for a small base class that Dhcpv4Srv,
Dhcpv6Srv and D2Controller can use. We will start that base class (@ref
isc::dhcp::Daemon) as very small one. It is expected to grow over time as we
do more code unification.
-# We need to implement a way to initialized stand-alone logging (i.e. each
Kea component will initialize it on its own).
-# Config file format.
We will use the current format of b10-config.db. This is slight change
to what we did in Kea during BIND10 days, because we were receiving a subset
of that configuration. Let me give specific example. That's how b10-config.db
looks like 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
Kea components used to receive only relevant parts of it (e.g. Kea4
received config that contained content of the Dhcp4 element). We'll be
receiving the whole config now. The modification in the code is really
minor: just iterate over top level elements and pick the appropriate
tree (or get element by name). Also, that approach makes the logging
initialization code very easy to share among Kea4, Kea6 and D2.
-# We keep .spec files. We'll keep and maintain them even though we won't do
anything with them. Those files were used by bindctl to do syntax checking.
We will be lacking that capability for a while. Implementing C++ code for
.spec validation of received config is out of scope for 0.9 (and probably
for 1.0 as this is pretty big task).
-# Shell script to start/stop Kea4,Kea6 and D2. There will be a script that will
start, stop and reconfigure the daemons. It will be rather simple. Its only
job will be to pass config file to each daemon and remember its PID file, so
sending signals would be possible (for config 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 would be:
-# Start the processes
- eventually based on config, 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 (past 0.9)
-# Stop the processes in an orderly fashion
-# Perhaps return status of each process
*/
\ No newline at end of file
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