@section configBackendMotivation Motivation for Different Backends
-BIND10 (the project under which the first stages of Keas were developed)
+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)
@section configBackendAdding How to Add a New Configuration Backend
-@todo Will be covered in ticket #3400.
+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):
+
+-# 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 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().
+
+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
-# A new parameter called --with-kea-config will be implemented in the
configure script. It will allow the selection at compilation time of how the
servers will be configured. For the next 2-3 months (until around June 2014),
- there will be two values: JSON (read from file) and BIND10 (use the BIND10 framework).
+ there will be two values: JSON (read from file) and BUNDY (use the BUNDY/BIND10 framework).
Once the file based configuration is implemented and the Kea team is ready to switch
(i.e. enough confidence, Forge tests updated for new configuration
- mechanism), the BIND10 backend will be removed from the Kea repository. Other projects
+ mechanism), the Bundy/BIND10 framework will be removed from the Kea repository. Other projects
(e.g. Bundy) who want to maintain it, are advised to just revert the single
- commit that will bring the BIND10 framework back to their repositories.<br/><br/>
+ commit that will bring the Bundy framework back to their repositories.
This switchable backend concept is quite simple. There are just different
implementations of ControlledXSrv class, so it is a matter of compiling/linking
one file or another. Hence it is easy to remove the old backend (and for
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).<br/><br/>
--# 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.<br/><br/>
--# 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.<br/><br/>
- 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".<br/><br/>
--# 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.<br/><br/>
--# 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 will simply remove 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).<br/><br/>
--# 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.<br/><br/>
+ 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.
+
+-# 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 will simply remove 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).
+
+-# 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.
+
-# A way is needed to initialize stand-alone logging (i.e. each
- Kea component will initialize it on its own).<br/><br/>
+ Kea component will initialize it on its own).
+
-# The current format of the BIND10 configuration file, b10-config.db will be
retained as the configuration file format. This is slight change
from the BIND10 days, as then a subset of the configuration was received by
- the daemon processes.<br/><br/>
- To take a specific example, the following is how b10-config.db
- looks today:<br/><br/>
+ the daemon processes. To take a specific example, the following is how
+ b10-config.db looks today:
@code
{
"Init": { ... }
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.<br/><br/>
+ 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).<br/><br/>
+ 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
/**
- @page contributorGuide BIND10 Contributor's Guide
+ @page contributorGuide Kea Contributor's Guide
-So you found a bug in BIND10 or plan to develop an extension and want to
+So you found a bug in Kea or plan to develop an extension and want to
send a patch? Great! This page will explain how to contribute your
changes smoothly.
@section contributorGuideWritePatch Writing a patch
-Before you start working on a patch or a new feature, it is a good idea
-to discuss it first with BIND10 developers. You can post your questions
-to the \c bind10-dev mailing list
-(https://lists.isc.org/mailman/listinfo/bind10-dev) for general BIND10
-stuff, or to the \c bind10-dhcp mailing list
-(https://lists.isc.org/mailman/listinfo/bind10-dhcp) for DHCP specific
-topics. If you prefer to get faster feedback, most BIND10 developers
-hang out in the \c bind10 jabber room
-(xmpp:bind10@conference.jabber.isc.org). Those involved in DHCP also use
-the \c dhcp chatroom (xmpp:dhcp@conference.jabber.isc.org). Feel free to
-join these rooms and talk to us. It is possible that someone else is
-working on your specific issue or perhaps the solution you plan to
-implement is not the best one. Often having a 10 minute talk could save
-many hours of engineering work.
+Before you start working on a patch or a new feature, it is a good
+idea to discuss it first with Kea developers. You can post your
+questions to the \c kea-dev mailing list
+(https://lists.isc.org/mailman/listinfo/kea-dev) or kea-users
+(https://lists.isc.org/mailman/listinfo/kea-users). Kea-users list
+is intended for users who are not interested in the internal working
+or development details. It is ok to ask for feedback regarding new
+design or the best proposed solution to a certain problem, but all
+the internal details should be limited to kea-dev and not posted
+on kea-users. If you prefer to get
+faster feedback, most Kea developers hang out in the \c dhcp
+jabber room (xmpp:dhcp@conference.jabber.isc.org). Feel free to join this
+room and talk to us. It is possible that someone else is working on your
+specific issue or perhaps the solution you plan to implement is not
+the best one. Often having a 10 minute talk could save many hours of
+engineering work.
First step would be to get the source code from our Git repository. The
procedure is very easy and is explained here:
-http://bind10.isc.org/wiki/GitGuidelines. While it is possible to
+http://kea.isc.org/wiki/GitGuidelines. While it is possible to
provide a patch against the latest stable release, it makes the review
process much easier if it is for latest code from the Git \c master
branch.
Ok, so you have written a patch? Great! Before you submit it, make sure
that your code compiles. This may seem obvious, but there's more to
-it. You have surely checked that it compiles on your system, but BIND10
-is portable software. Besides Linux, it is compiled and used on
+it. You have surely checked that it compiles on your system, but Kea
+is a portable software. Besides Linux, it is compiled and used on
relatively uncommon systems like OpenBSD and Solaris 11. Will your code
compile and work there? What about endianess? It is likely that you used
a regular x86 architecture machine to write your patch, but the software
is expected to run on many other architectures. You may take a look at
-system specific build notes (http://bind10.isc.org/wiki/SystemSpecificNotes).
+system specific build notes (http://kea.isc.org/wiki/SystemSpecificNotes).
For a complete list of systems we build on, you may take a look at the
-following build farm report: http://git.bind10.isc.org/~tester/builder/builder-new.html .
+following build farm report: http://git.kea.isc.org/~tester/builder/KEA-builder-new.html .
-Does your patch conform to BIND10 coding guidelines
-(http://bind10.isc.org/wiki/CodingGuidelines)? You still can submit a
+Does your patch conform to Kea coding guidelines
+(http://kea.isc.org/wiki/CodingGuidelines)? You still can submit a
patch that does not adhere to it, but that will decrease its chances of
-being accepted. If the deviations are minor, the BIND10 engineer who
+being accepted. If the deviations are minor, the Kea engineer who
does the review will likely fix the issues. However, if there are lots
of issues, the reviewer may simply reject the patch and ask you to fix
it before re-submitting.
@section contributorGuideUnittests Running unit-tests
-One of the ground rules in BIND10 development is that every piece of
+One of the ground rules in Kea development is that every piece of
code has to be tested. We now have an extensive set of unit-tests for
almost every line of code. Even if you are fixing something small,
like a single line fix, it is encouraged to write unit-tests for that
function, method or a class, you definitely should write unit-tests
for it.
-BIND10 uses the Google C++ Testing Framework (also called googletest or
+Kea uses the Google C++ Testing Framework (also called googletest or
gtest) as a base for our C++ unit-tests. See
-http://code.google.com/p/googletest/ for details. For Python unit-tests,
-we use the its \c unittest library which is included in Python. You must
+http://code.google.com/p/googletest/ for details. We still have some Python
+unit-tests that we inherited from BIND10 days, but those tests are being
+removed, so please do not develop any new Python tests in Kea. (If you
+want to write DHCP tests in Python, we encourage you to take a look
+at ISC Forge: http://kea.isc.org/wiki/IscForge). You must
have \c gtest installed or at least extracted in a directory before
-compiling BIND10 unit-tests. To enable unit-tests in BIND10, use:
+compiling Kea unit-tests. To enable unit-tests in Kea, use:
@code
./configure --with-gtest=/path/to/your/gtest/dir
code, you are likely to be interested in enabling the MySQL backend for
DHCP. Note that if the backend is not enabled, MySQL specific unit-tests
are skipped. From that perspective, it is useful to use
-\c --with-dhcp-mysql. For a complete list of all switches, use:
+\c --with-dhcp-mysql. For PostgreSQL, use \c --with-dhcp-pgsql. For a
+complete list of all switches, use:
@code
./configure --help
@section contributorGuideReview Going through a review
Once all those are checked and working, feel free to create a ticket for
-your patch at http://bind10.isc.org/ or attach your patch to an existing
+your patch at http://kea.isc.org/ or attach your patch to an existing
ticket if you have fixed it. It would be nice if you also join the
-\c bind10 or \c dhcp chatroom saying that you have submitted a
-patch. Alternatively, you may send a note to the \c bind10-dev or
-\c bind10-dhcp mailing lists.
+\c dhcp chatroom saying that you have submitted a patch. Alternatively,
+you may send a note to the \c kea-dev mailing list.
-Here's the tricky part. One of BIND10 developers will review your patch,
+Here's the tricky part. One of Kea developers will review your patch,
but it may not happen immediately. Unfortunately, developers are usually
working under a tight schedule, so any extra unplanned review work may
take a while sometimes. Having said that, we value external
after first review. To keep the code quality high, we use the same
review processes for internal code and for external patches. It may take
some cycles of review/updated patch submissions before the code is
-finally accepted.
+finally accepted. The nature of the review process is that it emphasizes
+areas that need improvement. If you are not used to the review process,
+you may get the impression that the feedback is negative. It is not. We
+seldom see reviews that say "all ok, please merge".
Once the process is almost complete, the developer will likely ask you
how you would like to be credited. The typical answers are by first and
@section contributorGuideExtra Extra steps
If you are interested in knowing the results of more in-depth testing,
-you are welcome to visit the BIND10 build farm:
-http://git.bind10.isc.org/~tester/builder/builder-new.html. This is a
+you are welcome to visit the Kea build farm:
+http://git.kea.isc.org/~tester/builder/KEA-builder-new.html. This is a
live result page with all tests being run on various systems. Besides
basic unit-tests, we also have reports from Valgrind (memory debugger),
cppcheck and clang-analyzer (static code analyzers), Lettuce system
tests and more. Although it is not possible for non ISC employees to run
tests on that farm, it is possible that your contributed patch will end
-up there sooner or later.
+up there sooner or later. We also have ISC Forge tests running, but currently
+the test results are not publicly available.
*/
*
* Welcome to Kea Developer's Guide. This documentation is addressed
* at existing and prospecting developers and programmers and provides
- * information needed to both extend and maintain BIND 10.
+ * information needed to both extend and maintain Kea.
*
* If you wish to write "hook" code - code that is loaded by Kea at
* run-time and modifies its behavior you should read the section
* If you are a user or system administrator, rather than software engineer,
* you should read the
* <a href="http://kea.isc.org/docs/bind10-guide.html">Kea
- * Guide (Administrator Reference for Kea)</a> instead.
+ * Administrator Reference Manual</a> instead.
*
* Regardless of your field of expertise, you are encouraged to visit the
* <a href="http://kea.isc.org/">Kea webpage (http://kea.isc.org)</a>
* - @subpage libdhcp_ddns
*
* @section miscellaneousTopics Miscellaneous Topics
- * - @subpage logBind10Logging
+ * - @subpage logKeaLogging
* - @subpage logBasicIdeas
* - @subpage logDeveloperUse
* - @subpage logNotes
/**
@page dhcp4 DHCPv4 Server Component
-BIND10 offers DHCPv4 server implementation. It is implemented as
+Kea offers DHCPv4 server implementation. It is implemented as
b10-dhcp4 component. Its primary code is located in
isc::dhcp::Dhcpv4Srv class. It uses \ref libdhcp extensively,
especially isc::dhcp::Pkt4, isc::dhcp::Option and
only), as support for transmission to hosts without IPv4 address
assigned is not implemented in IfaceMgr yet.
-@section dhcpv4Session BIND10 message queue integration
+@section dhcpv4Session Bundy message queue integration
-DHCPv4 server component is now integrated with BIND10 message queue.
+DHCPv4 server now has two configuration backends: JSON and Bundy. The
+following section applies only to the Bundy backend.
+
+DHCPv4 server component is now integrated with Bundy message queue.
The integration is performed by establishSession() and disconnectSession()
functions in isc::dhcp::ControlledDhcpv4Srv class. main() method defined
in the src/bin/dhcp4/main.cc file instantiates isc::dhcp::ControlledDhcpv4Srv
@section dhcpv4ConfigBackend Configuration backend for DHCPv4
There are many theoretical ways in which server configuration can be stored. Kea 0.8 and
-earlier versions used BIND10 framework and its internal storage for DHCPv6 server configuration.
+earlier versions used BIND10/Bundy framework and its internal storage for DHCPv6 server configuration.
The legacy ISC-DHCP implementation uses flat files. Configuration stored in JSON files is
becoming more and more popular among various projects. There are unofficial patches for
ISC-DHCP that keep parts of the configuration in LDAP. It was also suggested that in some
two values: BUNDY and JSON.
BUNDY (which is the default value as of May 2014) means that Kea4 is linked with the
-Bundy (former BIND10) configuration backend that connects to the BIND10 framework and in general works
+Bundy (former BIND10) configuration backend that connects to the Bundy/BIND10 framework and in general works
exactly the same as Kea 0.8 and earlier versions. The benefits of that backend are uniform
integration with Bundy/BIND10 framework, easy on-line reconfiguration using bindctl, available
RESTful API. On the other hand, it requires the whole heavy Bundy framework that requires
@page dhcpv4Hooks The Hooks API for the DHCPv4 Server
@section dhcpv4HooksIntroduction Introduction
- BIND10 features an API (the "Hooks" API) that allows user-written code to
- be integrated into BIND 10 and called at specific points in its processing.
+ Kea features an API (the "Hooks" API) that allows user-written code to
+ be integrated into Kea and called at specific points in its processing.
An overview of the API and a tutorial for writing such code can be found in
- the @ref hooksdgDevelopersGuide. Information for BIND 10 maintainers can be
+ the @ref hooksdgDevelopersGuide. Information for Kea maintainers can be
found in the @ref hooksComponentDeveloperGuide.
This manual is more specialised and is aimed at developers of hook
/**
@page dhcp6 DHCPv6 Server Component
- BIND10 offers DHCPv6 server implementation. It is implemented as
+ Kea offers DHCPv6 server implementation. It is implemented as
b10-dhcp6 component. Its primary code is located in
isc::dhcp::Dhcpv6Srv class. It uses \ref libdhcp extensively,
especially lib::dhcp::Pkt6, isc::dhcp::Option and
DHCPv6 server component does not support relayed traffic yet, as
support for relay decapsulation is not implemented yet.
- DHCPv6 server component does not use BIND10 logging yet.
+ @section dhcpv6Session Bundy message queue integration
- @section dhcpv6Session BIND10 message queue integration
+DHCPv4 server now has two configuration backends: JSON and Bundy. The
+following section applies only to the Bundy backend.
- DHCPv6 server component is now integrated with BIND10 message queue.
+ DHCPv6 server component is now integrated with Bundy/BIND10 message queue.
It follows the same principle as DHCPv4. See \ref dhcpv4Session for
details.
@section dhcpv6ConfigParser Configuration Parser in DHCPv6
- b10-dhcp6 component uses BIND10 cfgmgr for commands and configuration. During
- initial configuration (See \ref
+ Bundy configuration in the Kea6 component uses Bundy cfgmgr for commands and
+ configuration. During initial configuration (See \ref
isc::dhcp::ControlledDhcpv6Srv::establishSession()), the configuration handler
callback is installed (see isc::dhcp::ControlledDhcpv6Srv::dhcp6ConfigHandler().
It is called every time there is a new configuration. In particular, it is
server, i.e. to send DNS Update messages. The b10-dhcp6 module is responsible
for generating so called @ref isc::dhcp_ddns::NameChangeRequest and sending it to the
b10-dhcp-ddns module. The @ref isc::dhcp_ddns::NameChangeRequest object represents changes to the
-DNS bindings, related to acquisition, renewal or release of the lease. The bind10-dhcp6
+DNS bindings, related to acquisition, renewal or release of the lease. The b10-dhcp6
module implements the simple FIFO queue of the NameChangeRequest objects. The module
logic, which processes the incoming DHCPv6 Client FQDN Options puts these requests
into the FIFO queue.
send them to the b10-dhcp-ddns module when server is idle waiting for DHCP messages.
In the simplest case, when client gets one address from the server, a DHCPv6 server
-may generate 0, 1 or 2 NameChangeRequests during single message processing.
+may generate 0, 1 or 2 NameChangeRequests during single message processing.
Server generates no NameChangeRequests if it is not configured to update DNS
or it rejects the DNS update for any other reason.
@section dhcpv6ConfigBackend Configuration backend for DHCPv6
There are many theoretical ways in which server configuration can be stored. Kea 0.8 and
-earlier versions used BIND10 framework and its internal storage for DHCPv6 server configuration.
+earlier versions used Bundy/BIND10 framework and its internal storage for DHCPv6 server configuration.
The legacy ISC-DHCP implementation uses flat files. Configuration stored in JSON files is
becoming more and more popular among various projects. There are unofficial patches for
ISC-DHCP that keep parts of the configuration in LDAP. It was also suggested that in some
two values: BUNDY and JSON.
BUNDY (which is the default value as of April 2014) means that Kea6 is linked with the
-Bundy (former BIND10) configuration backend that connects to the BIND10 framework and in general works
+Bundy (former BIND10) configuration backend that connects to the Bundy/BIND10 framework and in general works
exactly the same as Kea 0.8 and earlier versions. The benefits of that backend are uniform
integration with Bundy/BIND10 framework, easy on-line reconfiguration using bindctl, available
RESTful API. On the other hand, it requires the whole heavy Bundy framework that requires
@page dhcpv6Hooks The Hooks API for the DHCPv6 Server
@section dhcpv6HooksIntroduction Introduction
- BIND10 features an API (the "Hooks" API) that allows user-written code to
- be integrated into BIND 10 and called at specific points in its processing.
+ Kea features an API (the "Hooks" API) that allows user-written code to
+ be integrated into Kea and called at specific points in its processing.
An overview of the API and a tutorial for writing such code can be found in
- the @ref hooksdgDevelopersGuide. Information for BIND 10 maintainers can be
+ the @ref hooksdgDevelopersGuide. Information for Kea maintainers can be
found in the @ref hooksComponentDeveloperGuide.
This manual is more specialised and is aimed at developers of hook
@section libdhcp_user_chkIntro Libdhcp_user_chk: An Example Hooks Library
## Introduction
libdhcp_user_chk is an example hooks library which customizes the DHCP query
-processing provided by BIND X DHCP server modules (b10-dhcp4 and b10-dhcp6).
+processing provided by Kea DHCP server modules (b10-dhcp4 and b10-dhcp6).
Specifically it allows subnet selection and DHCP response option customization
-based upon a registry of DHCP clients. Note that the words "client" and "user" are used interchangeably herein. The intent of the custom behavior is three
+based upon a registry of DHCP clients. Note that the words "client" and "user"
+are used interchangeably herein. The intent of the custom behavior is three
fold:
1. To assign "new" or "unregistered" users to a restricted subnet, while "known"
2. To allow DHCP response options or vendor option values to be customized
based upon user identity.
-3. To provide a real time record of the user registration activity which can be sampled by an external consumer.
+3. To provide a real time record of the user registration activity which can be
+sampled by an external consumer.
## User Registry Classes
At the heart of the library is a class hierarchy centered around the class,
## Using the library
Two steps are required in order to use the library:
-# The user registry file must be created and deployed
--# The BIND10 DHCP module(s) must be configured to load the library
+-# The Kea DHCP module(s) must be configured to load the library
### Creating the Registry File
Currently, the library uses a hard coded pathname for the user registry defined
the library will unload.
### Configuring the DHCP Modules
-it must be configured as a hook library for the
-desired DHCP server modules. Note that the user_chk library is installed alongside the BIND10 libraries in "<install-dir>/lib" where <install-dir> is determined by the --prefix option of the configure script. It defaults to "/usr/local". Assuming the default value then, configuring b10-dhcp4 to load the user_chk
-library could be done with the following BIND10 configuration commands:
+
+It must be configured as a hook library for the desired DHCP server modules.
+Note that the user_chk library is installed alongside the Kea libraries in
+"<install-dir>/lib" where <install-dir> is determined by the --prefix option of
+the configure script. It defaults to "/usr/local". Assuming the default value
+then, configuring b10-dhcp4 to load the user_chk library could be done with the
+following Kea4 configuration:
@code
-config add Dhcp4/hook_libraries
-config set Dhcp4/hook_libraries[0] "/usr/local/lib/libdhcp_user_chk.so"
-config commit
+"Dhcp4": {
+ "hook_libraries": [ "/usr/local/lib/libdhcp_user_chk.so" ],
+ ...
+}
@endcode
To configure it for b10-dhcp6, the commands are simply as shown below:
@code
-config add Dhcp6/hook_libraries
-config set Dhcp6/hook_libraries[0] "/usr/local/lib/libdhcp_user_chk.so"
-config commit
+"Dhcp6": {
+ "hook_libraries": [ "/usr/local/lib/libdhcp_user_chk.so" ],
+ ...
+}
@endcode
## User Check Outcome
Once up and running, the library should begin adding entries to the outcome
-file. Currently, the library uses a hard coded pathname for the user registry defined in load_unload.cc:
+file. Currently, the library uses a hard coded pathname for the user registry
+defined in load_unload.cc:
+@code
const char* user_chk_output_fname = "/tmp/user_chk_outcome.txt";
+@endcode
If the file cannot be created (or opened), the library will unload.
For each lease granted, the library will add the following information to the
end of the file: the id type, the user id, the lease or prefix granted, and
whether or not the user was found in the registry. This information is written
-in the form of "name=value" with one value per line. (See subnet_callout.cc for details.)
+in the form of "name=value" with one value per line. (See subnet_callout.cc for
+details.)
A sample outcome file is shown below:
/// Instantiates the UserRegistry and opens the outcome file. Failure in
/// either results in a failed return code.
///
-/// @param unused library handle parameter required by Hooks API.
-///
/// @return Returns 0 upon success, non-zero upon failure.
int load(LibraryHandle&) {
// non-zero indicates an error.
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.
-/// @file pkt_receive.cc Defines the pkt4_receive and pkt6_receive callout functions.
+/// @file pkt_receive_co.cc Defines the pkt4_receive and pkt6_receive callout functions.
#include <hooks/hooks.h>
#include <dhcp/pkt4.h>
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.
-/// @file pkt_send.cc Defines the pkt4_send and pkt6_send callout functions.
+/// @file pkt_send_co.cc Defines the pkt4_send and pkt6_send callout functions.
#include <asiolink/io_address.h>
#include <hooks/hooks.h>
/// Each user entry is written in an ini-like format, with one name-value pair
/// per line as follows:
///
-/// id_type=<id type>
-/// client=<id str>
-/// subnet=<subnet str>
-/// registered=<is registered>"
+/// id_type=<id type><br/>
+/// client=<id str><br/>
+/// subnet=<subnet str><br/>
+/// registered=<is registered>
///
/// where:
/// <id type> text label of the id type: "HW_ADDR" or "DUID"
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.
-/// @file subnet_select.cc Defines the subnet4_select and subnet6_select callout functions.
+/// @file subnet_select_co.cc Defines the subnet4_select and subnet6_select callout functions.
#include <hooks/hooks.h>
#include <dhcp/pkt4.h>
%@endverbatim
The unit tests are run automatically when "make check" is executed (providing
- that BIND 10 has been build with the \--with-dhcp-mysql switch (see the installation
- section in the <a href="http://bind10.isc.org/docs/bind10-guide.html">BIND 10 Guide</a>).
+ that Kea has been build with the \--with-dhcp-mysql switch (see the installation
+ section in the <a href="http://kea.isc.org/docs/kea-guide.html">Kea Administrator
+ Reference Manual</a>).
@subsection dhcp-pgsql-unittest PostgreSQL Unit Tests
that runs tests. Use caution!
The unit tests are run automatically when "make check" is executed (providing
- that BIND 10 has been build with the \--with-dhcp-pgsql switch (see the installation
- section in the <a href="http://bind10.isc.org/docs/bind10-guide.html">BIND10 Guide</a>).
+ that Kea has been build with the \--with-dhcp-pgsql switch (see the installation
+ section in the <a href="http://kea.isc.org/docs/kea-guide.html">Kea Administrator
+ Reference Manual</a>).
*/
necessary for DHCPv4 and DHCPv6 server operation. In particular, it stores
subnets (\ref isc::dhcp::Subnet4 and \ref isc::dhcp::Subnet6) together with
their pools (\ref isc::dhcp::Pool4 and \ref isc::dhcp::Pool6), options and
-other information specified by the used in BIND10 configuration.
+other information specified by the used in Kea configuration.
@section allocengine Allocation Engine
// PERFORMANCE OF THIS SOFTWARE.
/**
-@page hooksComponentDeveloperGuide Guide to Hooks for the BIND 10 Component Developer
+@page hooksComponentDeveloperGuide Guide to Hooks for the Kea Component Developer
@section hooksComponentIntroduction Introduction
-The hooks framework is a BIND 10 system that simplifies the way that
-users can write code to modify the behavior of BIND 10. Instead of
-altering the BIND 10 source code, they write functions that are compiled
-and linked into a shared library. The library is specified in the BIND 10
-configuration database and run time, BIND 10 dynamically loads the library
+The hooks framework is a Kea system that simplifies the way that
+users can write code to modify the behavior of Kea. Instead of
+altering the Kea source code, they write functions that are compiled
+and linked into a shared library. The library is specified in the Kea
+configuration and during run time Kea dynamically loads the library
into its address space. At various points in the processing, the component
"calls out" to functions in the library, passing to them the data is it
currently working on. They can examine and modify the data as required.
-This guide is aimed at BIND 10 developers who want to write or modify a
-BIND 10 component to use hooks. It shows how the component should be written
+This guide is aimed at Kea developers who want to write or modify a
+Kea component to use hooks. It shows how the component should be written
to load a shared library at run-time and how to call functions in it.
-For information about writing a hooks library containing functions called by BIND 10
+For information about writing a hooks library containing functions called by Kea
during its execution, see the document @ref hooksdgDevelopersGuide.
@subsection hooksComponentTerminology Terminology
In the remainder of this guide, the following terminology is used:
-- Component - a BIND 10 process, e.g. the authoritative DNS server or the
-DHCPv4 server.
+- Component - a Kea process, e.g. a DHCPv4 or DHCPv6 server.
- Hook/Hook Point - used interchageably, this is a point in the code at
which a call to user-written functions is made. Each hook has a name and
point. This is so-named because the component "calls out" to the library
to execute a user-written function.
-- User code/user library - non-BIND 10 code that is compiled into a
-shared library and loaded by BIND 10 into its address space. Multiple
+- User code/user library - non-Kea code that is compiled into a
+shared library and loaded by Kea into its address space. Multiple
user libraries can be loaded at the same time, each containing callouts for
the same hooks. The hooks framework calls these libraries one after the
other. (See the document @ref hooksdgDevelopersGuide for more details.)
@subsection hooksComponentLanguages Languages
-The core of BIND 10 is written in C++ with some parts in Python. While it is
-the intention to provide the hooks framework for all languages, the initial
-version is for C++. All examples in this guide are in that language.
+The core of Kea is written in C++ with some remaining legacy parts in Python.
+While it is the intention to provide the hooks framework for all languages,
+the initial version is for C++. All examples in this guide are in that language.
@section hooksComponentBasicIdeas Basic Ideas
Before any other action takes place, the location of the hook points
in the code need to be determined. This of course depends on the
component but as a general guideline, hook locations should be chosen
-where a callout is able to obtain useful information from BIND 10 and/or
+where a callout is able to obtain useful information from Kea and/or
affect processing. Typically this means at the start or end of a major
step in the processing of a request, at a point where either useful
information can be passed to a callout and/or the callout can affect
square-root function in the system's maths library being attached to the hook
as a callout).
-- Although hook names can be in any case (including mixed case), the BIND 10
+- Although hook names can be in any case (including mixed case), the Kea
convention is that they are lower-case.
@section hooksComponentCallingCallouts Calling Callouts on a Hook
isc::hooks::HooksManager::calloutsPresent() will return false for every
index, and isc::hooks::HooksManager::callCallouts() will be a no-op.
-However, if user libraries are specified in the BIND 10 configuration,
+However, if user libraries are specified in the Kea configuration,
the component should load them. (Note the term "libraries": the hooks
framework allows multiple user libraries to be loaded.) This should take
place after the component's configuration has been read, and is achieved
to a packet: the memory allocated for those options will most likely
lie in library address space.
-The problem really arises because of the extensive use by BIND 10 of boost
+The problem really arises because of the extensive use by Kea of boost
smart pointers. When the pointer is destroyed, the pointed-to memory is
deallocated. If the pointer points to address space that is unmapped because
a library has been unloaded, the deletion causes a segmentation fault.
@section hooksmgIntroduction Introduction
- This document is aimed at BIND 10 maintainers responsible for the hooks
+ This document is aimed at Kea maintainers responsible for the hooks
system. It provides an overview of the classes that make up the hooks
framework and notes important aspects of processing. More detailed
information can be found in the source code.
The user-side code is able to access two objects in the framework,
the @ref hooksmgCalloutHandle and the @ref hooksmgLibraryHandle.
- The @ref hooksmgCalloutHandle is used to pass data between the BIND 10
+ The @ref hooksmgCalloutHandle is used to pass data between the Kea
component and the loaded library; the @ref hooksmgLibraryHandle is used
for registering callouts.
@subsubsection hooksmgCalloutHandle Callout Handle
The @ref isc::hooks::CalloutHandle has two functions: passing arguments
- between the BIND 10 component and the user-written library, and storing
+ between the Kea component and the user-written library, and storing
per-request context between library calls. In both cases the data is
stored in a std::map structure, keyed by argument (or context item) name.
The actual data is stored in a boost::any object, which allows any
context_create and context_destroy hooks.
In operation, the @ref hooksmgHooksManager provides a thin wrapper
- around it, so that the BIND 10 component developer does not have to
+ around it, so that the Kea component developer does not have to
worry about another object.
@subsubsection hooksmgLibraryManager Library Manager
As the LibraryManager provides all the methods needed to manage the
shared library, it is the natural home for the static validateLibrary()
- method. The function called the parsing of the BIND 10 configuration, when
+ method. The function called the parsing of the Kea configuration, when
the "hooks-libraries" element is processed. It checks that shared library
exists, that it can be opened, that it contains the "version()" function
and that that function returns a valid value. It then closes the shared
One point of note is that LibraryManagerCollection operates on an "all
or none" principle. When loadLibraries() is called, on exit either all
libraries have been successfully opened or none of them have. There
- is no use-case in BIND 10 where, after a user has specified the shared
+ is no use-case in Kea where, after a user has specified the shared
libraries they want to load, the system will operate with only some of
them loaded.
(Whilst on the subject of library index numbers, two additional
numbers - 0 and INT_MAX - are also valid as "current library index".
- For flexibility, the BIND 10 component is able to register its own
+ For flexibility, the Kea component is able to register its own
functions as hook callouts. It does this by obtaining a suitable @ref
hooksmgLibraryHandle from the @ref hooksmgHooksManager. A choice
of two is available: one @ref hooksmgLibraryHandle (with an index
to a packet: the memory allocated for those options will most likely
lie in library address space.
- The problem really arises because of the extensive use by BIND 10 of
+ The problem really arises because of the extensive use by Kea of
boost smart pointers. When the pointer is destroyed, the pointed-to
memory is deallocated. If the pointer points to address space that is
unmapped because a library has been unloaded, the deletion causes a
and the address space unmapped.
The hooks framework cannot solve the second issue as the objects in
- question are under control of the BIND 10 server incorporating the
+ question are under control of the Kea server incorporating the
hooks. It is up to the server developer to ensure that all such objects
have been destroyed before libraries are reloaded. In extreme cases
this may mean the server suspending all processing of incoming requests
until all currently executing requests have completed and data object
destroyed, reloading the libraries, then resuming processing.
- @subsection hooksmgStaticLinking Hooks and Statically-Linked BIND 10
+ @subsection hooksmgStaticLinking Hooks and Statically-Linked Kea
- BIND 10 has the configuration option to allow static linking. What this
- means is that it links against the static BIND 10 libraries and not
+ Kea has the configuration option to allow static linking. What this
+ means is that it links against the static Kea libraries and not
the shareable ones - although it links against the shareable system
libraries like "libc" and "libstdc++" and well as the sharable libraries
for third-party packages such as log4cplus and MySql.
Static linking poses a problem for dynamically-loaded hooks libraries
as some of the code in them - in particular the hooks framework and
the logging code - depend on global objects created within the BIND
- 10 libraries. In the normal course of events (BIND 10 linked against
- shared libraries), when BIND 10 is run and the operating system loads
- a BIND 10 shared library containing a global object, address space
+ 10 libraries. In the normal course of events (Kea linked against
+ shared libraries), when Kea is run and the operating system loads
+ a Kea shared library containing a global object, address space
is assigned for it. When the hooks framework loads a user-library
- linked against the same BIND 10 shared library, the operating system
+ linked against the same Kea shared library, the operating system
recognises that the library is already loaded (and initialized) and
uses its definition of the global object. Thus both the code in the
- BIND 10 image and the code in the user-written shared library
+ Kea image and the code in the user-written shared library
reference the same object.
- If BIND 10 is statically linked, the linker allocates address space
- in the BIND 10 image for the global object and does not include any
- reference to the shared library containing it. When BIND 10 now loads
- the user-written shared library - and so loads the BIND 10 library code
+ If Kea is statically linked, the linker allocates address space
+ in the Kea image for the global object and does not include any
+ reference to the shared library containing it. When Kea now loads
+ the user-written shared library - and so loads the Kea library code
containing the global object - the operating system does not know that
the object already exists. Instead, it allocates new address space.
- The version of BIND 10 in memory therefore has two copies of the object:
- one referenced by code in the BIND 10 image, and one referenced by code
+ The version of Kea in memory therefore has two copies of the object:
+ one referenced by code in the Kea image, and one referenced by code
in the user-written hooks library. This causes problems - information
put in one copy is not available to the other.
isc::hooks::ServerHooks object, used by the user-written hooks library
if it attempts to register or deregister callouts. The contents of the
singleton - the names of the hook points and their index - are set by
- the relevant BIND 10 server; this information is not available in the
+ the relevant Kea server; this information is not available in the
singleton created in the user's hooks library.
Within the code users by the user's hooks library, the ServerHooks
the constructors of these objects store a reference to the singleton
ServerHooks when they are created and use that reference to access
ServerHooks data. Since both CalloutHandle and CalloutManager are
- created in the statically-linked BIND 10 server, use of the reference
+ created in the statically-linked Kea server, use of the reference
means that it is the singleton within the server - and not the one
within the user's hooks library - that is referenced.
The solution of the logging problem is not so straightforward. Within
- BIND 10, there are two logging components, the BIND 10 logging framework
+ Kea, there are two logging components, the Kea logging framework
and the log4cplus libraries. Owing to static linking, there are two
instances of the former; but as static linking uses shared libraries of
third-party products, there is one instance of the latter. What further
The logging initialization comprises the following:
-# Static initialization of the log4cplus global variables.
- -# Static initialization of messages in the various BIND 10 libraries.
+ -# Static initialization of messages in the various Kea libraries.
-# Static initialization of logging framework.
-# Run-time initialization of the logging framework.
-# Run-time initialization of log4cplus
- As both the BIND 10 server and the user-written hooks libraries use the
+ As both the Kea server and the user-written hooks libraries use the
log4cplus shared library, item 1 - the static initialization of the log4cplus
global variables is performed once.
The next two tasks - static initialization of the messages in the BIND
10 libraries and the static initialization of the logging framework -
- are performed twice, once in the context of the BIND 10 server and
+ are performed twice, once in the context of the Kea server and
once in the context of the hooks library. For this reason, run-time
initialization of the logging framework needs to be performed twice,
- once in the context of the BIND 10 server and once in the context of the
+ once in the context of the Kea server and once in the context of the
user-written hooks library. However, the standard logging framework
initialization code also performs the last task, initialization of
log4cplus, something that causes problems if executed more than once.
has been written. It executes the only part of the logging framework
run-time initialization that actually pertains to the logging framework
and not log4cplus, namely loading the message dictionary with the
- statically-initialized messages in the BIND 10 libraries.
+ statically-initialized messages in the Kea libraries.
This should be executed by any hooks library linking against a statically
- initialized BIND 10. (In fact, running it against a dynamically-linked
- BIND 10 should have no effect, as the load operation discards any duplicate
+ initialized Kea. (In fact, running it against a dynamically-linked
+ Kea should have no effect, as the load operation discards any duplicate
message entries.) The hooks library tests do this, the code being
copnditionally compiled within a test of the USE_STATIC_LINK macro, set
by the configure script.
@note Not everything is completely rosy with logging and static linking.
In particular, there appears to be an issue with the scenario where a
- user-written hooks library is run by a statically-linked BIND 10 and then
+ user-written hooks library is run by a statically-linked Kea and then
unloaded. As far as can be determined, on unload the system attempts to
delete the same logger twice. This is alleviated by explictly clearing
the loggerptr_ variable in the isc::log::Logger destructor, but there
@section hooksdgIntroduction Introduction
-Although the BIND 10 framework and its associated DNS and DHCP programs
+Although the Kea framework and its DHCP programs
provide comprehensive functionality, there will be times when it does
not quite do what you require: the processing has to be extended in some
way to solve your problem.
-Since the BIND 10 source code is freely available (BIND 10 being an
+Since the Kea source code is freely available (Kea being an
open-source project), one option is to modify it to do what
you want. Whilst perfectly feasible, there are drawbacks:
-- Although well-documented, BIND 10 is a large program. Just
+- Although well-documented, Kea is a large program. Just
understanding how it works will take a significant amount of time. In
addition, despite the fact that its object-oriented design keeps the
coupling between modules to a minimum, an inappropriate change to one
behave oddly or to stop working altogether.
- The change may need to be re-applied or re-written with every new
-version of BIND 10. As new functionality is added or bugs are fixed,
+version of Kea. As new functionality is added or bugs are fixed,
the code or algorithms in the core software may change - and may change
significantly.
-To overcome these problems, BIND 10 provides the "Hooks" interface -
+To overcome these problems, Kea provides the "Hooks" interface -
a defined interface for third-party or user-written code. (For ease of
reference in the rest of this document, all such code will be referred
to as "user code".) At specific points in its processing
-("hook points") BIND 10 will make a call to this code. The call passes
+("hook points") Kea will make a call to this code. The call passes
data that the user code can examine and, if required, modify.
-BIND 10 uses the modified data in the remainder of its processing.
+Kea uses the modified data in the remainder of its processing.
-In order to minimise the interaction between BIND 10 and the user
-code, the latter is built independently of BIND 10 in the form of
-a shared library (or libraries). These are made known to BIND 10
-through its configuration mechanism, and BIND 10 loads the library at
+In order to minimise the interaction between Kea and the user
+code, the latter is built independently of Kea in the form of
+a shared library (or libraries). These are made known to Kea
+through its configuration mechanism, and Kea loads the library at
run time. Libraries can be unloaded and reloaded as needed while BIND
10 is running.
-Use of a defined API and the BIND 10 configuration mechanism means that
-as new versions of BIND 10 are released, there is no need to modify
+Use of a defined API and the Kea configuration mechanism means that
+as new versions of Kea are released, there is no need to modify
the user code. Unless there is a major change in an interface
(which will be clearly documented), all that will be required is a rebuild
of the libraries.
@note Although the defined interface should not change, the internals
of some of the classes and structures referenced by the user code may
-change between versions of BIND 10. These changes have to be reflected
+change between versions of Kea. These changes have to be reflected
in the compiled version of the software, hence the need for a rebuild.
@subsection hooksdgLanguages Languages
-The core of BIND 10 is written in C++. While it is the intention to
+The core of Kea is written in C++. While it is the intention to
provide interfaces into user code written in other languages, the initial
versions of the Hooks system requires that user code be written in C++.
All examples in this guide are in that language.
- Framework function - the functions that a user library needs to
supply in order for the hooks framework to load and unload the library.
-- User code/user library - non-BIND 10 code that is compiled into a
-shared library and loaded by BIND 10 into its address space.
+- User code/user library - non-Kea code that is compiled into a
+shared library and loaded by Kea into its address space.
@section hooksdgTutorial Tutorial
-To illustrate how to write code that integrates with BIND 10, we will
+To illustrate how to write code that integrates with Kea, we will
use the following (rather contrived) example:
-The BIND 10 DHCPv4 server is used to allocate IPv4 addresses to clients
+The Kea DHCPv4 server is used to allocate IPv4 addresses to clients
(as well as to pass them other information such as the address of DNS
servers). We will suppose that we need to classify clients requesting
IPv4 addresses according to their hardware address, and want to log both
Loading and initializing a library holding user code makes use
of three (user-supplied) functions:
-- version - defines the version of BIND 10 code with which the user-library
+- version - defines the version of Kea code with which the user-library
is built
- load - called when the library is loaded by the server.
- unload - called when the library is unloaded by the server.
@subsubsection hooksdgVersionFunction The "version" Function
"version" is used by the hooks framework to check that the libraries
-it is loading are compatible with the version of BIND 10 being run.
-Although the hooks system allows BIND 10 and user code to interface
+it is loading are compatible with the version of Kea being run.
+Although the hooks system allows Kea and user code to interface
through a defined API, the relationship is somewhat tight in that the
-user code will depend on the internal structures of BIND 10. If these
-change - as they can between BIND 10 releases - and BIND 10 is run with
-a version of user code built against an earlier version of BIND
-10, a program crash could result.
+user code will depend on the internal structures of Kea. If these
+change - as they can between Kea releases - and Kea is run with
+a version of user code built against an earlier version of Kea, program
+crash could result.
To guard against this, the "version" function must be provided in every
library. It returns a constant defined in header files of the version
-of BIND 10 against which it was built. The hooks framework checks this
-for compatibility with the running version of BIND 10 before loading
+of Kea against which it was built. The hooks framework checks this
+for compatibility with the running version of Kea before loading
the library.
In this tutorial, we'll put "version" in its own file, version.cc. The
}
@endcode
-The file "hooks/hooks.h" is specified relative to the BIND 10 libraries
+The file "hooks/hooks.h" is specified relative to the Kea libraries
source directory - this is covered later in the section @ref hooksdgBuild.
-It defines the symbol BIND10_HOOKS_VERSION, which has a value that changes
-on every release of BIND 10: this is the value that needs to be returned
+It defines the symbol KEA_HOOKS_VERSION, which has a value that changes
+on every release of Kea: this is the value that needs to be returned
to the hooks framework.
A final point to note is that the definition of "version" is enclosed
this is covered further in the section @ref hooksdgCalloutRegistration.
The example does not make any use callouts with non-standard names. However,
-as our design requires that the log file be open while BIND 10 is active
+as our design requires that the log file be open while Kea is active
and the library loaded, we'll open the file in the "load" function and close
it in "unload".
- "unload" closes the log file if it is open and is a no-op otherwise. As
with "load", a zero value must be returned on success and a non-zero value
on an error. The hooks framework will record a non-zero status return
-as an error in the current BIND 10 log but otherwise ignore it.
+as an error in the current Kea log but otherwise ignore it.
- As before, the function definitions are enclosed in 'extern "C"' braces.
@subsection hooksdgCallouts Callouts
Having sorted out the framework, we now come to the functions that
actually do something. These functions are known as "callouts" because
-the BIND 10 code "calls out" to them. Each BIND 10 server has a number of
+the Kea code "calls out" to them. Each Kea server has a number of
hooks to which callouts can be attached: server-specific documentation
describes in detail the points in the server at which the hooks are
present together with the data passed to callouts attached to them.
@endcode
(As before, the callout is declared with "C" linkage.) Information is passed
-between BIND 10 and the callout through name/value pairs in the CalloutHandle
+between Kea and the callout through name/value pairs in the CalloutHandle
object. The object is also used to pass information between callouts on a
per-request basis. (Both of these concepts are explained below.)
and error code is that if the latter is returned, the server will
log an error, specifying both the library and hook that generated it.
Effectively the return status provides a quick way for a callout to log
-error information to the BIND 10 logging system.
+error information to the Kea logging system.
@subsubsection hooksdgArguments Callout Arguments
@subsubsection hooksdgCalloutContext Per-Request Context
-Although many of the BIND 10 modules can be characterised as handling
+Although many of the Kea modules can be characterised as handling
singles packet - e.g. the DHCPv4 server receives a DISCOVER packet,
processes it and responds with an OFFER, this is not true in all cases.
The principal exception is the recursive DNS resolver: this receives a
the the code be compiled as positition-independent code (using the
compiler's "-fpic" switch) and linked as a shared library (with the
linker's "-shared" switch). The build command also needs to point to
-the BIND 10 include directory and link in the appropriate libraries.
+the Kea include directory and link in the appropriate libraries.
-Assuming that BIND 10 has been installed in the default location, the
+Assuming that Kea has been installed in the default location, the
command line needed to create the library using the Gnu C++ compiler on a
Linux system is:
@code
-g++ -I /usr/include/bind10 -L /usr/lib/bind10/lib -fpic -shared -o example.so \
+g++ -I /usr/include/kea -L /usr/lib/kea/lib -fpic -shared -o example.so \
load_unload.cc pkt4_receive.cc pkt4_send.cc version.cc \
- -lb10-dhcpsrv -lb10-dhcp++ -lb10-hooks -lb10-log -lb10-util -lb10-exceptions
+ -lkea-dhcpsrv -lkea-dhcp++ -lkea-hooks -lkea-log -lkea-util -lkea-exceptions
@endcode
Notes:
your operating system and compiler - consult the relevant documentation
for details.
- The values for the "-I" and "-L" switches depend on where you have
-installed BIND 10.
+installed Kea.
- The list of libraries that need to be included in the command line
depends on the functionality used by the hook code and the module to
which they are attached (e.g. hook code for DNS will need to link against
the libkea-dns++ library). Depending on operating system, you may also need
-to explicitly list libraries on which the BIND 10 libraries depend.
+to explicitly list libraries on which the Kea libraries depend.
@subsection hooksdgConfiguration Configuring the Hook Library
-The final step is to make the library known to BIND 10. All BIND 10 modules to
+The final step is to make the library known to Kea. All Kea modules to
which hooks can be added contain the "hook_library" element, and user
-libraries are added to this. (The BIND 10 hooks system can handle multiple libraries - this is discussed below.).
+libraries are added to this. (The Kea hooks system can handle multiple libraries
+- this is discussed below.).
To add the example library (assumed to be in /usr/local/lib) to the DHCPv4
module, the following bindctl commands must be executed:
request is received.
@note The above assumes that the hooks library will be used with a version of
-BIND 10 that is dynamically-linked. For information regarding running
-hooks libraries against a statically-linked BIND 10, see
-@ref hooksdgStaticallyLinkedBind10.
+Kea that is dynamically-linked. For information regarding running
+hooks libraries against a statically-linked Kea, see
+@ref hooksdgStaticallyLinkedKea.
@section hooksdgAdvancedTopics Advanced Topics
@subsubsection hooksdgMultipleCallouts Multiple Callouts on a Hook
-The BIND 10 hooks framework allows multiple callouts to be attached to
+The Kea hooks framework allows multiple callouts to be attached to
a hook point. Although it is likely to be rare for user code to need to
do this, there may be instances where it make sense.
@subsection hooksdgMultipleLibraries Multiple User Libraries
-As alluded to in the section @ref hooksdgConfiguration, BIND 10 can load
+As alluded to in the section @ref hooksdgConfiguration, Kea can load
multiple libraries. The libraries are loaded in the order specified in
the configuration, and the callouts attached to the hooks in the order
presented by the libraries.
would be able to read this, but would not be able to return information
back to "add_option".
-All argument names used by BIND 10 will be a combination of letters
+All argument names used by Kea will be a combination of letters
(both upper- and lower-case), digits, hyphens and underscores: no
other characters will be used. As argument names are simple strings,
it is suggested that if such a mechanism be used, the names of the data
values passed between the libraries include a special character such as
the dollar symbol or percent sign. In this way there is no danger that
-a name will conflict with any existing or future BIND 10 argument names.
+a name will conflict with any existing or future Kea argument names.
@subsection hooksdgRegisterMultipleLibraries Dynamic Callout Registration and Multiple Libraries
"logpkt" that registered the new callout, "double_check" would appear
after "validate".
-@subsection hooksdgStaticallyLinkedBind10 Running Against a Statically-Linked BIND 10
+@subsection hooksdgStaticallyLinkedKea Running Against a Statically-Linked Kea
-If BIND 10 is built with the --enable-static-link switch (set when
-running the "configure" script), no shared BIND 10 libraries are built;
-instead, archive libraries are created and BIND 10 is linked to them.
+If Kea is built with the --enable-static-link switch (set when
+running the "configure" script), no shared Kea libraries are built;
+instead, archive libraries are created and Kea is linked to them.
If you create a hooks library also linked against these archive libraries,
when the library is loaded you end up with two copies of the library code,
-one in BIND 10 and one in your library.
+one in Kea and one in your library.
To run successfully, your library needs to perform run-time initialization
-of the BIND 10 code in your library (something performed by BIND 10
+of the Kea code in your library (something performed by Kea
in the case of shared libraries). To do this, call the function
isc::hooks::hooksStaticLinkInit() as the first statement of the load()
function. (If your library does not include a load() function, you need
// and is used to prevent a clash with symbols in any other Doxygen file.
/**
-@page logBind10Logging BIND 10 Logging
+@page logKeaLogging Kea Logging
@section logBasicIdeas Basic Ideas
-The BIND 10 logging system is based on the log4J logging system
+The Kea logging system is based on the log4J logging system
common in Java development, and includes the following ideas:
- A set of severity levels.
- Separation of message use from message text.
@subsection logSeverity Message Severity
-Each message logged by BIND 10 has a severity associated with it, ranging
+Each message logged by Kea has a severity associated with it, ranging
from FATAL - the most severe - to DEBUG - messages output as the code
executes to facilitate debugging. In order of decreasing severity,
the levels are:
logger. The top of the hierarchy is the root logger; this does not
have a parent. The reason for this hierarchy is that unless a logger
explicitly assigns a value to an attribute (such as severity of messages
-it should log), it picks it up the value from the parent. In BIND 10,
-each component (b10-auth, b10-resolver etc.) has a root logger (named
+it should log), it picks it up the value from the parent. In Kea,
+each component (b10-dhcp4, b10-dhcp-ddns etc.) has a root logger (named
after the program) and every other logger in the component is a child
of that. So in the example above, the error/syslog attributes could be
associated with the b10-resolver logger while the logger associated with
More information about the logging hierarchy can be found in the section
on Logging configuration in the <a
-href="http://bind10.isc.org/docs/bind10-guide.html#logging">BIND 10
-Guide</a>.
+href="http://kea.isc.org/docs/kea-guide.html#logging">Kea Administrator
+Reference Manual</a>.
@subsection logSeparationUseText Separation of Messages Use from Message Text
substitutes any message parameters (in this example, the name of the file
where the write operation failed) and logs the result to the destination.
-In BIND 10, a the default text for each message is linked into the
+In Kea, a the default text for each message is linked into the
program. Each program is able to read a locally-defined message file
when it starts, updating the stored definitions with site-specific text.
When the message is logged, the updated text is output. However, the
message identifier is always included in the output so that the origin
of the message can be identified even if the text has been changed.
-@note Local message files have not yet been implemented in BIND 10.
+@note Local message files have not yet been implemented in Kea.
-@section logDeveloperUse Using Logging in a BIND 10 Component
+@section logDeveloperUse Using Logging in a Kea Component
-The steps in using the logging system in a BIND 10 component (such as
+The steps in using the logging system in a Kea component (such as
an executable or library) are:
<ol>
<li>Run it through the message compiler to produce the files for your
module. This step should be included in the build process. The message
-compiler is a BIND10 program and is one of the first programs built and
+compiler is a Kea program and is one of the first programs built and
linked in the build process. As a result, it should be available for
-compiling the message files of all BIND 10 components and libraries.
+compiling the message files of all Kea components and libraries.
For C++ development, the message compiler produces two files in the
default directory, having the same name as the input file but with file
@subsection logMessageFiles Create a Message File
A message file contains message definitions. Typically there
-will be one message file for each component that uses BIND 10 logging.
+will be one message file for each component that uses Kea logging.
An example file could be:
@code
</ul>
Although there are few restriction on what can be in the message
-identifcation and text, there are a number of conventions used by BIND
-10, both in the contents of the message and in the usage. All code
+identifcation and text, there are a number of conventions used by Kea,
+both in the contents of the message and in the usage. All code
should adhere to these:
<ul>
across multiple lines makes it awkward to search the file for messages
and associated information.</li>
-<li>The message identifier should be unique across the entire BIND 10
+<li>The message identifier should be unique across the entire Kea
system. (An error will be reported at system start-up if an identifier
is repeated.)</li>
<li>A particular message identifier should only be used at one place in
-the BIND 10 code. In this way, if the message indicates a problem, the
+the Kea code. In this way, if the message indicates a problem, the
code in question can be quickly identified.</li>
<li>The explanation of the message - the free-form text following the
-message identification - appears in the BIND 10 message manual. It
+message identification - appears in the Kea message manual. It
should:
<ul>
@subsection logSourceFiles Produce Source Files
The message file created in the previous step is then run through the
-message compiler to produce source files that are included in the BIND
-10 programs.
+message compiler to produce source files that are included in the Kea
+programs.
@subsubsection logMessageCompiler Message Compiler
The message compiler is a program built in the src/log/compiler directory.
The source file for the messages is the ".mes" file, but the files used
by the code (which, in the case of C++, must be compiled and linked)
are the output of the message compiler. (The compiler is produced very
-early on in the BIND 10 build sequence, so is available for use in the
+early on in the Kea build sequence, so is available for use in the
building of subsequent components.) To allow this, certain dependencies
must be included in the Makefile.am for each component that uses logging.
<dl>
<dt>B10_LOGGER_ROOT</dt>
-<dd>Sets the "root" for the unit test. If not defined, the name "bind10"
+<dd>Sets the "root" for the unit test. If not defined, the name "kea"
is used.</dd>
<dt>B10_LOGGER_SEVERITY</dt>
projects / thirdparty / kea.git / commitdiff
