mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-31 05:55:28 +00:00
[3635] Updated details of how to configure hooks libraries
This commit is contained in:
Stephen Morris
91
doc/guide/hooks.xml
Normal file
91
doc/guide/hooks.xml
Normal file
@@ -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 "—" >
|
||||
]>
|
||||
|
||||
<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 -->
|
||||
@@ -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" />
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user