Commit 0a00f963 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰

[master] Merge branch 'trac3396' (Developer's Guide update)

Conflicts:
	ChangeLog
	src/bin/dhcp4/dhcp4.dox
	src/bin/dhcp6/dhcp6.dox
	src/hooks/dhcp/user_chk/libdhcp_user_chk.dox
parents 909bf558 271450ed
802. [doc] tomek, marcin
Developer's Guide updated to Change BIND 10 references to Kea.
Documentation for Keactl added.
(Trac #3396, git 271450edbc63e9022f877c9aa3d1dc290708f151)
(Trac #3466, git fa9570d19c73cbe7effc75589b7eb855c411f6a3)
801. [build] fdupont
Detect all OS X versions more recent than 10.9 (where
pthread_cond_destroy() doesn't work as documented,
......
......@@ -33,7 +33,7 @@ maintain their own backends.
@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)
......@@ -51,62 +51,78 @@ developed and maintained by other organizations.
@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 to 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 the other
components: DHCPv6 or DHCP-DDNS):
-# Write your own implementation of isc::dhcp::ControlledDhcpv4Srv::init(),
isc::dhcp::ControlledDhcpv4Srv::init() and isc::dhcp::ControlledDhcpv4Srv::cleanup()
and put it in the src/bin/dhcp4 directory (e.g. as foo_controller.cc).
-# Modify src/bin/dhcp4/Makefile.am to include your file (e.g. foo_controller.cc) in
the build.
-# Modify the AC_ARG_WITH(kea-config,...) macro in configure.ac to include an
entry for your configuration backend.
-# Add your own AM_CONDITIONAL(CONFIG_BACKEND_FOO, ...) and
AC_DEFINE(CONFIG_BACKEND_FOO, ...) macros to configure.ac (following the
above-mentioned AC_ARG_WITH macro) to set the C++ macro for your backend.
-# Modify the sanity check in configure.ac to allow your configuration backend name.
Optionally you can also:
-# Implement unit tests for your backend in the src/bin/dhcp4/tests directory.
-# Modify src/bin/dhcp4/tests/Makefile.am to include the file(s) containing the
unit tests.
@section configBackendJSONDesign The JSON Configuration Backend
The following are some considerations that shaped the design of the configuration
backend framework.
-# 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).
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
(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/>
This switchable backend concept is quite simple. There are just different
implementations of ControlledXSrv class, so it is a matter of compiling/linking
The following are some details of the JSON backend framework.
-# A switch called --with-kea-config has been implemented in the
configure script. It allows the selection at compilation time of how the
servers will be configured. Currently (June 2014),
there are two values: JSON (the default, read configuration from a JSON file)
and BUNDY (use the BUNDY/BIND10 framework). Although the Bundy/BIND10
framework has been removed from Kea, the configuration choice
is available for other projects (e.g. Bundy) that want to include an
implementation of Kea using that backend. Such projects are advised to
import the Kea modules and compile them with the Bundy backend
enabled.<br/><br/>
This switchable backend concept is quite simple. There are different
implementations of ControlledXSrv class, each backend keeping its code
in a separate file. 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/>
-# A way is needed to initialize stand-alone logging (i.e. each
Kea component will initialize it on its own).<br/><br/>
-# 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/>
external projects, like Bundy, to keep it if they desire). It is also easy
for other organizations to add and maintain their own backends (e.g. LDAP).<br/><br/>
-# Each backend uses 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/>
-# A command handler handles the 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.
This is implemented in configure() in the kea_controller.cc files
in src/bin/dhcp4 and src/bin/dhcp6 directories.<br/><br/>
-# The current JSON parser in @ref
isc::data::Element::fromJSON() has been extended to allow optional
preprocessing. For now, that capability simply removes whole-line
comments starting with the hash character, but it is expected to grow over
time (in-line comments and file inclusions are the obvious envisaged
additions). This is implemented in @ref isc::data::Element::fromJSONFile.<br/><br/>
-# The current format of the BIND10 configuration file (BIND 10 stored its
configuration in (installation directory) /var/bind10/b10-config.db) has been
retained as the configuration file format. Its actual naming is now arbitrary
and left up to the user (it is passed as a parameter to the -c command line
option). From the implementation perspective, this is slight change
from the BIND10 days, as back then a subset of the configuration was received by
the daemon processes. Nowadays the whole configuration is pased. To take a
specific example, the following is how b10-config.db looks today:
@code
{
"Init": { ... }
......@@ -127,30 +143,39 @@ backend framework.
}
}
@endcode
<br/>
The Kea components used to receive only relevant parts of it (e.g. Kea4
received config that contained content of the Dhcp4 element). Now they
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/>
received configuration data that only contained the content of the Dhcp4 element).
Now each component receives all of it: the code
iterates over the top level elements and picks the appropriate
tree (or get the element by name). That approach makes the common configuration
(such as the logging initialization code) very easy to share among Kea4, Kea6 and
DHCP-DDNS.<br/><br/>
-# 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,
have been retained. They will be kept and maintained even though no use of
them is currently planned. At some future time syntax validation may be implemented,
although it is out of scope for Kea 0.9 (and probably
for 1.0 as it is pretty big task).<br/><br/>
-# Addition of a shell script to start/stop Kea4,Kea6 and D2. There will be a script that will
for 1.0 as well, as it is a pretty big task).<br/><br/>
-# A shell script has been added (as src/bin/keactrl/keactrl) to
start, stop and reconfigure the daemons. Its only
job will be to pass the configuration file to each daemon and remember its PID file, so
that sending signals will be be possible (for configuration reload or shutdown). Optionally,
it could also print out a status based on PID, but that may be tricky to
implement in a portable way. The minimum set of commands will be:
-# Start the processes
- eventually based on configuration, initially start them all
- it could launch a nanny script which restarts them on a crash (past 0.9)
-# Prompt the processes to reload configuration
- for now it will be a matter of sending singal to the right process
- this could also decide if D2 should still be running or not, and react accordingly (post 0.9)
-# Stop the processes in an orderly fashion
-# Perhaps return status of each process
job is to pass the configuration file to each daemon and remember its PID file, so
that sending signals is possible (for configuration reload or shutdown). It is also
able to print out a status.
Future changes planned for this part of the code are:
-# 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. This has been implemented in @ref isc::dhcp::Daemon.<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. 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".
*/
......@@ -14,72 +14,79 @@
/**
@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.
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
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
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). The kea-users list
is intended for users who are not interested in the internal workings
or development details of Kea: 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 discussed on kea-dev and not posted
to 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.
The first step in writing the patch or new feature should be to get
the source code from our Git repository. The procedure is very easy and
is explained here: 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
it. You have surely checked that it compiles on your system, but Kea
is 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
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
Does your patch conform to Kea coding guidelines
(http://kea.isc.org/wiki/CodingGuidelines)? You can submit a
patch that does not adhere to them, but that will reduce its chances of
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
change. That is even more true for new code. If you write a new
like a single line fix, you are encouraged to write unit-tests for that
change. That is even more true for new code: if you write a new
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
......@@ -113,10 +120,11 @@ checks on logger parameters. Use \c --enable-debug to enable various
additional consistency checks that reduce performance but help during
development. If you happen to modify anything in the
documentation, use \c --enable-generate-docs. If you are modifying DHCP
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:
code, you are likely to be interested in enabling a database backend for
DHCP. Note that if the backend is not enabled, the database-specific unit-tests
are skipped. To enable the MySQL backend, use the switch
\c --with-dhcp-mysql; for PostgreSQL, use \c --with-dhcp-pgsql.
A complete list of all switches can be obtained with the command:
@code
./configure --help
......@@ -124,23 +132,25 @@ are skipped. From that perspective, it is useful to use
@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
Once everything is checked and working, feel free to create a ticket for
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
contributions very much and will do whatever we can to review patches in
a timely manner. Don't get discouraged if your patch is not accepted
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
review processes for external patches as we do for internal code. 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: even
the Kea developers 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
......@@ -152,13 +162,14 @@ critical for whatever reason, it may also be mentioned in release notes.
@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),
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.
*/
......@@ -17,7 +17,7 @@
*
* 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
......@@ -31,7 +31,7 @@
* 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>
......@@ -98,7 +98,7 @@
* - @subpage libdhcp_ddns
*
* @section miscellaneousTopics Miscellaneous Topics
* - @subpage logBind10Logging
* - @subpage logKeaLogging
* - @subpage logBasicIdeas
* - @subpage logDeveloperUse
* - @subpage logNotes
......
......@@ -15,7 +15,7 @@
/**
@page dhcp4 DHCPv4 Server Component
BIND10 offers DHCPv4 server implementation. It is implemented as
Kea offers DHCPv4 server implementation. It is implemented as
kea-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
......@@ -29,9 +29,12 @@ DHCPv4 server component does not support direct traffic (relayed
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
......@@ -194,7 +197,7 @@ limited.
@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
......@@ -205,7 +208,7 @@ There is a new parameter for configure script: --with-kea-config. It currently s
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
......
......@@ -16,10 +16,10 @@
@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
......
......@@ -15,7 +15,7 @@
/**
@page dhcp6 DHCPv6 Server Component
BIND10 offers DHCPv6 server implementation. It is implemented as
Kea offers DHCPv6 server implementation. It is implemented as
kea-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
......@@ -28,20 +28,21 @@
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
kea-dhcp6 component uses BIND10 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().
kea-dhcp6 compiled with Bundy backend uses Bundy cfgmgr for commands and
configuration. During initial configuration (See \ref
isc::dhcp::ControlledDhcpv6Srv::init() in bundy_controller.cc), the configuration handler
callback is installed (see bundyConfigHandler().
It is called every time there is a new configuration. In particular, it is
called every time during daemon start process. It contains a
isc::data::ConstElementPtr to a new configuration. This simple handler calls
......@@ -108,7 +109,7 @@ The kea-dhcp-ddns process is responsible for the actual communication with the D
server, i.e. to send DNS Update messages. The kea-dhcp6 module is responsible
for generating so called @ref isc::dhcp_ddns::NameChangeRequest and sending it to the
kea-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 kea-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.
......@@ -119,7 +120,7 @@ a code which will check if there are any outstanding requests in the queue and
send them to the kea-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.
......@@ -226,7 +227,7 @@ limited.
@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
......@@ -237,7 +238,7 @@ There is a new parameter for configure script: --with-kea-config. It currently s
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
......
......@@ -16,10 +16,10 @@
@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
......
......@@ -20,7 +20,8 @@
libdhcp_user_chk is an example hooks library which customizes the DHCP query
processing provided by Kea DHCP server modules (kea-dhcp4 and kea-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"
......@@ -29,7 +30,8 @@ or "registered" users are assigned to unrestricted subnets.
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,
......@@ -88,7 +90,7 @@ flow upon receipt of an inbound request is the same and is as follows:
## 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
......@@ -124,36 +126,46 @@ Upon start up the library will attempt to load this file. If it does not exist
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 kea-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 kea-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 kea-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:
......
......@@ -67,8 +67,6 @@ extern "C" {
/// 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.
......
......@@ -12,7 +12,7 @@
// 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.