From: Tomek Mrugalski Date: Tue, 6 May 2014 13:37:00 +0000 (+0200) Subject: [3398] Rather important file has been omitted. :) X-Git-Tag: trac3434_base~40 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=83b2d2b565a2061e6c14a6aa2974cb4780dd3582;p=thirdparty%2Fkea.git [3398] Rather important file has been omitted. :) --- diff --git a/doc/devel/config-backend.dox b/doc/devel/config-backend.dox new file mode 100644 index 0000000000..98430c978c --- /dev/null +++ b/doc/devel/config-backend.dox @@ -0,0 +1,164 @@ +// 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