|
@@ -100,11 +100,11 @@ shared library and loaded by Kea into its address space.
|
|
|
To illustrate how to write code that integrates with Kea, we will
|
|
To illustrate how to write code that integrates with Kea, we will
|
|
|
use the following (rather contrived) example:
|
|
use the following (rather contrived) example:
|
|
|
|
|
|
|
|
-The Kea DHCPv4 server is used to allocate IPv4 addresses to clients
|
|
+<i>The Kea DHCPv4 server is used to allocate IPv4 addresses to clients
|
|
|
(as well as to pass them other information such as the address of DNS
|
|
(as well as to pass them other information such as the address of DNS
|
|
|
servers). We will suppose that we need to classify clients requesting
|
|
servers). We will suppose that we need to classify clients requesting
|
|
|
IPv4 addresses according to their hardware address, and want to log both
|
|
IPv4 addresses according to their hardware address, and want to log both
|
|
|
-the hardware address and allocated IP address for the clients of interest.
|
|
+the hardware address and allocated IP address for the clients of interest.</i>
|
|
|
|
|
|
|
|
The following sections describe how to implement these requirements.
|
|
The following sections describe how to implement these requirements.
|
|
|
The code presented here is not efficient and there are better ways of
|
|
The code presented here is not efficient and there are better ways of
|
|
@@ -282,11 +282,11 @@ int callout(CalloutHandle& handle);
|
|
|
@endcode
|
|
@endcode
|
|
|
|
|
|
|
|
(As before, the callout is declared with "C" linkage.) Information is passed
|
|
(As before, the callout is declared with "C" linkage.) Information is passed
|
|
|
-between Kea and the callout through name/value pairs in the CalloutHandle
|
|
+between Kea and the callout through name/value pairs in the @c CalloutHandle
|
|
|
object. The object is also used to pass information between callouts on a
|
|
object. The object is also used to pass information between callouts on a
|
|
|
per-request basis. (Both of these concepts are explained below.)
|
|
per-request basis. (Both of these concepts are explained below.)
|
|
|
|
|
|
|
|
-A callout returns an "int" as a status return. A value of 0 indicates
|
|
+A callout returns an @c int as a status return. A value of 0 indicates
|
|
|
success, anything else signifies an error. The status return has no
|
|
success, anything else signifies an error. The status return has no
|
|
|
effect on server processing; the only difference between a success
|
|
effect on server processing; the only difference between a success
|
|
|
and error code is that if the latter is returned, the server will
|
|
and error code is that if the latter is returned, the server will
|
|
@@ -296,7 +296,7 @@ error information to the Kea logging system.
|
|
|
|
|
|
|
|
@subsubsection hooksdgArguments Callout Arguments
|
|
@subsubsection hooksdgArguments Callout Arguments
|
|
|
|
|
|
|
|
-The CalloutHandle object provides two methods to get and set the
|
|
+The @c CalloutHandle object provides two methods to get and set the
|
|
|
arguments passed to the callout. These methods are called (naturally
|
|
arguments passed to the callout. These methods are called (naturally
|
|
|
enough) getArgument and SetArgument. Their usage is illustrated by the
|
|
enough) getArgument and SetArgument. Their usage is illustrated by the
|
|
|
following code snippets.
|
|
following code snippets.
|
|
@@ -336,27 +336,27 @@ In the callout
|
|
|
handle.setArgument("data_count", number);
|
|
handle.setArgument("data_count", number);
|
|
|
@endcode
|
|
@endcode
|
|
|
|
|
|
|
|
-As can be seen "getArgument" is used to retrieve data from the
|
|
+As can be seen @c getArgument is used to retrieve data from the
|
|
|
-CalloutHandle, and setArgument used to put data into it. If a callout
|
|
+@c CalloutHandle, and @c setArgument used to put data into it. If a callout
|
|
|
wishes to alter data and pass it back to the server, it should retrieve
|
|
wishes to alter data and pass it back to the server, it should retrieve
|
|
|
-the data with getArgument, modify it, and call setArgument to send
|
|
+the data with @c getArgument, modify it, and call @c setArgument to send
|
|
|
it back.
|
|
it back.
|
|
|
|
|
|
|
|
There are several points to be aware of:
|
|
There are several points to be aware of:
|
|
|
|
|
|
|
|
-- the data type of the variable in the call to getArgument must match
|
|
+- the data type of the variable in the call to @c getArgument must match
|
|
|
-the data type of the variable passed to the corresponding setArgument
|
|
+the data type of the variable passed to the corresponding @c setArgument
|
|
|
<B>exactly</B>: using what would normally be considered to be a
|
|
<B>exactly</B>: using what would normally be considered to be a
|
|
|
"compatible" type is not enough. For example, if the server passed
|
|
"compatible" type is not enough. For example, if the server passed
|
|
|
-an argument as an "int" and the callout attempted to retrieve it as a
|
|
+an argument as an @c int and the callout attempted to retrieve it as a
|
|
|
-"long", an exception would be thrown even though any value that can
|
|
+@c long, an exception would be thrown even though any value that can
|
|
|
-be stored in an "int" will fit into a "long". This restriction also
|
|
+be stored in an @c int will fit into a @c long. This restriction also
|
|
|
applies the "const" attribute but only as applied to data pointed to by
|
|
applies the "const" attribute but only as applied to data pointed to by
|
|
|
-pointers, e.g. if an argument is defined as a "char*", an exception will
|
|
+pointers, e.g. if an argument is defined as a @c char*, an exception will
|
|
|
be thrown if an attempt is made to retrieve it into a variable of type
|
|
be thrown if an attempt is made to retrieve it into a variable of type
|
|
|
-"const char*". (However, if an argument is set as a "const int", it can
|
|
+@c const @c char*. (However, if an argument is set as a @c const @c int,
|
|
|
-be retrieved into an "int".) The documentation of each hook point will
|
|
+it can be retrieved into an @c int.) The documentation of each hook
|
|
|
-detail the data type of each argument.
|
|
+point will detail the data type of each argument.
|
|
|
- Although all arguments can be modified, some altered values may not
|
|
- Although all arguments can be modified, some altered values may not
|
|
|
be read by the server. (These would be ones that the server considers
|
|
be read by the server. (These would be ones that the server considers
|
|
|
"read-only".) Consult the documentation of each hook to see whether an
|
|
"read-only".) Consult the documentation of each hook to see whether an
|
|
@@ -371,8 +371,8 @@ parameters can be modified. As a general rule:
|
|
|
|
|
|
|
|
- Do not alter arguments unless you mean the change to be reflected in
|
|
- Do not alter arguments unless you mean the change to be reflected in
|
|
|
the server.
|
|
the server.
|
|
|
-- If you alter an argument, call CalloutHandle::setArgument to update the
|
|
+- If you alter an argument, call @c CalloutHandle::setArgument to update the
|
|
|
-value in the CalloutHandle object.
|
|
+value in the @c CalloutHandle object.
|
|
|
|
|
|
|
|
@subsubsection hooksdgSkipFlag The "Skip" Flag
|
|
@subsubsection hooksdgSkipFlag The "Skip" Flag
|
|
|
|
|
|
|
@@ -391,7 +391,7 @@ 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
|
|
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.
|
|
is on it, the callout notifies the server to drop the packet.
|
|
|
|
|
|
|
|
-To handle these common cases, the CalloutHandle has a "skip" flag.
|
|
+To handle these common cases, the @c CalloutHandle has a "skip" flag.
|
|
|
This is set by a callout when it wishes the server to skip normal
|
|
This is set by a callout when it wishes the server to skip normal
|
|
|
processing. It is set false by the hooks framework before callouts on a
|
|
processing. It is set false by the hooks framework before callouts on a
|
|
|
hook are called. If the flag is set on return, the server will take the
|
|
hook are called. If the flag is set on return, the server will take the
|
|
@@ -427,7 +427,7 @@ Future developments may have the server processing multiple packets
|
|
|
simultaneously, or to suspend processing on a packet and resume it at
|
|
simultaneously, or to suspend processing on a packet and resume it at
|
|
|
a later time after other packets have been processed.
|
|
a later time after other packets have been processed.
|
|
|
|
|
|
|
|
-As well as argument information, the CalloutHandle object can be used by
|
|
+As well as argument information, the @c CalloutHandle object can be used by
|
|
|
callouts to attach information to a packet 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
|
|
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
|
|
is to allow callouts to pass information between one another on a
|
|
@@ -441,9 +441,9 @@ simultaneously: callouts can effectively attach data to a packet that
|
|
|
follows the packet around the system.
|
|
follows the packet around the system.
|
|
|
|
|
|
|
|
Context information is held as name/value pairs in the same way
|
|
Context information is held as name/value pairs in the same way
|
|
|
-as arguments, being accessed by the pair of methods setContext and
|
|
+as arguments, being accessed by the pair of methods @c setContext and
|
|
|
-getContext. They have the same restrictions as the setArgument and
|
|
+@c getContext. They have the same restrictions as the @c setArgument and
|
|
|
-getArgument methods - the type of data retrieved from context must
|
|
+@c getArgument methods - the type of data retrieved from context must
|
|
|
<B>exactly</B> match the type of the data set.
|
|
<B>exactly</B> match the type of the data set.
|
|
|
|
|
|
|
|
The example in the next section illustrates their use.
|
|
The example in the next section illustrates their use.
|
|
@@ -457,8 +457,9 @@ do this in one callout, for this example we'll use two:
|
|
|
|
|
|
|
|
- pkt4_receive - a callout on this hook is invoked when a packet has been
|
|
- pkt4_receive - a callout on this hook is invoked when a packet has been
|
|
|
received and has been parsed. It is passed a single argument, "query4"
|
|
received and has been parsed. It is passed a single argument, "query4"
|
|
|
-which is an isc::dhcp::Pkt4 object (representing a DHCP v4 packet).
|
|
+which is an isc::dhcp::Pkt4Ptr object, holding a pointer to the
|
|
|
-We will do the classification here.
|
|
+isc::dhcp::Pkt4 object (representing a DHCPv4 packet). We will do the
|
|
|
|
|
+classification here.
|
|
|
|
|
|
|
|
- pkt4_send - called when a response is just about to be sent back to
|
|
- pkt4_send - called when a response is just about to be sent back to
|
|
|
the client. It is passed a single argument "response4". This is the
|
|
the client. It is passed a single argument "response4". This is the
|
|
@@ -521,7 +522,7 @@ int pkt4_receive(CalloutHandle& handle) {
|
|
|
}
|
|
}
|
|
|
@endcode
|
|
@endcode
|
|
|
|
|
|
|
|
-The pkt4_receive callout placed the hardware address of an interesting client in
|
|
+The "pkt4_receive" callout placed the hardware address of an interesting client in
|
|
|
the "hwaddr" context for the packet. Turning now to the callout that will
|
|
the "hwaddr" context for the packet. Turning now to the callout that will
|
|
|
write this information to the log file:
|
|
write this information to the log file:
|
|
|
|
|
|
|
@@ -757,12 +758,12 @@ to initialize per-request context. The second is called after all
|
|
|
server-defined hooks have been processed, and is to allow a library to
|
|
server-defined hooks have been processed, and is to allow a library to
|
|
|
tidy up.
|
|
tidy up.
|
|
|
|
|
|
|
|
-As an example, the pkt4_send example above required that the code
|
|
+As an example, the "pkt4_send" example above required that the code
|
|
|
check for an exception being thrown when accessing the "hwaddr" context
|
|
check for an exception being thrown when accessing the "hwaddr" context
|
|
|
item in case it was not set. An alternative strategy would have been to
|
|
item in case it was not set. An alternative strategy would have been to
|
|
|
provide a callout for the "context_create" hook and set the context item
|
|
provide a callout for the "context_create" hook and set the context item
|
|
|
"hwaddr" to an empty string. Instead of needing to handle an exception,
|
|
"hwaddr" to an empty string. Instead of needing to handle an exception,
|
|
|
-pkt4_send would be guaranteed to get something when looking for
|
|
+"pkt4_send" would be guaranteed to get something when looking for
|
|
|
the hwaddr item and so could write or not write the output depending on
|
|
the hwaddr item and so could write or not write the output depending on
|
|
|
the value.
|
|
the value.
|
|
|
|
|
|
|
@@ -771,7 +772,7 @@ automatically deletes context. An example where it could be required
|
|
|
is where memory has been allocated by a callout during the processing
|
|
is where memory has been allocated by a callout during the processing
|
|
|
of a request and a raw pointer to it stored in the context object. On
|
|
of a request and a raw pointer to it stored in the context object. On
|
|
|
destruction of the context, that memory will not be automatically
|
|
destruction of the context, that memory will not be automatically
|
|
|
-released. Freeing in the memory in the "context_destroy callout will solve
|
|
+released. Freeing in the memory in the "context_destroy" callout will solve
|
|
|
that problem.
|
|
that problem.
|
|
|
|
|
|
|
|
Actually, when the context is destroyed, the destructor
|
|
Actually, when the context is destroyed, the destructor
|
|
@@ -786,8 +787,8 @@ Here it is assumed that the hooks library is performing some form of
|
|
|
security checking on the packet and needs to maintain information in
|
|
security checking on the packet and needs to maintain information in
|
|
|
a user-specified "SecurityInformation" object. (The details of this
|
|
a user-specified "SecurityInformation" object. (The details of this
|
|
|
fictitious object are of no concern here.) The object is created in
|
|
fictitious object are of no concern here.) The object is created in
|
|
|
-the context_create callout and used in both the pkt4_receive and the
|
|
+the "context_create" callout and used in both the "pkt4_receive" and the
|
|
|
-pkt4_send callouts.
|
|
+"pkt4_send" callouts.
|
|
|
|
|
|
|
|
@code
|
|
@code
|
|
|
// Storing information in a "raw" pointer. Assume that the
|
|
// Storing information in a "raw" pointer. Assume that the
|
|
@@ -831,7 +832,7 @@ int pkt4_send(CalloutHandle& handle) {
|
|
|
}
|
|
}
|
|
|
|
|
|
|
|
// Context destruction. We need to delete the pointed-to SecurityInformation
|
|
// Context destruction. We need to delete the pointed-to SecurityInformation
|
|
|
-// object because we will lose the pointer to it when the CalloutHandle is
|
|
+// object because we will lose the pointer to it when the @c CalloutHandle is
|
|
|
// destroyed.
|
|
// destroyed.
|
|
|
int context_destroy(CalloutHandle& handle) {
|
|
int context_destroy(CalloutHandle& handle) {
|
|
|
// Retrieve the pointer to the SecurityInformation object
|
|
// Retrieve the pointer to the SecurityInformation object
|
|
@@ -843,7 +844,7 @@ int context_destroy(CalloutHandle& handle) {
|
|
|
}
|
|
}
|
|
|
@endcode
|
|
@endcode
|
|
|
|
|
|
|
|
-The requirement for the context_destroy callout can be eliminated if
|
|
+The requirement for the "context_destroy" callout can be eliminated if
|
|
|
a Boost shared ptr is used to point to the allocated memory:
|
|
a Boost shared ptr is used to point to the allocated memory:
|
|
|
|
|
|
|
|
@code
|
|
@code
|
|
@@ -865,7 +866,7 @@ int context_create(CalloutHandle& handle) {
|
|
|
}
|
|
}
|
|
|
|
|
|
|
|
// Other than the data type, a shared pointer has similar semantics to a "raw"
|
|
// Other than the data type, a shared pointer has similar semantics to a "raw"
|
|
|
-// pointer. Only the code from pkt4_receive is shown here.
|
|
+// pointer. Only the code from "pkt4_receive" is shown here.
|
|
|
|
|
|
|
|
int pkt4_receive(CalloutHandle& handle) {
|
|
int pkt4_receive(CalloutHandle& handle) {
|
|
|
// Retrieve the pointer to the SecurityInformation object
|
|
// Retrieve the pointer to the SecurityInformation object
|
|
@@ -881,7 +882,7 @@ int pkt4_receive(CalloutHandle& handle) {
|
|
|
}
|
|
}
|
|
|
|
|
|
|
|
// No context_destroy callout is needed to delete the allocated
|
|
// No context_destroy callout is needed to delete the allocated
|
|
|
-// SecurityInformation object. When the CalloutHandle is destroyed, the shared
|
|
+// SecurityInformation object. When the @c CalloutHandle is destroyed, the shared
|
|
|
// pointer object will be destroyed. If that is the last shared pointer to the
|
|
// pointer object will be destroyed. If that is the last shared pointer to the
|
|
|
// allocated memory, then it too will be deleted.
|
|
// allocated memory, then it too will be deleted.
|
|
|
@endcode
|
|
@endcode
|
|
@@ -915,13 +916,13 @@ registration is through the LibraryHandle object. This was briefly
|
|
|
introduced in the discussion of the framework functions, in that
|
|
introduced in the discussion of the framework functions, in that
|
|
|
an object of this type is pass to the "load" function. A LibraryHandle
|
|
an object of this type is pass to the "load" function. A LibraryHandle
|
|
|
can also be obtained from within a callout by calling the CalloutHandle's
|
|
can also be obtained from within a callout by calling the CalloutHandle's
|
|
|
-getLibraryHandle() method.
|
|
+@c getLibraryHandle() method.
|
|
|
|
|
|
|
|
The LibraryHandle provides three methods to manipulate callouts:
|
|
The LibraryHandle provides three methods to manipulate callouts:
|
|
|
|
|
|
|
|
-- registerCallout - register a callout on a hook.
|
|
+- @c registerCallout - register a callout on a hook.
|
|
|
-- deregisterCallout - deregister a callout from a hook.
|
|
+- @c deregisterCallout - deregister a callout from a hook.
|
|
|
-- deregisterAllCallouts - deregister all callouts on a hook.
|
|
+- @c deregisterAllCallouts - deregister all callouts on a hook.
|
|
|
|
|
|
|
|
The following sections cover some of the ways in which these can be used.
|
|
The following sections cover some of the ways in which these can be used.
|
|
|
|
|
|
|
@@ -960,7 +961,7 @@ 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.
|
|
do this, there may be instances where it make sense.
|
|
|
|
|
|
|
|
To register multiple callouts on a hook, just call
|
|
To register multiple callouts on a hook, just call
|
|
|
-LibraryHandle::registerCallout multiple times on the same hook, e.g.
|
|
+@c LibraryHandle::registerCallout multiple times on the same hook, e.g.
|
|
|
|
|
|
|
|
@code
|
|
@code
|
|
|
libhandle.registerCallout("pkt4_receive", classify);
|
|
libhandle.registerCallout("pkt4_receive", classify);
|
|
@@ -968,7 +969,7 @@ LibraryHandle::registerCallout multiple times on the same hook, e.g.
|
|
|
@endcode
|
|
@endcode
|
|
|
|
|
|
|
|
The hooks framework will call the callouts in the order they are
|
|
The hooks framework will call the callouts in the order they are
|
|
|
-registered. The same CalloutHandle is passed between them, so any
|
|
+registered. The same @c CalloutHandle is passed between them, so any
|
|
|
change made to the CalloutHandle's arguments, "skip" flag, or per-request
|
|
change made to the CalloutHandle's arguments, "skip" flag, or per-request
|
|
|
context by the first is visible to the second.
|
|
context by the first is visible to the second.
|
|
|
|
|
|
|
@@ -1036,7 +1037,7 @@ int write_data(CalloutHandle& handle) {
|
|
|
flush(interesting);
|
|
flush(interesting);
|
|
|
|
|
|
|
|
// We've logged the data, so deregister ourself. This callout will not
|
|
// We've logged the data, so deregister ourself. This callout will not
|
|
|
- // be called again until it is registered by pkt4_receive.
|
|
+ // be called again until it is registered by "pkt4_receive".
|
|
|
|
|
|
|
|
handle.getLibraryHandle().deregisterCallout("pkt4_send", write_data);
|
|
handle.getLibraryHandle().deregisterCallout("pkt4_send", write_data);
|
|
|
|
|
|
|
@@ -1093,7 +1094,7 @@ request.
|
|
|
|
|
|
|
|
The vertical blue lines represent callout context. Context is
|
|
The vertical blue lines represent callout context. Context is
|
|
|
per-packet but also per-library. When the server calls "authorize",
|
|
per-packet but also per-library. When the server calls "authorize",
|
|
|
-the CalloutHandle's getContext and setContext methods access a context
|
|
+the CalloutHandle's @c getContext and @c setContext methods access a context
|
|
|
created purely for library 1. The next callout on the hook will access
|
|
created purely for library 1. The next callout on the hook will access
|
|
|
context created for library 2. These contexts are passed to the callouts
|
|
context created for library 2. These contexts are passed to the callouts
|
|
|
associated with the next hook. So when "check" is called, it gets the
|
|
associated with the next hook. So when "check" is called, it gets the
|
|
@@ -1132,7 +1133,7 @@ as separate elements of the hooks-libraries configuration element, e.g.
|
|
|
|
|
|
|
|
In rare cases, it is possible that one library may want to pass
|
|
In rare cases, it is possible that one library may want to pass
|
|
|
data to another. This can be done in a limited way by means of the
|
|
data to another. This can be done in a limited way by means of the
|
|
|
-CalloutHandle's setArgument and getArgument calls. For example, in the
|
|
+CalloutHandle's @c setArgument and @c getArgument calls. For example, in the
|
|
|
above diagram, the callout "add_option" can pass a value to "putopt"
|
|
above diagram, the callout "add_option" can pass a value to "putopt"
|
|
|
by setting a name.value pair in the hook's argument list. "putopt"
|
|
by setting a name.value pair in the hook's argument list. "putopt"
|
|
|
would be able to read this, but would not be able to return information
|
|
would be able to read this, but would not be able to return information
|
|
@@ -1185,7 +1186,7 @@ to add one.) For example:
|
|
|
extern "C" {
|
|
extern "C" {
|
|
|
|
|
|
|
|
int version() {
|
|
int version() {
|
|
|
- return (BIND10_HOOKS_VERSION);
|
|
+ return (KEA_HOOKS_VERSION);
|
|
|
}
|
|
}
|
|
|
|
|
|
|
|
int load() {
|
|
int load() {
|
Marcin Siodelski