hooks_user.dox 66.7 KB
Newer Older
Razvan Becheriu's avatar
Razvan Becheriu committed
1
// Copyright (C) 2013-2020 Internet Systems Consortium, Inc. ("ISC")
2
//
3 4 5
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6

7 8 9 10
// Note: the prefix "hooksdg" to all labels is an abbreviation for "Hooks
// Developer's Guide" and is used to prevent a clash with symbols in any
// other Doxygen file.

11
/**
12
 @page hooksdgDevelopersGuide Hooks Developer's Guide
13

14
 @section hooksdgIntroduction Introduction
15

16
Although the Kea framework and its DHCP programs
17 18 19 20
provide comprehensive functionality, there will be times when it does
not quite do what you require: the processing has to be extended in some
way to solve your problem.

21
Since the Kea source code is freely available (Kea being an
22 23 24
open-source project), one option is to modify it to do what
you want.  Whilst perfectly feasible, there are drawbacks:

25
- Although well-documented, Kea is a large program.  Just
26 27 28 29
understanding how it works will take a significant amount of time. In
addition, despite the fact that its object-oriented design keeps the
coupling between modules to a minimum, an inappropriate change to one
part of the program during the extension could cause another to
30
behave oddly or to stop working altogether.
31 32

- The change may need to be re-applied or re-written with every new
33
version of Kea.  As new functionality is added or bugs are fixed,
34 35 36
the code or algorithms in the core software may change - and may change
significantly.

37
To overcome these problems, Kea provides the "Hooks" interface -
38 39 40
a defined interface for third-party or user-written code. (For ease of
reference in the rest of this document, all such code will be referred
to as "user code".)  At specific points in its processing
41
("hook points") Kea will make a call to this code.  The call passes
42
data that the user code can examine and, if required, modify.
43
Kea uses the modified data in the remainder of its processing.
44

45 46 47 48 49 50
In order to minimize the interaction between Kea and the user code,
the latter is built independently of Kea in the form of one or more
dynamic shared objects, called here (for historical reasons), shared
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 Kea is running.
51

52 53
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
54 55 56
the user code.  Unless there is a major change in an interface
(which will be clearly documented), all that will be required is a rebuild
of the libraries.
57 58

@note Although the defined interface should not change, the internals
59
of some of the classes and structures referenced by the user code may
60
change between versions of Kea.  These changes have to be reflected
61
in the compiled version of the software, hence the need for a rebuild.
62

63

64
@subsection hooksdgLanguages Languages
65

66
The core of Kea is written in C++.  While it is the intention to
67
provide interfaces into user code written in other languages, the initial
Francis Dupont's avatar
Francis Dupont committed
68 69 70 71
versions of the Hooks system required that user code be written in C++.
It is no longer the case and there are examples of hooks written for
instance in Python but this guide does not document how to do that.
All examples in this guide are in C++.
72

73

74
@subsection hooksdgTerminology Terminology
75 76 77 78

In the remainder of this guide, the following terminology is used:

- Hook/Hook Point - used interchageably, this is a point in the code at
79 80
which a call to user functions is made. Each hook has a name and
each hook can have any number (including 0) of user functions
81 82
attached to it.

83
- Callout - a user function called by the server at a hook
84
point. This is so-named because the server "calls out" to the library
85
to execute a user function.
86

87 88
- Framework function - the functions that a user library needs to
supply in order for the hooks framework to load and unload the library.
89

90 91
- User code/user library - non-Kea code that is compiled into a
shared library and loaded by Kea into its address space.
92 93


94
@section hooksdgTutorial Tutorial
95

96
To illustrate how to write code that integrates with Kea, we will
97 98
use the following (rather contrived) example:

99
<i>The Kea DHCPv4 server is used to allocate IPv4 addresses to clients
100 101 102
(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
IPv4 addresses according to their hardware address, and want to log both
103
the hardware address and allocated IP address for the clients of interest.</i>
104 105

The following sections describe how to implement these requirements.
106 107
The code presented here is not efficient and there are better ways of
doing the task.  The aim however, is to illustrate the main features of
108
user hooks code, not to provide an optimal solution.
109 110


111
@subsection hooksdgFrameworkFunctions Framework Functions
112

113
Loading and initializing a library holding user code makes use
114 115
of three (user-supplied) functions:

116
- version - defines the version of Kea code with which the user-library
117 118 119
is built
- load - called when the library is loaded by the server.
- unload - called when the library is unloaded by the server.
120 121
- multi_threading_compatible - defines the compatibility (or not) of
the user-library and a multi-threaded DHCP service.
122

123
Of these, only "version" is mandatory, although in our example, all four
124 125
are used.

126
@subsubsection hooksdgVersionFunction The "version" Function
127 128

"version" is used by the hooks framework to check that the libraries
129 130
it is loading are compatible with the version of Kea being run.
Although the hooks system allows Kea and user code to interface
131
through a defined API, the relationship is somewhat tight in that the
132 133
user code will depend on the internal structures of Kea.  If these
change - as they can between Kea releases - and Kea is run with
134
a version of user code built against an earlier version of Kea, a program
135
crash could result.
136

137 138
To guard against this, the "version" function must be provided in every
library.  It returns a constant defined in header files of the version
139 140
of Kea against which it was built.  The hooks framework checks this
for compatibility with the running version of Kea before loading
141
the library.
142 143 144 145 146 147 148 149 150 151 152 153

In this tutorial, we'll put "version" in its own file, version.cc.  The
contents are:

@code
// version.cc

#include <hooks/hooks.h>

extern "C" {

int version() {
154
    return (KEA_HOOKS_VERSION);
155 156
}

157
}
158 159
@endcode

160
The file "hooks/hooks.h" is specified relative to the Kea libraries
161
source directory - this is covered later in the section @ref hooksdgBuild.
162 163
It defines the symbol KEA_HOOKS_VERSION, which has a value that changes
on every release of Kea: this is the value that needs to be returned
164
to the hooks framework.
165 166 167 168 169 170 171

A final point to note is that the definition of "version" is enclosed
within 'extern "C"' braces.  All functions accessed by the hooks
framework use C linkage, mainly to avoid the name mangling that
accompanies use of the C++ compiler, but also to avoid issues related
to namespaces.

172
@subsubsection hooksdgLoadUnloadFunctions The "load" and "unload" Functions
173 174

As the names suggest, "load" is called when a library is loaded and
175 176
"unload" called when it is unloaded.  (It is always guaranteed that
"load" is called: "unload" may not be called in some circumstances,
177
e.g., if the system shuts down abnormally.)  These functions are the
178 179 180 181
places where any library-wide resources are allocated and deallocated.
"load" is also the place where any callouts with non-standard names
(names that are not hook point names) can be registered:
this is covered further in the section @ref hooksdgCalloutRegistration.
182 183

The example does not make any use callouts with non-standard names.  However,
184
as our design requires that the log file be open while Kea is active
185
and the library loaded, we'll open the file in the "load" function and close
186 187 188
it in "unload".

We create two files, one for the file handle declaration:
189 190 191 192 193 194

@code
// library_common.h

#ifndef LIBRARY_COMMON_H
#define LIBRARY_COMMON_H
195

196 197 198 199
#include <fstream>

// "Interesting clients" log file handle declaration.
extern std::fstream interesting;
200 201

#endif // LIBRARY_COMMON_H
202 203 204 205 206 207 208 209 210 211
@endcode

... and one to hold the "load" and "unload" functions:

@code
// load_unload.cc

#include <hooks/hooks.h>
#include "library_common.h"

212 213
using namespace isc::hooks;

214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
// "Interesting clients" log file handle definition.
std::fstream interesting;

extern "C" {

int load(LibraryHandle&) {
    interesting.open("/data/clients/interesting.log",
                     std::fstream::out | std::fstream::app);
    return (interesting ? 0 : 1);
}

int unload() {
    if (interesting) {
        interesting.close();
    }
    return (0);
}

232
}
233 234 235 236 237 238 239
@endcode

Notes:
- The file handle ("interesting") is declared in a header file and defined
outside of any function.  This means it can be accessed by any function
within the user library.  For convenience, the definition is in the
load_unload.cc file.
240 241 242 243 244 245
- "load" is called with a LibraryHandle argument, this being used in
the registration of functions.  As no functions are being registered
in this example, the argument specification omits the variable name
(whilst retaining the type) to avoid an "unused variable" compiler
warning. (The LibraryHandle and its use is discussed in the section
@ref hooksdgLibraryHandle.)
Francis Dupont's avatar
Francis Dupont committed
246
- In the initial version of the hooks framework, it was not possible to pass
247
any configuration information to the "load" function.  The name of the log
Francis Dupont's avatar
Francis Dupont committed
248
file had therefore to be hard-coded as an absolute path name or communicated
249
to the user code by some other means.
250
- "load" must return 0 on success and non-zero on error.  The hooks framework
251 252 253 254
will abandon the loading of the library if "load" returns an error status.
(In this example, "interesting" can be tested as a boolean value,
returning "true" if the file opened successfully.)
- "unload" closes the log file if it is open and is a no-op otherwise. As
255
with "load", a zero value must be returned on success and a non-zero value
256
on an error.  The hooks framework will record a non-zero status return
257
as an error in the current Kea log but otherwise ignore it.
258 259
- As before, the function definitions are enclosed in 'extern "C"' braces.

260 261 262 263 264 265 266 267 268 269
In some cases to restrict the library loading to DHCP servers so it
cannot be loaded by the DDNS server or the Control Agent.
The best way to perform this is to check the process name returned
by @c isc::dhcp::Daemon::getProcName() static / class method declared
in process/daemon.h header against "kea-dhcp4" and "kea-dhcp6"
(other values are "kea-dhcp-ddns", "kea-ctrl-agent" and "kea-netconf").
If you'd like to check the address family too it is returned in DHCP servers
by isc::dhcp::CfgMgr::instance().getFamily() declared in dhcpsrv/cfgmgr.h
with AF_INET and AF_INET6 values.

Francis Dupont's avatar
Francis Dupont committed
270
@subsubsection hooksdgMultiThreadingCompatibleFunction The "multi_threading_compatible" function
271 272 273

"multi_threading_compatible" is used by the hooks framework to check
if the libraries it is loading are compatible with the DHCPv4 or DHCPv6
Razvan Becheriu's avatar
Razvan Becheriu committed
274 275
server multi-threading configuration. The value 0 means not compatible
and is the default when the function is not implemented. Non 0 values
276 277
mean compatible.

278 279 280 281
If your code implements it and returns the value 0 it is recommended
to document the reason so someone revisiting the code will not by
accident change the code.

282 283
To be compatible means:
- the code associated with DHCP packet processing callouts e.g.
284
pkt4_receive or pkt6_send must be thread safe so the multi-threaded
Razvan Becheriu's avatar
Razvan Becheriu committed
285 286
DHCP service can simultaneously call more than once one of these callouts.
- commands registered by a library are not required to be thread safe because
287 288 289
commands are executed by the main thread. Now it is a good idea to make
them thread safe and to document cases where they are not.
- when a library implements a thread safe backend API (e.g. host data
Razvan Becheriu's avatar
Razvan Becheriu committed
290
source) the service methods must be thread safe.
291
- a library which modifies the internal configuration of the server,
Razvan Becheriu's avatar
Razvan Becheriu committed
292
e.g. creates or deletes a subnet, it must enter a critical section using
293
the @c isc::util::MultiThreadingCriticalSection RAII class.
294

Francis Dupont's avatar
Francis Dupont committed
295
In the tutorial, we'll put "multi_threading_compatible" in its own file,
296 297 298 299 300 301 302 303
multi_threading_compatible.cc. The contents are:

@code
// multi_threading_compatible.cc

extern "C" {

int multi_threading_compatible() {
Razvan Becheriu's avatar
Razvan Becheriu committed
304
    return (1);
305 306 307 308
}

}
@endcode
309

310 311 312
and for a command creating a new subnet:

@code
Razvan Becheriu's avatar
Razvan Becheriu committed
313
#include <util/multi_threading_mgr.h>
314 315 316 317 318

int commandHandler(CalloutHandle& handle) {
    ...
    {
        // Enter the critical section.
319
        isc::util::MultiThreadingCriticalSection ct;
320 321 322 323 324 325 326
        <add the subnet>
        // Leave the critical section.
    }
    ...
}
@endcode

Francis Dupont's avatar
Francis Dupont committed
327 328
@ref hooksMultiThreading provides more details about thread safety
requirements.
329

330
@subsection hooksdgCallouts Callouts
331 332 333

Having sorted out the framework, we now come to the functions that
actually do something.  These functions are known as "callouts" because
334
the Kea code "calls out" to them.  Each Kea server has a number of
335 336 337
hooks to which callouts can be attached: server-specific documentation
describes in detail the points in the server at which the hooks are
present together with the data passed to callouts attached to them.
338 339

Before we continue with the example, we'll discuss how arguments are
340 341
passed to callouts and information is returned to the server.  We will
also discuss how information can be moved between callouts.
342

343
@subsubsection hooksdgCalloutSignature The Callout Signature
344 345 346 347 348

All callouts are declared with the signature:
@code
extern "C" {
int callout(CalloutHandle& handle);
349
}
350 351 352
@endcode

(As before, the callout is declared with "C" linkage.)  Information is passed
353
between Kea and the callout through name/value pairs in the @c CalloutHandle
354 355 356
object. The object is also used to pass information between callouts on a
per-request basis. (Both of these concepts are explained below.)

357
A callout returns an @c int as a status return.  A value of 0 indicates
358 359 360 361 362
success, anything else signifies an error.  The status return has no
effect on server processing; the only difference between a success
and error code is that if the latter is returned, the server will
log an error, specifying both the library and hook that generated it.
Effectively the return status provides a quick way for a callout to log
363
error information to the Kea logging system.
364

365
@subsubsection hooksdgArguments Callout Arguments
366

367
The @c CalloutHandle object provides two methods to get and set the
368
arguments passed to the callout.  These methods are called (naturally
Francis Dupont's avatar
Francis Dupont committed
369
enough) getArgument and setArgument.  Their usage is illustrated by the
370 371 372 373 374 375 376 377 378 379 380 381
following code snippets.

@code
    // Server-side code snippet to show the setting of arguments

    int count = 10;
    boost::shared_ptr<Pkt4> pktptr = ... // Set to appropriate value

    // Assume that "handle" has been created
    handle.setArgument("data_count", count);
    handle.setArgument("inpacket", pktptr);

382
    // Call the callouts attached to the hook
383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406
    ...

    // Retrieve the modified values
    handle.getArgument("data_count", count);
    handle.getArgument("inpacket", pktptr);
@endcode

In the callout

@code
    int number;
    boost::shared_ptr<Pkt4> packet;

    // Retrieve data set by the server.
    handle.getArgument("data_count", number);
    handle.getArgument("inpacket", packet);

    // Modify "number"
    number = ...;

    // Update the arguments to send the value back to the server.
    handle.setArgument("data_count", number);
@endcode

407 408
As can be seen @c getArgument is used to retrieve data from the
@c CalloutHandle, and @c setArgument used to put data into it.  If a callout
409
wishes to alter data and pass it back to the server, it should retrieve
410
the data with @c getArgument, modify it, and call @c setArgument to send
411 412 413 414
it back.

There are several points to be aware of:

415 416
- the data type of the variable in the call to @c getArgument must match
the data type of the variable passed to the corresponding @c setArgument
417 418
<B>exactly</B>: using what would normally be considered to be a
"compatible" type is not enough.  For example, if the server passed
419 420 421
an argument as an @c int and the callout attempted to retrieve it as a
@c long, an exception would be thrown even though any value that can
be stored in an @c int will fit into a @c long.  This restriction also
422
applies the "const" attribute but only as applied to data pointed to by
423
pointers, e.g., if an argument is defined as a @c char*, an exception will
424
be thrown if an attempt is made to retrieve it into a variable of type
425 426 427
@c const @c char*.  (However, if an argument is set as a @c const @c int,
it can be retrieved into an @c int.)  The documentation of each hook
point will detail the data type of each argument.
428 429 430 431 432 433
- Although all arguments can be modified, some altered values may not
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
argument can be used to transfer data back to the server.
- If a pointer to an object is passed to a callout (either a "raw"
pointer, or a boost smart pointer (as in the example above), and the
434
underlying object is altered through that pointer, the change will be
435 436 437 438 439 440 441
reflected in the server even if no call is made to setArgument.

In all cases, consult the documentation for the particular hook to see whether
parameters can be modified.  As a general rule:

- Do not alter arguments unless you mean the change to be reflected in
the server.
442 443
- If you alter an argument, call @c CalloutHandle::setArgument to update the
value in the @c CalloutHandle object.
444

445
@subsubsection hooksdgNextStep The Next step status
446

447
Note: This functionality used to be provided in Kea 0.9.2 and earlier using
Francis Dupont's avatar
Francis Dupont committed
448
boolean skip flag. See @ref hooksdgSkipFlag for explanation and tips how
449
to migrate your hooks code to this new API.
450 451 452 453 454 455

When a to callouts attached to a hook returns, the server will usually continue
its processing.  However, a callout might have done something that means that
the server should follow another path.  Possible actions a server could take
include:

456 457 458 459 460
- Continue as usual. This is the default value. Unless callouts explicitly
change the status, the server will continue processing. There is no need
to set the status, unless one callout wants to override the status set
by another callout. This action is represented by CalloutHandle::NEXT_STEP_CONTINUE.

461 462 463 464
- Skip the next stage of processing because the callout has already
done it.  For example, a hook is located just before the DHCP server
allocates an address to the client.  A callout may decide to allocate
special addresses for certain clients, in which case it needs to tell
465 466 467
the server not to allocate an address in this case. This action is
hook specific and is represented by CalloutHandle::NEXT_STEP_SKIP.

468
- Drop the packet and continue with the next request. A possible scenario
469 470
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
471 472
is on it, the callout notifies the server to drop the packet. This
action is represented by CalloutHandle::NEXT_STEP_DROP.
473

474 475 476 477 478 479
To handle these common cases, the @c CalloutHandle has a setStatus method.
This is set by a callout when it wishes the server to change the normal
processing. Exact meaning is hook specific. Please consult hook API
documentation for details. For historic reasons (Kea 0.9.2 used a single
boolean flag called skip that also doubled in some cases as an indicator
to drop the packet) several hooks use SKIP status to drop the packet.
480

Razvan Becheriu's avatar
Razvan Becheriu committed
481 482
The methods to get and set the "skip" or "drop" state are getStatus and
setStatus. Their usage is intuitive:
483 484

@code
485
    // Get the current setting of the next step status.
Razvan Becheriu's avatar
Razvan Becheriu committed
486
    auto status = handle.getStatus();
487 488 489 490

    if (status == CalloutHandle::NEXT_STEP_DROP)
       // Do something...
       :
491

Razvan Becheriu's avatar
Razvan Becheriu committed
492 493 494 495
    if (status == CalloutHandle::NEXT_STEP_SKIP)
       // Do something...
       :

496 497 498 499 500
    // Do some processing...
        :
    if (lease_allocated) {
        // Flag the server to skip the next step of the processing as we
        // already have an address.
501
        handle.setStatus(CalloutHandle::NEXT_STEP_SKIP);
502 503
    }
    return;
504

505 506
@endcode

507
Like arguments, the next step status is passed to all callouts on a hook.  Callouts
508 509
later in the list are able to examine (and modify) the settings of earlier ones.

Razvan Becheriu's avatar
Razvan Becheriu committed
510 511 512 513 514 515 516 517 518 519 520
If using multiple libraries, when the library wants to drop the current packet,
the DROP status must be used instead of the SKIP status so that the packet
processing ends at that specific hook point.

It is recommended for all callouts to check the status before doing any
processing.  As callouts can modify the status, it is recommended to take good
care when doing so, because this will have impact on all remaining hooks as well.
It is highly recommended to not reset the SKIP or DROP status to CONTINUE, even
though possible, so that the rest of the loaded hooks and the server can check
and perform the proper action.

521 522 523
Some hook points handle special functionality for the server, like pkt4_receive,
pkt6_receive, which handle unpacking of the received packet, pkt4_send, pkt6_send,
which handle packing of the response packet.
Razvan Becheriu's avatar
Razvan Becheriu committed
524

525 526 527 528 529
If the hook handles these actions and sets the next step flag to SKIP, it should
also perform a check for the SKIP flag before anything else.  If it is already
set, do not pack/unpack the packet (other library, or even the same library, if
loaded multiple times, has done it already).  Some libraries might also need to
throw exceptions in such cases because they need to perform specific actions before
Razvan Becheriu's avatar
Razvan Becheriu committed
530 531
pack/unpack (eg. addOption/delOption before pack action), which have no effect if
pack/unpack action is done previously by some other library.
532

Razvan Becheriu's avatar
Razvan Becheriu committed
533
@code
Razvan Becheriu's avatar
Razvan Becheriu committed
534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552
    // Check if other library has already set SKIP flag and performed unpack
    // so that unpack is skipped
    if (handle.getStatus() != CalloutHandle::NEXT_STEP_SKIP) {
        query->unpack();
    }
@endcode

@code
    // Check the status state.
    auto status = handle.getStatus();
    if (status == CalloutHandle::NEXT_STEP_SKIP) {
        isc_throw(InvalidOperation, "packet pack already handled");
    }
    ...
    response->delOption(DEL_OPTION_CODE);
    ...
    response->addOption(ADD_OPTION_CODE);
    ...
    response->pack();
Razvan Becheriu's avatar
Razvan Becheriu committed
553 554 555
@endcode

As stated before, the order of loading libraries is critical in achieving the
Razvan Becheriu's avatar
Razvan Becheriu committed
556 557 558
desired behavior, so please read @ref hooksdgMultipleLibraries when configuring
multiple libraries.

559 560 561 562 563 564 565
@subsubsection hooksdgSkipFlag The "Skip" Flag (deprecated)

In releases 0.9.2 and earlier, the functionality currently offered by next step
status (see @ref hooksdgNextStep) was provided by
a boolean flag called "Skip". However, since it only allowed to either continue
or skip the next processing step and was not extensible to other decisions,
setSkip(bool) call was replaced with a setStatus(enum) in Kea 1.0. This
566
new approach is extensible. If we decide to add new results (e.g., WAIT
567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594
or RATELIMIT), we will be able to do so without changing the API again.

If you have your hooks libraries that take advantage of skip flag, migrating
to the next step status is very easy. See @ref hooksdgNextStep for detailed
explanation of the new status field.

To migrate, replace this old code:
@code
handle.setSkip(false); // This is the default.

handle.setSkip(true);  // Tell the server to skip the next processing step.

bool skip = hangle.getSkip(); // Check the skip flag state.
if (skip) {
   ...
}
@endcode

with this:

@code
// This is the default.
handle.setStatus(CalloutHandle::NEXT_STEP_CONTINUE);

// Tell the server to skip the next processing step.
handle.setStatus(CalloutHandle::NEXT_STEP_SKIP);

// Check the status state.
Razvan Becheriu's avatar
Razvan Becheriu committed
595
auto status = handle.getStatus();
596 597 598 599 600
if (status == CalloutHandle::NEXT_STEP_SKIP) {
    ...
}
@endcode

601
@subsubsection hooksdgCalloutContext Per-Request Context
602

Francis Dupont's avatar
Francis Dupont committed
603
Although the Kea modules can be characterized as handling a single
604
packet at a time - e.g., the DHCPv4 server receives a DHCPDISCOVER packet,
605
processes it and responds with an DHCPOFFER, this may not always be true.
606 607 608
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.
609

610
As well as argument information, the @c CalloutHandle object can be used by
611
callouts to attach information to a packet being handled by the server.
612 613
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
614
per-packet basis.
615

616 617 618 619 620 621
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.
622 623

Context information is held as name/value pairs in the same way
624 625 626
as arguments, being accessed by the pair of methods @c setContext and
@c getContext.  They have the same restrictions as the @c setArgument and
@c getArgument methods - the type of data retrieved from context must
627 628
<B>exactly</B> match the type of the data set.

629
The example in the next section illustrates their use.
630

631

632
@subsection hooksdgExampleCallouts Example Callouts
633 634 635 636 637 638

Continuing with the tutorial, the requirements need us to retrieve the
hardware address of the incoming packet, classify it, and write it,
together with the assigned IP address, to a log file.  Although we could
do this in one callout, for this example we'll use two:

639 640
- 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"
641 642 643
which is an isc::dhcp::Pkt4Ptr object, holding a pointer to the
isc::dhcp::Pkt4 object (representing a DHCPv4 packet). We will do the
classification here.
644

645 646 647 648
- 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
point at which the example code will write the hardware and IP addresses
to the log file.
649 650 651 652

The standard for naming callouts is to give them the same name as
the hook.  If this is done, the callouts will be automatically found
by the Hooks system (this is discussed further in section @ref
653
hooksdgCalloutRegistration).  For our example, we will assume this is the
654 655 656 657
case, so the code for the first callout (used to classify the client's
hardware address) is:

@code
658
// pkt_receive4.cc
659 660 661 662 663 664 665 666

#include <hooks/hooks.h>
#include <dhcp/pkt4.h>
#include "library_common.h"

#include <string>

using namespace isc::dhcp;
667
using namespace isc::hooks;
668 669 670 671
using namespace std;

extern "C" {

672 673
// This callout is called at the "pkt4_receive" hook.
int pkt4_receive(CalloutHandle& handle) {
674 675 676 677

    // A pointer to the packet is passed to the callout via a "boost" smart
    // pointer. The include file "pkt4.h" typedefs a pointer to the Pkt4
    // object as Pkt4Ptr.  Retrieve a pointer to the object.
678 679
    Pkt4Ptr query4_ptr;
    handle.getArgument("query4", query4_ptr);
680 681

    // Point to the hardware address.
682
    HWAddrPtr hwaddr_ptr = query4_ptr->getHWAddr();
683 684 685 686 687 688

    // The hardware address is held in a public member variable. We'll classify
    // it as interesting if the sum of all the bytes in it is divisible by 4.
    //  (This is a contrived example after all!)
    long sum = 0;
    for (int i = 0; i < hwaddr_ptr->hwaddr_.size(); ++i) {
689
        sum += hwaddr_ptr->hwaddr_[i];
690 691 692 693 694 695
    }

    // Classify it.
    if (sum % 4 == 0) {
        // Store the text form of the hardware address in the context to pass
        // to the next callout.
696 697
        string hwaddr = hwaddr_ptr->toText();
        handle.setContext("hwaddr", hwaddr);
698 699 700 701
    }

    return (0);
};
702 703

}
704 705
@endcode

706
The "pkt4_receive" callout placed the hardware address of an interesting client in
707 708 709 710
the "hwaddr" context for the packet.  Turning now to the callout that will
write this information to the log file:

@code
711
// pkt4_send.cc
712 713 714 715 716 717 718 719

#include <hooks/hooks.h>
#include <dhcp/pkt4.h>
#include "library_common.h"

#include <string>

using namespace isc::dhcp;
720
using namespace isc::hooks;
721 722 723 724
using namespace std;

extern "C" {

725 726
// This callout is called at the "pkt4_send" hook.
int pkt4_send(CalloutHandle& handle) {
727 728 729 730 731

    // Obtain the hardware address of the "interesting" client.  We have to
    // use a try...catch block here because if the client was not interesting,
    // no information would be set and getArgument would thrown an exception.
    string hwaddr;
732 733
    try {
        handle.getContext("hwaddr", hwaddr);
734

735
        // getContext didn't throw so the client is interesting.  Get a pointer
736 737 738
        // to the reply.
        Pkt4Ptr response4_ptr;
        handle.getArgument("response4", response4_ptr);
739 740

        // Get the string form of the IP address.
741
        string ipaddr = response4_ptr->getYiaddr().toText();
742 743 744 745 746 747 748 749

        // Write the information to the log file.
        interesting << hwaddr << " " << ipaddr << "\n";

        // ... and to guard against a crash, we'll flush the output stream.
        flush(interesting);

    } catch (const NoSuchCalloutContext&) {
750 751 752 753
        // No such element in the per-request context with the name "hwaddr".
        // This means that the request was not an interesting, so do nothing
        // and dismiss the exception.
     }
754 755 756 757

    return (0);
}

758
}
759 760
@endcode

761

762 763 764 765 766
@subsection hooksdgLogging Logging in the Hooks Library

Hooks libraries take part in the DHCP message processing. They also often
modify the server's behavior by taking responsibility for processing
the DHCP message at certain stages and instructing the server to skip
767 768
the default processing for that stage. Thus, hooks libraries play an
important role in the DHCP server operation and, depending on their
Josh Soref's avatar
Josh Soref committed
769
purpose, they may have high complexity, which increases likelihood of the
770
defects in the libraries.
771

Josh Soref's avatar
Josh Soref committed
772
All hooks libraries should use Kea logging system to facilitate diagnostics
773
of the defects in the libraries and issues with the DHCP server's operation.
774 775 776
Even if the issue doesn't originate in the hooks library itself, the use
of the library may uncover issues in the Kea code that only
manifest themselves in some special circumstances.
777 778

Hooks libraries use the Kea logging system in the same way as any other
779 780
standard Kea library. A hooks library should have at least one logger
defined, but may have multiple loggers if it is desired
781 782
to separate log messages from different functional parts of the library.

783 784 785
Assuming that it has been decided to use logging in the hooks library, the
implementor must select a unique name for the logger. Ideally the name
should have some relationship with the name of the library so that it is
786 787 788
easy to distinguish messages logged from this library. For example,
if the hooks library is used to capture incoming and outgoing DHCP
messages, and the name of the library is "libkea-packet-capture",
789
a suitable logger name could be "packet-capture".
790

791 792
In order to use a logger within the library, the logger should be declared
in a header file, which must be included in all files using
793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811
the logger:

@code
#ifndef PACKET_CAPTURE_LOG_H
#define PACKET_CAPTURE_LOG_H

#include <log/message_initializer.h>
#include <log/macros.h>
#include <user_chk_messages.h>

namespace packet_capture {

extern isc::log::Logger packet_capture_logger;

}

#endif
@endcode

812 813
The logger should be defined and initialized in the implementation file,
as illustrated below:
814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830

@code
#include <packet_capture_log.h>

namespace packet_capture {

isc::log::Logger packet_capture_logger("packet-capture");

}
@endcode

These files may contain multiple logger declarations and initializations
when the use of more than one logger is desired.

The next step is to add the appropriate message file as described in the
@ref logMessageFiles.

831 832 833 834 835 836 837 838 839 840 841 842 843 844 845
The implementor must make sure that log messages appear in the right
places and that they are logged at the appropriate level. The choice
of the place where the message should appear is not always obvious:
it depends if the particular function being called already logs enough
information and whether adding log message before and/or after the
call to this function would simply duplicate some messages. Sometimes
the choice whether the log message should appear within the function or
outside of it depends on the level of details available for logging. For
example, in many cases it is desirable to include the client identifier
or transaction id of the DHCP packet being processed in logging message.
If this information is available at the higher level but not in the
function being called, it is often better to place the log message at
higher level.  However, the function parameters list could be extended
to include the additional information, and to be logged and the logging
call made from within the function.
846 847

Ideally, the hooks library should contain debug log messages (traces)
848
in all significant decision points in the code, with the information as to
849 850 851
how the code hit this decision point, how it will proceed and why.
However, care should be taken when selecting the log level for those
messages, because selecting too high logging level may impact the
852
performance of the system. For this reason, traces (messages of
853 854 855 856
the debug severity) should use different debug levels for the
messages of different importance or having different performance
requirements to generate the log message. For example, generation of
a log message, which prints full details of a packet, usually requires
Josh Soref's avatar
Josh Soref committed
857
more CPU bandwidth than the generation of the message which only prints
858 859 860 861 862 863 864 865
the packet type and length. Thus, the former should be logged at
lower debug level (see @ref logSeverity for details of using
various debug levels using "dbglevel" parameter).

All loggers defined within the hooks libraries derive the default
configuration from the root logger. For example, when the hooks
library is attached to the DHCPv4 server, the root logger name is
"kea-dhcp4", and the library by default uses configuration of this
866
logger. The configuration of the library's logger can
867
be modified by adding a configuration entry for it
868
to the configuration file. In case of the "packet-capture"
869 870 871 872 873
logger declared above, the full name of the logger in the
configuration file will be "kea-dhcp4.packet-capture". The
configuration specified for this logger will override the default
configuration derived from the root logger.

874

875
@subsection hooksdgBuild Building the Library
876

Francis Dupont's avatar
Francis Dupont committed
877 878
Building the code requires building a sharable library.  This requires
the the code be compiled as position-independent code (using the
879 880
compiler's "-fpic" switch) and linked as a shared library (with the
linker's "-shared" switch).  The build command also needs to point to
881
the Kea include directory and link in the appropriate libraries.
882

883
Assuming that Kea has been installed in the default location, the
884 885 886 887
command line needed to create the library using the Gnu C++ compiler on a
Linux system is:

@code
888
g++ -I <install-dir>/include/kea -L <install-dir>/lib -fpic -shared -o example.so \
889
    load_unload.cc pkt4_receive.cc pkt4_send.cc version.cc \
890
    -lkea-dhcpsrv -lkea-dhcp++ -lkea-hooks -lkea-log -lkea-util -lkea-exceptions
891 892 893
@endcode

Notes:
894 895 896
- Replace "<install-dir>" with the location in which you installed Kea. Unless
you specified the "--prefix" switch on the "configure" command line when
building Kea, it will be installed in the default location, usually /usr/local.
897
- The compilation command and switches required may vary depending on
898 899
your operating system and compiler - consult the relevant documentation
for details.
900
- The list of libraries that need to be included in the command line
901
depends on the functionality used by the hook code and the module to
902 903
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.
904

905

906
@subsection hooksdgConfiguration Configuring the Hooks Library
907

908 909 910 911
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.)
912

913 914 915
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:
916 917

@code
918 919
"Dhcp4": {
       :
920 921 922 923
    "hooks-libraries": [
        {
            "library": "/usr/local/lib/example.so"
        }
924 925
    ]
        :
926
}
927
@endcode
928
(Note that "hooks" is plural.)
929

930 931 932 933 934 935 936
Each entry in the "hooks-libraries" list is a structure (a "map" in JSON
parlance) that holds the following element:
- library - the name of the library to load.  This must be a string.

@note The syntax of the hooks-libraries configuration element has changed
since kea 0.9.2 (in that version, "hooks-libraries" was just a list of
libraries).  This change is in preparation for the introduction of
937 938 939 940
library-specific parameters, which will be added to Kea in a version after 1.0.

The DHCPv4 server will load the library and execute the callouts each time a
request is received.
941

942 943 944 945
@note All the above assumes that the hooks library will be used with a
version of Kea that is dynamically-linked.  For information regarding
running hooks libraries against a statically-linked Kea, see @ref
hooksdgStaticallyLinkedKea.
946

947
@section hooksdgAdvancedTopics Advanced Topics
948

949

950
@subsection hooksdgContextCreateDestroy Context Creation and Destruction
951 952 953 954 955 956 957 958 959

As well as the hooks defined by the server, the hooks framework defines
two hooks of its own, "context_create" and "context_destroy".  The first
is called when a request is created in the server, before any of the
server-specific hooks gets called.  It's purpose it to allow a library
to initialize per-request context. The second is called after all
server-defined hooks have been processed, and is to allow a library to
tidy up.

960
As an example, the "pkt4_send" example above required that the code
961 962 963 964
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
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,
965
"pkt4_send" would be guaranteed to get something when looking for
966 967
the hwaddr item and so could write or not write the output depending on
the value.
968 969 970 971 972 973

In most cases, "context_destroy" is not needed as the Hooks system
automatically deletes context. An example where it could be required
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
destruction of the context, that memory will not be automatically
974
released. Freeing in the memory in the "context_destroy" callout will solve
975 976 977
that problem.

Actually, when the context is destroyed, the destructor
978 979 980 981
associated with any objects stored in it are run. Rather than point to
allocated memory with a raw pointer, a better idea would be to point to
it with a boost "smart" pointer and store that pointer in the context.
When the context is destroyed, the smart pointer's destructor is run,
982
which will automatically delete the pointed-to object.
983

984 985 986 987 988
These approaches are illustrated in the following examples.
Here it is assumed that the hooks library is performing some form of
security checking on the packet and needs to maintain information in
a user-specified "SecurityInformation" object. (The details of this
fictitious object are of no concern here.) The object is created in
989 990
the "context_create" callout and used in both the "pkt4_receive" and the
"pkt4_send" callouts.
991

992 993
@code
// Storing information in a "raw" pointer.  Assume that the
994

995 996 997 998
#include <hooks/hooks.h>
   :

extern "C" {
999

1000 1001 1002 1003 1004 1005 1006 1007 1008
// context_create callout - called when the request is created.
int context_create(CalloutHandle& handle) {
    // Create the security information and store it in the context
    // for this packet.
    SecurityInformation* si = new SecurityInformation();
    handle.setContext("security_information", si);
}

// Callouts that use the context
1009
int pkt4_receive(CalloutHandle& handle) {
1010
    // Retrieve the pointer to the SecurityInformation object
1011
    SecurityInformation* si;
1012 1013 1014 1015 1016 1017 1018 1019 1020 1021
    handle.getContext("security_information", si);
        :
        :
    // Set the security information
    si->setSomething(...);

    // The pointed-to information has been updated but the pointer has not been
    // altered, so there is no need to call setContext() again.
}

1022
int pkt4_send(CalloutHandle& handle) {
1023
    // Retrieve the pointer to the SecurityInformation object
1024
    SecurityInformation* si;
1025 1026 1027 1028 1029 1030 1031