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.

Hooks in the Control Agent

auth

Arguments:
- name: request, type: isc::http::HttpRequestPtr, direction: in/out
- name: response, type: isc::http::HttpResponseJsonPtr, direction: in/out
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.

response

Arguments:
- name: request, type: isc::http::HttpRequestPtr, direction: in
- name: response, type: isc::http::HttpResponseJsonPtr, direction: in/out
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.

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.