[master] Revert "[master] Finished merge if trac3732a (remove BUNDY 2nd pass)"

This reverts commit 8d0324f4, reversing
changes made to 9257854f.

Revert trac3732a merge because config was reused by command stuff.

configure.ac

@@ -1093,7 +1093,9 @@ fi
 # Add some default CPP flags needed for Boost, identified by the AX macro.
 CPPFLAGS="$CPPFLAGS $CPPFLAGS_BOOST_THREADCONF"
 
-# Can be required by gtest, boost and perhaps still asio
+# I can't get some of the #include <asio.hpp> right without this
+# TODO: find the real cause of asio/boost wanting pthreads
+# (this currently only occurs for src/lib/cc/session_unittests)
 PTHREAD_LDFLAGS=
 AC_CHECK_LIB(pthread, pthread_create,[ PTHREAD_LDFLAGS=-lpthread ], [])
 AC_SUBST(PTHREAD_LDFLAGS)

src/lib/cc/.gitignore

+/cc_messages.cc
+/cc_messages.h
+/s-messages

src/lib/cc/Makefile.am

@@ -2,10 +2,32 @@ SUBDIRS = . tests
 
 AM_CPPFLAGS = -I$(top_srcdir)/src/lib -I$(top_builddir)/src/lib
 AM_CPPFLAGS += $(BOOST_INCLUDES)
+
 AM_CXXFLAGS = $(KEA_CXXFLAGS)
+if USE_GXX
+# ASIO header files used in session.cc will trigger the "unused-parameter"
+# warning.  Unfortunately there doesn't seem to be an easy way to selectively
+# avoid the error.  As a short term workaround we suppress this warning
+# for the entire this module.  See also src/bin/auth/Makefile.am.
+AM_CXXFLAGS += -Wno-unused-parameter
+AM_CXXFLAGS += -fno-strict-aliasing
+endif
 
 lib_LTLIBRARIES = libkea-cc.la
 libkea_cc_la_SOURCES = data.cc data.h
 libkea_cc_la_SOURCES += command_interpreter.cc command_interpreter.h
+libkea_cc_la_SOURCES += logger.cc logger.h
+nodist_libkea_cc_la_SOURCES = cc_messages.cc cc_messages.h
+libkea_cc_la_LIBADD = $(top_builddir)/src/lib/log/libkea-log.la
+
+CLEANFILES = *.gcno *.gcda cc_messages.cc cc_messages.h s-messages
+
+cc_messages.cc cc_messages.h: s-messages
+
+s-messages: cc_messages.mes
+	$(top_builddir)/src/lib/log/compiler/message $(top_srcdir)/src/lib/cc/cc_messages.mes
+	touch $@
+
+BUILT_SOURCES = cc_messages.cc cc_messages.h
 
-CLEANFILES = *.gcno *.gcda
+EXTRA_DIST = cc_messages.mes

src/lib/cc/cc_messages.mes

+# 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.
+
+$NAMESPACE isc::cc
+
+% CC_RECEIVE Received a message over control channel: %1
+Debug message, noting that a message was received over control channel.
+
+% CC_SEND Sending message over control channel: '%1'
+Debug message, the code is about to send a message over the control channel.
+
+% CC_REGISTER_COMMAND_HANDLER Handler for command '%1' registered
+Command Handler for a given command has been registered. This means that
+the software enabled handling of said command.
+
+% CC_PROCESS_COMMAND Processing command '%1'
+Debug message, noting that the software is processing received command.
+
+% CC_READ_ERROR Received truncated or malformed command (%1)
+A read error indicates that either the communication was interrupted (e.g.
+truncated packet received) or the entity had sent malformed command.

src/lib/cc/data.h

@@ -691,18 +691,18 @@ public:
 bool isNull(ConstElementPtr p);
 
 ///
-/// \brief Remove all values from the first ElementPtr that are equal
-/// in the second. Both ElementPtrs MUST be MapElements The use for
-/// this function is to end up with a MapElement that only contains
-/// new and changed values (for configuration update handlers)
+/// \brief Remove all values from the first ElementPtr that are
+/// equal in the second. Both ElementPtrs MUST be MapElements
+/// The use for this function is to end up with a MapElement that
+/// only contains new and changed values (for ModuleCCSession and
+/// configuration update handlers)
 /// Raises a TypeError if a or b are not MapElements
 void removeIdentical(ElementPtr a, ConstElementPtr b);
 
-/// \brief Create a new ElementPtr from the first ElementPtr, removing
-/// all values that are equal in the second. Both ElementPtrs MUST be
-/// MapElements.  The returned ElementPtr will be a MapElement that
-/// only contains new and changed values (for configuration update
-/// handlers).
+/// \brief Create a new ElementPtr from the first ElementPtr, removing all
+/// values that are equal in the second. Both ElementPtrs MUST be MapElements.
+/// The returned ElementPtr will be a MapElement that only contains new and
+/// changed values (for ModuleCCSession and configuration update handlers).
 /// Raises a TypeError if a or b are not MapElements
 ConstElementPtr removeIdentical(ConstElementPtr a, ConstElementPtr b);
 

src/lib/cc/logger.cc

+// Copyright (C) 2010  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.
+
+#include <cc/logger.h>
+
+namespace isc {
+namespace cc {
+
+isc::log::Logger logger("cc");
+
+}
+}

src/lib/cc/logger.h

+// Copyright (C) 2010  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.
+
+#ifndef CC_LOGGER_H
+#define CC_LOGGER_H
+
+#include <cc/cc_messages.h>
+#include <log/macros.h>
+
+/// \file cc/logger.h
+/// \brief Command Channel library global logger
+///
+/// This holds the logger for the CC library. It is a private header
+/// and should not be included in any publicly used header, only in local
+/// cc files.
+
+namespace isc {
+namespace cc {
+
+/// Trace basic operation
+const int DBG_TRACE_BASIC = DBGLVL_TRACE_BASIC;
+
+/// This includes messages being sent and received, waiting for messages
+/// and alike.
+const int DBG_TRACE_DETAILED = DBGLVL_TRACE_DETAIL;
+
+// Declaration of the logger.
+extern isc::log::Logger logger;
+
+} // namespace cc
+} // namespace isc
+
+/// \brief Logger for this library
+
+#endif

src/lib/config/.gitignore

+/config_messages.cc
+/config_messages.h
+/s-messages

src/lib/config/Makefile.am

 SUBDIRS = . tests
 
 AM_CPPFLAGS = -I$(top_srcdir)/src/lib -I$(top_builddir)/src/lib
+AM_CPPFLAGS += -I$(top_builddir)/src/lib/cc
+AM_CPPFLAGS += -I$(top_srcdir)/src/lib/log -I$(top_builddir)/src/lib/log
 AM_CPPFLAGS += $(BOOST_INCLUDES)
 
+# Define rule to build logging source files from message file
+config_messages.h config_messages.cc: s-messages
+
+s-messages: config_messages.mes
+	$(top_builddir)/src/lib/log/compiler/message $(top_srcdir)/src/lib/config/config_messages.mes
+	touch $@
+
+BUILT_SOURCES = config_messages.h config_messages.cc
+
 lib_LTLIBRARIES = libkea-cfgclient.la
 libkea_cfgclient_la_SOURCES = config_data.h config_data.cc
 libkea_cfgclient_la_SOURCES += module_spec.h module_spec.cc
+libkea_cfgclient_la_SOURCES += command_mgr.cc command_mgr.h
+libkea_cfgclient_la_SOURCES += command_socket.cc command_socket.h
+libkea_cfgclient_la_SOURCES += command_socket_factory.cc command_socket_factory.h
+libkea_cfgclient_la_SOURCES += config_log.h config_log.cc
 
 libkea_cfgclient_la_LIBADD = $(top_builddir)/src/lib/cc/libkea-cc.la
 libkea_cfgclient_la_LIBADD += $(top_builddir)/src/lib/exceptions/libkea-exceptions.la
+libkea_cfgclient_la_LIBADD += $(top_builddir)/src/lib/log/libkea-log.la
+libkea_cfgclient_la_LIBADD += $(top_builddir)/src/lib/dhcp/libkea-dhcp++.la
 
 libkea_cfgclient_la_LDFLAGS = -no-undefined -version-info 1:0:1
 
-CLEANFILES = *.gcno *.gcda
+nodist_libkea_cfgclient_la_SOURCES  = config_messages.h config_messages.cc
+
+# The message file should be in the distribution.
+EXTRA_DIST = config_messages.mes command-socket.dox
+
+CLEANFILES = *.gcno *.gcda config_messages.h config_messages.cc s-messages

src/lib/config/TODO

+Open issues for lib/config:
+
+* Error output currently goes to stdout, and we need to use
+  decent logging for that.
+* Add "expect failure" tests to the unit tests.
+* This cpp version does not use recvmsg() with a sequence number to
+  prevent other messages sneaking in before the answer it expects.
+  (because lib/cc/session.cc|h does not support that yet).

src/lib/config/config_log.cc

+// Copyright (C) 2011,2015  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.
+
+/// Defines the logger used by the config lib
+
+#include "config/config_log.h"
+
+namespace isc {
+namespace config {
+
+isc::log::Logger config_logger("config");
+
+isc::log::Logger command_logger("commands");
+
+} // namespace nsas
+} // namespace isc
+

src/lib/config/config_log.h

+// Copyright (C) 2011,2015  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.
+
+#ifndef CONFIG_LOG_H
+#define CONFIG_LOG_H
+
+#include <log/macros.h>
+#include "config_messages.h"
+
+namespace isc {
+namespace config {
+
+/// @brief Command processing Logger
+///
+/// Define the logger used to log messages.  We could define it in multiple
+/// modules, but defining in a single module and linking to it saves time and
+/// space.
+extern isc::log::Logger config_logger;
+
+/// @brief Command processing Logger
+///
+/// Define the logger used to log messages related to command processing.
+extern isc::log::Logger command_logger;
+
+// Enumerate configuration elements as they are processed.
+const int DBG_CONFIG_PROCESS = DBGLVL_TRACE_BASIC;
+
+// Enumerate configuration elements as they are processed.
+const int DBG_COMMAND = DBGLVL_COMMAND;
+
+} // namespace config
+} // namespace isc
+
+#endif // CONFIG_LOG_H

src/lib/config/config_messages.mes

+# Copyright (C) 2011, 2014-2015  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.
+
+$NAMESPACE isc::config
+
+% COMMAND_PROCESS_ERROR1 Error while processing command: %1
+This warning message indicates that the server encountered an error while
+processing received command. Additional information will be provided, if
+available. Additional log messages may provide more details.
+
+% COMMAND_PROCESS_ERROR2 Error while processing command: %1
+This warning message indicates that the server encountered an error while
+processing received command. The difference, compared to COMMAND_PROCESS_ERROR1
+is that the initial command was well formed and the error occurred during
+logic processing, not the command parsing. Additional information will be
+provided, if available. Additional log messages may provide more details.
+
+% COMMAND_RECEIVED Received command '%1'
+This informational message indicates that a command was received over command
+socket. The nature of this command and its possible results will be logged
+with separate messages.
+
+% COMMAND_RESPONSE_ERROR Server failed to generate response for command: %1
+This error message indicates that the server failed to generate response for
+specified command. This likely indicates a server logic error, as the server
+is expected to generate valid responses for all commands, even malformed
+ones.
+
+% COMMAND_SOCKET_FAIL_NONBLOCK Failed to set non-blocking mode for socket %1 created for incoming connection on socket %2: %3
+This error message indicates that the server failed to set non-blocking mode
+on just created socket. That socket was created for accepting specific
+incoming connection. Additional information may be provided as third parameter.
+
+% COMMAND_SOCKET_ACCEPT_FAIL Failed to accept incoming connection on command socket %1: %2
+This error indicates that the server detected incoming connection and executed
+accept system call on said socket, but this call returned an error. Additional
+information may be provided by the system as second parameter.
+
+% COMMAND_SOCKET_READ Received %1 bytes over command socket %2
+This debug message indicates that specified number of bytes was received
+over command socket identified by specified file descriptor.
+
+% COMMAND_SOCKET_READ_FAIL Encountered error %1 while reading from command socket %2
+This error message indicates that an error was encountered while
+reading from command socket.
+
+% COMMAND_SOCKET_WRITE Sent response of %1 bytes over command socket %2
+This debug message indicates that the specified number of bytes was sent
+over command socket identifier by the specified file descriptor.
+
+% COMMAND_SOCKET_RESPONSE_TOOLARGE Server's response was larger (%1) than supported 64KB
+This error message indicates that the server received a command and generated
+an answer for it, but that response was larger than supported 64KB. Server
+will attempt to send the first 64KB of the response. Depending on the nature
+of this response, this may indicate a software or configuration error. Future
+Kea versions are expected to have better support for large responses.
+
+% COMMAND_SOCKET_WRITE_FAIL Error while writing %1 bytes to command socket %2
+This error message indicates that an error was encountered while
+attempting to send a response to the command socket.
+
+% COMMAND_SOCKET_UNIX_OPEN Command socket opened: UNIX, fd=%1, path=%2
+This informational message indicates that the daemon opened a command
+processing socket. This is a UNIX socket. It was opened with the file
+descriptor and path specified.
+
+% COMMAND_SOCKET_UNIX_CLOSE Command socket closed: UNIX, fd=%1, path=%2
+This informational message indicates that the daemon closed a command
+processing socket. This was a UNIX socket. It was opened with the file
+descriptor and path specified.
+
+% COMMAND_SOCKET_CONNECTION_OPENED Opened socket %1 for incoming command connection on socket %2
+This is an informational message that a new incoming command connection was
+detected and a dedicated socket was opened for that connection.
+
+% COMMAND_SOCKET_CONNECTION_CLOSED Closed socket %1 for existing command connection
+This is an informational message that the socket created for handling
+client's connection is closed. This usually means that the client disconnected,
+but may also mean a timeout.
+
+% COMMAND_REGISTERED Command %1 registered
+This debug message indicates that the daemon started supporting specified
+command. If the command socket is open, this command can now be issued.
+
+% COMMAND_DEREGISTERED Command %1 deregistered
+This debug message indicates that the daemon stopped supporting specified
+command. This command can no longer be issued. If the command socket is
+open and this command is issued, the daemon will not be able to process it.
+
+% CONFIG_CCSESSION_MSG error in CC session message: %1
+There was a problem with an incoming message on the command and control
+channel. The message does not appear to be a valid command, and is
+missing a required element or contains an unknown data format. This
+most likely means that another Kea module is sending a bad message.
+The message itself is ignored by this module.
+
+% CONFIG_CCSESSION_MSG_INTERNAL error handling CC session message: %1
+There was an internal problem handling an incoming message on the command
+and control channel. An unexpected exception was thrown, details of
+which are appended to the message. The module will continue to run,
+but will not send back an answer.
+
+The most likely cause of this error is a programming error.  Please raise
+a bug report.
+
+% CONFIG_CCSESSION_STOPPING error sending stopping message: %1
+There was a problem when sending a message signaling that the module using
+this CCSession is stopping. This message is sent so that the rest of the
+system is aware that the module is no longer running. Apart from logging
+this message, the error itself is ignored, and the ModuleCCSession is
+still stopped. The specific exception message is printed.
+
+% CONFIG_CCSESSION_STOPPING_UNKNOWN unknown error sending stopping message
+Similar to CONFIG_CCSESSION_STOPPING, but in this case the exception that
+is seen is not a standard exception, and further information is unknown.
+This is a bug.
+
+% CONFIG_GET_FAIL error getting configuration from cfgmgr: %1
+The configuration manager returned an error when this module requested
+the configuration. The full error message answer from the configuration
+manager is appended to the log error. The most likely cause is that
+the module is of a different (command specification) version than the
+running configuration manager.
+
+% CONFIG_JSON_PARSE JSON parse error in %1: %2
+There was an error parsing the JSON file. The given file does not appear
+to be in valid JSON format. Please verify that the filename is correct
+and that the contents are valid JSON.
+
+% CONFIG_LOG_EXPLICIT will use logging configuration for explicitly-named logger %1
+This is a debug message.  When processing the "loggers" part of the
+configuration file, the configuration library found an entry for the named
+logger that matches the logger specification for the program.  The logging
+configuration for the program will be updated with the information.
+
+% CONFIG_LOG_IGNORE_EXPLICIT ignoring logging configuration for explicitly-named logger %1
+This is a debug message.  When processing the "loggers" part of the
+configuration file, the configuration library found an entry for the
+named logger.  As this does not match the logger specification for the
+program, it has been ignored.
+
+% CONFIG_LOG_IGNORE_WILD ignoring logging configuration for wildcard logger %1
+This is a debug message.  When processing the "loggers" part of the
+configuration file, the configuration library found the named wildcard
+entry (one containing the "*" character) that matched a logger already
+matched by an explicitly named entry.  The configuration is ignored.
+
+% CONFIG_LOG_WILD_MATCH will use logging configuration for wildcard logger %1
+This is a debug message.  When processing the "loggers" part of
+the configuration file, the configuration library found the named
+wildcard entry (one containing the "*" character) that matches a logger
+specification in the program. The logging configuration for the program
+will be updated with the information.
+
+% CONFIG_MOD_SPEC_FORMAT module specification error in %1: %2
+The given file does not appear to be a valid specification file: details
+are included in the message. Please verify that the filename is correct
+and that its contents are a valid Kea module specification.
+
+% CONFIG_MOD_SPEC_REJECT module specification rejected by cfgmgr: %1
+The specification file for this module was rejected by the configuration
+manager. The full error message answer from the configuration manager is
+appended to the log error. The most likely cause is that the module is of
+a different (specification file) version than the running configuration
+manager.
+
+% CONFIG_OPEN_FAIL error opening %1: %2
+There was an error opening the given file. The reason for the failure
+is included in the message.
+
+% CONFIG_RPC_SEQ RPC call %1 to %2 with seq %3
+Debug message, saying there's a RPC call of given command to given module. It
+has internal sequence number as listed in the message.

src/lib/config/documentation.txt

-From DcConfiguration and commands in BIND10
+Configuration and commands in BIND10
+
+Introduction
+Overview
+C++ API for modules
+Python API for modules
+Specification files
+
+
+Introduction
+------------
+
+One of the goals of BIND 10 was to have 'live' configuration; to be able to change settings on the fly, and have the system remember those settings automatically, much like, for instance, a router operates.
+
+In order for this to work, it is important that all modules have a way of dynamically handling configuration updates. The way this works is explained in this document.
+
+
+Overview
+--------
+
+Central to the configuration part is the Configuration Manager b10-cfgmgr. The configuration manager loads any existing configuration, receives configuration updates from user interfaces, and notifies modules about configuration updates.
+
+UI  <---UIAPI---> Configuration Manager <---ModuleAPI---> Module
+                                        <---ModuleAPI---> Module
+                                        <---ModuleAPI---> Module
+
+When a configuration changes comes in from a UI, the configuration manager
+sends a message to the channel of the module of which the configuration is a part of.
+Through the Module API, the module automatically picks this up, and validates it.
+
+If it doesn't validate, an error is sent back to the manager, and subsequently to the UI (though this is not implemented yet).
+
+If it does, a callback function specified by the module itself is called, with the a MapElement containing the configuration items that have changed.
+
+The callback function returns a message containing either success or failure, and on success, the new configuration is locally stored in the modules session. Plans are to make this optional, so that modules have two choices; they can have the configuration stored for random access later, or they can run through the configuration when there is a changes, modify their internal structures, and then drop the full configuration. This makes handling configuration updates more complicated, but is more efficient assuming that configuration values are much more often read than written.
+
+Commands are handled in a similar way, but do not go through the configuration manager.
+
+
+C++ API For modules
+-------------------
+
+The important class for modules is isc::config::ModuleCCSession; this is the class that manages the connection to the command channel, stores the current configuration, validates new configurations, and calls callback functions as needed.
+[link to ModuleCCSession doxygen html]
+
+Upon initialization, the module provides it with a path to a specification file. This specification file contains information about the module, the configuration option the module has, and the direct commands the modules accepts. See the chapter 'specification files' for more information on these.
+
+The module also needs to provide two callback functions; one for handling configuration updates, and one for handling commands.
+
+The function for handling configuration updates has the following signature:
+isc::data::ElementPtr my_config_handler(isc::data::ElementPtr new_config);
+[link to Element doxygen html]
+
+The new_config is a ElementPtr pointing to a MapElement containing data in the form as specified by the specification file. It only contains values that were changed.
+
+The module can walk through this set and alter its behaviour accordingly if necessary. It can also simply check them and return success (see below) and reference the needed configuration values directly when necessary by calling get_config_value(std::string identifier).
+
+The callback function must return an answer message, which is created with isc::config::createAnswer(). For successful handling of the configuration, it should return the result of createAnswer(0) (0 being the result code for success). If there is a problem, the function can return the result of createAnswer(non-zero, "string_with_error_message"). In this case, the new configuration is not stored, and the error is fed back to the configuration manager.
+
+Direct commands work much the same way, only in this case the answer returned can also contain an ElementPtr with data specific to the command.
+
+The checking of new commands or configuration updates must be done manually, with the checkCommand() function. If this function is called, the moduleccsession class checks the command channel for any relevant messages, and handles them accordingly.
+
+
+Python API for modules
+----------------------
+
+The class to use in python modules is isc.config.ccsession.ModuleCCSession
+[link to doxygen python version]
+
+Again, the module initializes it with the path to a specification file, and two callback functions.
+
+It works much the same as the C++ version.
+
+The callback function for configuration updates has the form
+answer my_config_handler(new_config)
+
+Since python has dynamic typing, there is no specific class for the data that is passed to the handler, but it is a dict containing data as specified in the specification file.
+
+There are however a few convenience functions that can be found in the isc.config.data module.
+
+The answer can be created with isc.config.ccsession.create_answer(rcode, message), where rcode=0 is interpreted as success, and message can contain an error message for rcode!=0 results.
+
+The function to trigger update checks is check_command()
+
 
 Specification files
 -------------------

src/lib/config/tests/data_def_unittests_config.h.in

-// Copyright (C) 2009, 2015  Internet Systems Consortium, Inc. ("ISC")   
+// Copyright (C) 2009  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
@@ -13,3 +13,4 @@
 // PERFORMANCE OF THIS SOFTWARE.
 
 #define TEST_DATA_PATH "@abs_srcdir@/testdata"
+#define LOG_SPEC_FILE "@abs_top_srcdir@/src/bin/cfgmgr/plugins/logging.spec"

src/lib/config/tests/testdata/.gitignore

+/b10-config.db

src/lib/config/tests/testdata/Makefile.am

-EXTRA_DIST  = data22_1.data
+CLEANFILES = b10-config.db
+
+BUILT_SOURCES = b10-config.db
+
+# cfgmgr_test (under lib/python) will override b10-config.db, so we make a
+# writable copy in the builddir.
+b10-config.db: b10-config.db.master
+	cp $(srcdir)/b10-config.db.master $@
+
+EXTRA_DIST =  b10-config-bad1.db
+EXTRA_DIST += b10-config-bad2.db
+EXTRA_DIST += b10-config-bad3.db
+EXTRA_DIST += b10-config-bad4.db
+EXTRA_DIST += b10-config.db.master #.db will be auto-generated
+EXTRA_DIST += data22_1.data
 EXTRA_DIST += data22_2.data
 EXTRA_DIST += data22_3.data
 EXTRA_DIST += data22_4.data

src/lib/config/tests/testdata/b10-config-bad1.db

+{"version": 0}

src/lib/config/tests/testdata/b10-config-bad2.db

+{'version':

src/lib/config/tests/testdata/b10-config-bad4.db

+{'version': 2}

src/lib/config/tests/testdata/b10-config.db.master

+{"version": 2, "TestModule": {"test": 125}}