mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-31 05:55:28 +00:00
Code Issues Releases Wiki Activity

[master] Merge branch 'trac3635'

Browse Source
This commit is contained in:
Stephen Morris
2014-12-17 11:59:49 +00:00
parent 32f06c29c0 cdb5c15405
commit 42d1c98a2e
4 changed files with 143 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/Doxyfile
View File

@@ -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

90
doc/guide/hooks.xml Normal file
View File

@@ -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 -->

2
doc/guide/kea-guide.xml
View File

@@ -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" />

87
src/lib/hooks/hooks_user.dox
View File

@@ -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