[3635] Updated details of how to configure hooks libraries

doc/guide/hooks.xml

@@ -0,0 +1,91 @@
+<?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  "&#x2014;" >
+]>
+
+  <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 -->

doc/guide/kea-guide.xml

@@ -67,6 +67,8 @@
 
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ddns.xml" />
 
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hooks.xml" />
+
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="libdhcp.xml" />
 
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.xml" />

src/lib/hooks/hooks_user.dox

@@ -1,4 +1,4 @@
-// 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
@@ -412,7 +412,7 @@ usage is intuitive:
         handle.setSkip(true);
     }
     return;
-    
+
 @endcode
 
 Like arguments, the "skip" flag is passed to all callouts on a hook.  Callouts
@@ -607,21 +607,25 @@ 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 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
+The final step is to make the library known to Kea.  The configuration
-which hooks can be added contain the "hook_library" element, and user
+keywords of all Kea modules to which hooks can be added contain the
-libraries are added to this. (The Kea hooks system can handle multiple libraries
+"hooks-libraries" element and user libraries are added to this. (The Kea
-- this is discussed below.).
+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
+To add the example library (assumed to be in /usr/local/lib) to the
-module, the following bindctl commands must be executed:
+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
+"Dhcp4": {
-> config set Dhcp4/hook_libraries[0] "/usr/local/lib/example.so"
+       :
-> config commit
+    "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.
@@ -841,7 +845,7 @@ ones with non-standard names need to be registered manually.
 
 @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.
 
@@ -1003,6 +1007,17 @@ 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.
 
+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