1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
|
// Copyright (C) 2021 Internet Systems Consortium, Inc. ("ISC")
//
// 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/.
/**
@page d2Hooks The Hooks API for the Kea DHCP DDNS (D2)
@section d2HooksIntroduction Introduction
Kea features an API (the "Hooks" API) that allows user-written code to
be integrated into Kea and called at specific points in its processing.
An overview of the API and a tutorial for writing such code can be found in
the @ref hooksdgDevelopersGuide. It also includes information how hooks
framework can be used to implement additional control commands for
Kea DHCP DDNS. Information for Kea maintainers can be found in the
@ref hooksComponentDeveloperGuide.
This manual is more specialized and is aimed at developers of hook
code for Kea DHCP DDNS. It describes each hook point, what the callouts
attached to the hook are able to do, and the arguments passed to the
callouts. Each entry in this manual has the following information:
- Name of the hook point.
- Arguments for the callout. As well as the argument name and data type, the
information includes the direction, which can be one of:
- @b in - the server passes values to the callout but ignored any data
returned.
- @b out - the callout is expected to set this value.
- <b>in/out</b> - the server passes a value to the callout and uses whatever
value the callout sends back. Note that the callout may choose not to
do any modification, in which case the server will use whatever value
it sent to the callout.
- Description of the hook. This explains where in the processing the hook
is located, the possible actions a callout attached to this hook could take,
and a description of the data passed to the callouts.
- Next step status: the action taken by the server when a callout chooses to set
status to specified value. Actions not listed explicitly are not supported.
If a callout sets status to unsupported value, this specific value will be
ignored and treated as if the status was CONTINUE.
@section d2HooksHookPoints Hooks in Kea DHCP DDNS
The following list is roughly ordered by appearance of specific hook points during
packet processing, but the exact order depends on the actual processing. Hook points
that are not specific to packet processing (e.g. lease expiration) will be added
to the end of this list.
@subsection d2HooksD2SrvConfigured d2_srv_configured
- @b Arguments:
- name: @b io_context, type: isc::asiolink::IOServicePtr, direction: <b>in</b>
- name: @b json_config, type: isc::data::ConstElementPtr, direction: <b>in</b>
- name: @b server_config, type: isc::d2::D2CfgContextPtr, direction: <b>in</b>
- name: @b error, type: std::string, direction: <b>out</b>
- @b Description: this callout is executed when the server has completed
its (re)configuration. The server provides received and parsed configuration
structures to the hook library. It also provides a pointer to the IOService
object which is used by the server to run asynchronous operations. The hooks
libraries can use this IOService object to schedule asynchronous tasks which
are triggered by the Kea DHCP DDNS's main loop. The hook library should hold
the provided pointer until the library is unloaded. The D2CfgContext
object provides access to the D2 running configuration.
- <b>Next step status</b>: If any callout sets the status to DROP, the server
considers the configuration is incorrect and rejects it using the error
string as an error message.
@subsection d2HooksSelectKey select_key
- @b Arguments:
- name: @b current_server, type: isc::d2::DnsServerInfoPtr, direction: <b>in</b>
- name: @b tsig_key, type: isc::d2::D2TsigKeyPtr, direction: <b>in/out</b>
- @b Description: this callout is executed when the D2 is selecting for
a TSIG key to protect the next DNS update to the already chosen DNS
server. Pointers to the current DNS server and TSIG key are provided.
If a hook library wants to use another TSIG key the pointer must be updated.
- <b>Next step status</b>: If any callout sets the status to a different
value than CONTINUE the current server is skipped.
*/
|
