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 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:
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") Kea will make a call to this code. The call passes data that the user code can examine and, if required, modify. Kea uses the modified data in the remainder of its processing.
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 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.
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.
In the remainder of this guide, the following terminology is used:
To illustrate how to write code that integrates with Kea, we will use the following (rather contrived) example:
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 the hardware address and allocated IP address for the clients of interest.
The following sections describe how to implement these requirements. The code presented here is not efficient and there are better ways of doing the task. The aim however, is to illustrate the main features of user hook code not to provide an optimal solution.
Loading and initializing a library holding user code makes use of three (user-supplied) functions:
Of these, only "version" is mandatory, although in our example, all three are used.
"version" is used by the hooks framework to check that the libraries 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 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, a 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 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 contents are:
The file "hooks/hooks.h" is specified relative to the Kea libraries source directory - this is covered later in the section Building the Library. 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 within 'extern "C"' braces. All functions accessed by the hooks framework use C linkage, mainly to avoid the name mangling that accompanies use of the C++ compiler, but also to avoid issues related to namespaces.
As the names suggest, "load" is called when a library is loaded and "unload" called when it is unloaded. (It is always guaranteed that "load" is called: "unload" may not be called in some circumstances, e.g. if the system shuts down abnormally.) These functions are the places where any library-wide resources are allocated and deallocated. "load" is also the place where any callouts with non-standard names (names that are not hook point names) can be registered: this is covered further in the section Registering Callouts.
The example does not make any use callouts with non-standard names. However, 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".
We create two files, one for the file handle declaration:
... and one to hold the "load" and "unload" functions:
Having sorted out the framework, we now come to the functions that actually do something. These functions are known as "callouts" because 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.
Before we continue with the example, we'll discuss how arguments are passed to callouts and information is returned to the server. We will also discuss how information can be moved between callouts.
All callouts are declared with the signature:
(As before, the callout is declared with "C" linkage.) Information is passed 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.)
A callout returns an "int" as a status return. A value of 0 indicates success, anything else signifies an error. The status return has no effect on server processing; the only difference between a success 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 Kea logging system.
The CalloutHandle object provides two methods to get and set the arguments passed to the callout. These methods are called (naturally enough) getArgument and SetArgument. Their usage is illustrated by the following code snippets.
In the callout
As can be seen "getArgument" is used to retrieve data from the CalloutHandle, and setArgument used to put data into it. If a callout wishes to alter data and pass it back to the server, it should retrieve the data with getArgument, modify it, and call setArgument to send it back.
There are several points to be aware of:
In all cases, consult the documentation for the particular hook to see whether parameters can be modified. As a general rule:
When a to callouts attached to a hook returns, the server will usually continue its processing. However, a callout might have done something that means that the server should follow another path. Possible actions a server could take include:
To handle these common cases, the CalloutHandle has a "skip" flag. This is set by a callout when it wishes the server to skip normal processing. It is set false by the hooks framework before callouts on a hook are called. If the flag is set on return, the server will take the "skip" action relevant for the hook.
The methods to get and set the "skip" flag are getSkip and setSkip. Their usage is intuitive:
Like arguments, the "skip" flag is passed to all callouts on a hook. Callouts later in the list are able to examine (and modify) the settings of earlier ones.
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 packet from a client but that packet may itself generate multiple packets being sent to upstream servers. To avoid possible confusion the rest of this section uses the term "request" to indicate a request by a client for some information or action.
As well as argument information, the CalloutHandle object can be used by callouts to attach information to a request being handled by the server. This information (known as "context") is not used by the server: its purpose is to allow callouts to pass information between one another on a per-request basis.
Context only exists only for the duration of the request: when a request is completed, the context is destroyed. A new request starts with no context information. Context is particularly useful in servers that may be processing multiple requests simultaneously: callouts can effectively attach data to a request that follows the request around the system.
Context information is held as name/value pairs in the same way as arguments, being accessed by the pair of methods setContext and getContext. They have the same restrictions as the setArgument and getArgument methods - the type of data retrieved from context must exactly match the type of the data set.
The example in the next section illustrates their use.
Continuing with the tutorial, the requirements need us to retrieve the hardware address of the incoming packet, classify it, and write it, together with the assigned IP address, to a log file. Although we could do this in one callout, for this example we'll use two:
The standard for naming callouts is to give them the same name as the hook. If this is done, the callouts will be automatically found by the Hooks system (this is discussed further in section Registering Callouts). For our example, we will assume this is the case, so the code for the first callout (used to classify the client's hardware address) is:
The pkt4_receive callout placed the hardware address of an interesting client in the "hwaddr" context for the packet. Turning now to the callout that will write this information to the log file:
Building the code requires building a shareable library. This requires 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 Kea include directory and link in the appropriate libraries.
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:
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 Kea hooks system can handle multiple libraries
To add the example library (assumed to be in /usr/local/lib) to the DHCPv4 module, the following bindctl commands must be executed:
The DHCPv4 server will load the library and execute the callouts each time a request is received.
As well as the hooks defined by the server, the hooks framework defines two hooks of its own, "context_create" and "context_destroy". The first is called when a request is created in the server, before any of the server-specific hooks gets called. It's purpose it to allow a library to initialize per-request context. The second is called after all server-defined hooks have been processed, and is to allow a library to tidy up.
As an example, the pkt4_send example above required that the code check for an exception being thrown when accessing the "hwaddr" context item in case it was not set. An alternative strategy would have been to provide a callout for the "context_create" hook and set the context item "hwaddr" to an empty string. Instead of needing to handle an exception, pkt4_send would be guaranteed to get something when looking for the hwaddr item and so could write or not write the output depending on the value.
In most cases, "context_destroy" is not needed as the Hooks system automatically deletes context. An example where it could be required is where memory has been allocated by a callout during the processing of a request and a raw pointer to it stored in the context object. On destruction of the context, that memory will not be automatically released. Freeing in the memory in the "context_destroy callout will solve that problem.
Actually, when the context is destroyed, the destructor associated with any objects stored in it are run. Rather than point to allocated memory with a raw pointer, a better idea would be to point to it with a boost "smart" pointer and store that pointer in the context. When the context is destroyed, the smart pointer's destructor is run, which will automatically delete the pointed-to object.
These approaches are illustrated in the following examples. Here it is assumed that the hooks library is performing some form of security checking on the packet and needs to maintain information in a user-specified "SecurityInformation" object. (The details of this fictitious object are of no concern here.) The object is created in the context_create callout and used in both the pkt4_receive and the pkt4_send callouts.
The requirement for the context_destroy callout can be eliminated if a Boost shared ptr is used to point to the allocated memory:
(Note that a Boost shared pointer - rather than any other Boost smart pointer - should be used, as the pointer objects are copied within the hooks framework and only shared pointers have the correct behavior for the copy operation.)
As briefly mentioned in Example Callouts, the standard is for callouts in the user library to have the same name as the name of the hook to which they are being attached. This convention was followed in the tutorial, e.g. the callout that needed to be attached to the "pkt4_receive" hook was named pkt4_receive.
The reason for this convention is that when the library is loaded, the hook framework automatically searches the library for functions with the same names as the server hooks. When it finds one, it attaches it to the appropriate hook point. This simplifies the loading process and bookkeeping required to create a library of callouts.
However, the hooks system is flexible in this area: callouts can have non-standard names, and multiple callouts can be registered on a hook.
The way into the part of the hooks framework that allows callout registration is through the LibraryHandle object. This was briefly introduced in the discussion of the framework functions, in that an object of this type is pass to the "load" function. A LibraryHandle can also be obtained from within a callout by calling the CalloutHandle's getLibraryHandle() method.
The LibraryHandle provides three methods to manipulate callouts:
The following sections cover some of the ways in which these can be used.
The example in the tutorial used standard names for the callouts. As noted above, it is possible to use non-standard names. Suppose, instead of the callout names "pkt4_receive" and "pkt4_send", we had named our callouts "classify" and "write_data". The hooks framework would not have registered these callouts, so we would have needed to do it ourself. The place to do this is the "load" framework function, and its code would have had to been modified to:
It is possible for a library to contain callouts with both standard and non-standard names: ones with standard names will be registered automatically, ones with non-standard names need to be registered manually.
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.
To register multiple callouts on a hook, just call LibraryHandle::registerCallout multiple times on the same hook, e.g.
The hooks framework will call the callouts in the order they are registered. The same CalloutHandle is passed between them, so any change made to the CalloutHandle's arguments, "skip" flag, or per-request context by the first is visible to the second.
The previous sections have dealt with callouts being registered during the call to "load". The hooks framework is more flexible than that in that callouts can be registered and deregistered within a callout. In fact, a callout is able to register or deregister itself, and a callout is able to be registered on a hook multiple times.
Using our contrived example again, the DHCPv4 server processes one request to completion before it starts processing the next. With this knowledge, we could alter the logic of the code so that the callout attached to the "pkt4_receive" hook registers the callout doing the logging when it detects an interesting packet, and the callout doing the logging deregisters itself in its execution. The relevant modifications to the code in the tutorial are shown below:
Note that the above example used a non-standard name for the callout that wrote the data. Had the name been a standard one, it would have been registered when the library was loaded and called for the first request, regardless of whether that was defined as "interesting". (Although as callouts with standard names are always registered before "load" gets called, we could have got round that problem by deregistering that particular callout in the "load" function.)
As alluded to in the section Configuring the Hook Library, 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.
The following picture illustrates this, and also illustrates the scope of data passed around the system.
In this illustration, a server has three hook points, alpha, beta and gamma. Two libraries are configured, library 1 and library 2. Library 1 registers the callout "authorize" for hook alpha, "check" for hook beta and "add_option" for hook gamma. Library 2 registers "logpkt", "validate" and "putopt"
The horizontal red lines represent arguments to callouts. When the server calls hook alpha, it creates an argument list and calls the first callout for the hook, "authorize". When that callout returns, the same (but possibly modified) argument list is passed to the next callout in the chain, "logpkt". Another, separate argument list is created for hook beta and passed to the callouts "check" and "validate" in that order. A similar sequence occurs for hook gamma.
The next picture shows the scope of the context associated with a request.
The vertical blue lines represent callout context. Context is per-packet but also per-library. When the server calls "authorize", the CalloutHandle's getContext and setContext methods access a context created purely for library 1. The next callout on the hook will access context created for library 2. These contexts are passed to the callouts associated with the next hook. So when "check" is called, it gets the context data that was set by "authorize", when "validate" is called, it gets the context data set by "logpkt".
It is stressed that the context for callouts associated with different libraries is entirely separate. For example, suppose "authorize" sets the CalloutHandle's context item "foo" to 2 and "logpkt" sets an item of the same name to the string "bar". When "check" accesses the context item "foo", it gets a value of 2; when "validate" accesses an item of the same name, it gets the value "bar".
It is also stressed that all this context exists only for the life of the request being processed. When that request is complete, all the context associated with that request - for all libraries - is destroyed, and new context created for the next request.
This structure means that library authors can use per-request context without worrying about the presence of other libraries. Other libraries may be present, but will not affect the context values set by a library's callouts.
In rare cases, it is possible that one library may want to pass data to another. This can be done in a limited way by means of the CalloutHandle's setArgument and getArgument calls. For example, in the above diagram, the callout "add_option" can pass a value to "putopt" by setting a name.value pair in the hook's argument list. "putopt" would be able to read this, but would not be able to return information back to "add_option".
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 Kea argument names.
On a particular hook, callouts are called in the order the libraries appear in the configuration and, within a library, in the order the callouts are registered.
This order applies to dynamically-registered callouts as well. As an example, consider the diagram above where for hook "beta", callout "check" is followed by callout "validate". Suppose that when "authorize" is run, it registers a new callout ("double_check") on hook "beta". That callout will be inserted at the end of the callouts registered by library 1 and before any registered by library 2. It would therefore appear between "check" and "validate". On the other hand, if it were "logpkt" that registered the new callout, "double_check" would appear after "validate".
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 Kea and one in your library.
To run successfully, your library needs to perform run-time initialization 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 to add one.) For example: