From ae405fc3772f0328362fa5d9face67f92994873b Mon Sep 17 00:00:00 2001 From: Stephen Morris Date: Tue, 9 Dec 2014 17:58:56 +0000 Subject: [PATCH] [3635] Updated details of how to configure hooks libraries --- doc/guide/hooks.xml | 91 ++++++++++++++++++++++++++++++++++++ doc/guide/kea-guide.xml | 2 + src/lib/hooks/hooks_user.dox | 41 ++++++++++------ 3 files changed, 121 insertions(+), 13 deletions(-) create mode 100644 doc/guide/hooks.xml diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml new file mode 100644 index 0000000000..9978d66439 --- /dev/null +++ b/doc/guide/hooks.xml @@ -0,0 +1,91 @@ + + +]> + + + Hooks Libraries +
+ Introduction + + 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. + + + 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. + + + 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. + + + 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 Kea + Developer's Guide. + +
+
+ Configuring Hooks Libraries + + The hooks libraries for a given process are configured using the + hooks-libraries 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: + +"Dhcp4": { + : + "hooks-libraries": [ + "/opt/charging.so", + "/opt/local/notification.so" + ] + : +} + + + + 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. + + + Notes: + + + The full path to each library should be given. + + + As noted above, order may be important - consult the documentation for + each library. + + + An empty list has the same effect as omitting the + hooks-libraries configuration element all together. + + + + + At the present time, only the kea-dhcp4 and kea-dhcp6 processes support + hooks libraries. + +
+ diff --git a/doc/guide/kea-guide.xml b/doc/guide/kea-guide.xml index 1fe8123279..cdfa86e12f 100644 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@ -67,6 +67,8 @@ + + diff --git a/src/lib/hooks/hooks_user.dox b/src/lib/hooks/hooks_user.dox index 6f9954ba7b..3429e20a32 100644 --- a/src/lib/hooks/hooks_user.dox +++ b/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 -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 +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 -- 2.47.3