diff options
Diffstat (limited to 'src/bin/agent/agent_hooks.dox')
| -rw-r--r-- | src/bin/agent/agent_hooks.dox | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/src/bin/agent/agent_hooks.dox b/src/bin/agent/agent_hooks.dox new file mode 100644 index 0000000..be2c833 --- /dev/null +++ b/src/bin/agent/agent_hooks.dox @@ -0,0 +1,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. + +*/ |