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
|
// Copyright (C) 2017-2022 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 agentHooks The Hooks API for the Control Agent
@section agentHooksIntroduction Introduction
The Kea Control Agent features "Hooks" API that allows the user-written
code to be integrated with the Control Agent and handle some
of the control commands. The hooks library can be either used to provide
support for the new commands (not supported natively by the Control Agent)
or "override" implementation of the existing handlers. The hooks library
signals to the Control Agent that it has processed the given command by
setting "next step status" value to SKIP.
The hooks library can also be used to perform some additional tasks
related to reception of the control command instead of handling it, e.g.
logging or notifying some external service about reception of the
command.
@section agentHooksHookPoints Hooks in the Control Agent
@subsection agentHooksAuth auth
- @b Arguments:
- name: @b request, type: isc::http::HttpRequestPtr, direction: <b>in/out</b>
- name: @b response, type: isc::http::HttpResponseJsonPtr, direction: <b>in/out</b>
- @b Description: this callout is executed when Control Agent receives a
control command over the RESTful interface (HTTP).
The "request" argument is a pointer to the request, in fact a
PostHttpRequestJsonPtr. The "response" argument is the response in case
of errors. The purpose of this callout is to implement authentication
and authorization. It is called after basic HTTP authentication.
The next step status is used only to ask to reset the handle: if the
response is set the processing will stop and the response is returned.
In particular the command is not forwarded.
@subsection agentHooksResponse response
- @b Arguments:
- name: @b request, type: isc::http::HttpRequestPtr, direction: <b>in</b>
- name: @b response, type: isc::http::HttpResponseJsonPtr, direction: <b>in/out</b>
- @b Description: this callout is executed when Control Agent executed
a control command over the RESTful interface (HTTP).
The "request" argument is a pointer to the request. It is used as a
reference and for callout contexts. The "response" argument is the
response which will be sent back to the requesting client. It is
called after command processing. The next step status is ignored:
the response possibly modified will be sent back.
@section agentHooksHandle Handle and hook unload
The callout handle attached to the "request" argument can keep a pointer
to the hook address space which prevents the hook to be unloaded
when the "config-get" or "config-reload" command is executed.
The "next step status" of the "auth" callout point can be set to any
value other than CONTINUE to ask the callout handle to be reset. This
must be done when the command is "config-get" or "config-reload" or
when the "response" callout point is not used or when the callout
context does not transmit values between the "auth" and "response"
callout points.
*/
|
