[master] Merge branch 'trac3635'

doc/Doxyfile

@@ -648,6 +648,7 @@ WARN_LOGFILE           =
 INPUT                  = ../src/bin/d2 \
                          ../src/bin/dhcp4 \
                          ../src/bin/dhcp6 \
+                         ../src/bin/perfdhcp \
                          ../src/bin/sockcreator \
                          ../src/hooks/dhcp/user_chk \
                          ../src/lib/asiolink \
@@ -666,7 +667,6 @@ INPUT                  = ../src/bin/d2 \
                          ../src/lib/util \
                          ../src/lib/util/io \
                          ../src/lib/util/threads \
-                         ../tests/tools/perfdhcp \
                          devel
 
 # This tag can be used to specify the character encoding of the source files

doc/guide/hooks.xml

@@ -0,0 +1,90 @@
+<?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.  When processing reaches a hook point,
+      Kea calls the hooks library functions attached to it.  If multiple
+      libraries have attached a function to a given hook point, Kea calls
+      all of them, in the order in which the libraries are specified in
+      the configuration file. The order 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
@@ -54,8 +54,8 @@ 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.
+run time. Libraries can be unloaded and reloaded as needed while Kea
+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
@@ -153,7 +153,7 @@ contents are:
 extern "C" {
 
 int version() {
-    return (BIND10_HOOKS_VERSION);
+    return (KEA_HOOKS_VERSION);
 }
 
 }
@@ -387,9 +387,9 @@ allocates an address to the client.  A callout may decide to allocate
 special addresses for certain clients, in which case it needs to tell
 the server not to allocate an address in this case.
 - Drop the packet and continue with the next request. A possible scenario
-is a DNS server where a callout inspects the source address of an incoming
-packet and compares it against a black list; if the address is on it,
-the callout notifies the server to drop the packet.
+is a server where a callout inspects the hardware address of the client
+sending the packet and compares it against a black list; if the address
+is on it, the callout notifies the server to drop the packet.
 
 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
@@ -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
@@ -420,26 +420,25 @@ later in the list are able to examine (and modify) the settings of earlier ones.
 
 @subsubsection hooksdgCalloutContext Per-Request Context
 
-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.
+Although the Kea modules can be characterised as handling a single
+packet at a time - e.g. the DHCPv4 server receives a DHCPDISCOVER packet,
+processes it and responds with an DHCPOFFER, this may not always be true.
+Future developments may have the server processing multiple packets
+simultaneously, or to suspend processing on a packet and resume it at
+a later time after other packets have been processed.
 
 As well as argument information, the CalloutHandle object can be used by
-callouts to attach information to a request being handled by the server.
+callouts to attach information to a packet 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.
+per-packet 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 associated with a packet only exists only for the duration of the
+processing of that packet: when processing is completed, the context is
+destroyed.  A new packet starts with a new (empty) context.  Context is
+particularly useful in servers that may be processing multiple packets
+simultaneously: callouts can effectively attach data to a packet that
+follows the packet 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
@@ -603,25 +602,28 @@ for details.
 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 Kea libraries depend.
+which they are attached. Depending on operating system, you may also need
+to explicitly list libraries on which the Kea libraries you link against 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.
@@ -841,7 +843,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 +1005,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