--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY mdash "—" >
+]>
+
+ <chapter id="hooks-libraries">
+ <title>Hooks Libraries</title>
+ <section id="hooks-libraries-introduction">
+ <title>Introduction</title>
+ <para>
+ Although Kea offers a lot of flexibility, there may be cases where
+ its behavior needs customisation. To accommodate this possibility,
+ Kea includes the idea of "Hooks". This feature lets Kea load one
+ or more dynamically-linked libraries (known as "hooks libraries")
+ and, at various points in its processing ("hook points"), call
+ functions in them. Those functions perform whatever custom
+ processing is required.
+ </para>
+ <para>
+ Hooks libraries are attached to individual Kea processes, not to
+ Kea as a whole. This means (for example) that it is possible
+ to associate one set of libraries with the DHCP4 server and a
+ different set to the DHCP6 server.
+ </para>
+ <para>
+ Another point to note is that it is possible for a process to
+ load multiple libraries. At every hook point, Kea calls all
+ hooks library functions attached it. If multiple libraries have
+ attached a function to a given hook point, Kea calls all of them.
+ The order in which the functions are called is the order in which
+ the libraries are specified in the configuration file. This may
+ be important: consult the documentation of the libraries to see
+ if this is the case.
+ </para>
+ <para>
+ The next section describes how to configure hooks libraries. If you
+ are interested in writing your own hooks library, information can be
+ found in the <ulink url="http://git.kea.isc.org/~tester/kea/doxygen">Kea
+ Developer's Guide</ulink>.
+ </para>
+ </section> <!-- end Introduction -->
+ <section>
+ <title>Configuring Hooks Libraries</title>
+ <para>
+ The hooks libraries for a given process are configured using the
+ <command>hooks-libraries</command> keyword in the
+ configuration for that process. (Note that
+ the word "hooks" is plural). The value of the keyword
+ is an array of strings, each string corresponding to a hooks library.
+ For example, to set up two hooks libraries for the DHCPv4 server, the
+ configuration would be:
+<screen>
+<userinput>"Dhcp4": {
+ :
+ "hooks-libraries": [
+ "/opt/charging.so",
+ "/opt/local/notification.so"
+ ]
+ :
+}</userinput>
+</screen>
+ </para>
+ <note><para>
+ At present, the libraries are specified as a simple list. A future
+ version of Kea will support the capability of specifying a set of
+ parameters for each library. When that is added, it is likely
+ that the syntax for specifying hooks libraries will change.
+ </para></note>
+ <para>
+ Notes:
+ <itemizedlist mark='bullet'>
+ <listitem><para>
+ The full path to each library should be given.
+ </para></listitem>
+ <listitem><para>
+ As noted above, order may be important - consult the documentation for
+ each library.
+ </para></listitem>
+ <listitem><para>
+ An empty list has the same effect as omitting the
+ <command>hooks-libraries</command> configuration element all together.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ At the present time, only the kea-dhcp4 and kea-dhcp6 processes support
+ hooks libraries.
+ </para>
+ </section>
+ </chapter> <!-- hooks-libraries -->
-// Copyright (C) 2013 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2013-2014 Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
handle.setSkip(true);
}
return;
-
+
@endcode
Like arguments, the "skip" flag is passed to all callouts on a hook. Callouts
the libkea-dns++ library). Depending on operating system, you may also need
to explicitly list libraries on which the Kea libraries depend.
-@subsection hooksdgConfiguration Configuring the Hook Library
+@subsection hooksdgConfiguration Configuring the Hooks Library
-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
-- this is discussed below.).
+The final step is to make the library known to Kea. The configuration
+keywords of all Kea modules to which hooks can be added contain the
+"hooks-libraries" element and user 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:
+To add the example library (assumed to be in /usr/local/lib) to the
+DHCPv4 module, it must be listed in the "hooks-libraries" element of the
+"Dhcp4" part of the configuration file:
@code
-> config add Dhcp4/hook_libraries
-> config set Dhcp4/hook_libraries[0] "/usr/local/lib/example.so"
-> config commit
+"Dhcp4": {
+ :
+ "hooks-libraries": [ "/usr/local/lib/example.so" ]
+ :
+}
@endcode
+(Note that "hooks" is plural.)
The DHCPv4 server will load the library and execute the callouts each time a
request is received.
@subsubsection hooksdgMultipleCallouts Multiple Callouts on a Hook
-The Kea 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.
may be present, but will not affect the context values set by a library's
callouts.
+Configuring multiple libraries just requires listing the libraries
+as separate elements of the hooks-libraries configuration element, e.g.
+
+@code
+"Dhcp4": {
+ :
+ "hooks-libraries": [ "/usr/lib/library1.so", "/opt/library2.so" ]
+ :
+}
+@endcode
+
@subsection hooksdgInterLibraryData Passing Data Between Libraries
In rare cases, it is possible that one library may want to pass
projects / thirdparty / kea.git / commitdiff
