The Hooks API for the Kea DHCP DDNS (D2)

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 Hooks Developer's Guide. 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 Guide to Hooks for the Kea Component Developer.

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:
  • in - the server passes values to the callout but ignored any data returned.
  • out - the callout is expected to set this value.
  • in/out - 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.

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.

d2_srv_configured

• Arguments:
  • name: io_context, type: isc::asiolink::IOServicePtr, direction: in
  • name: json_config, type: isc::data::ConstElementPtr, direction: in
  • name: server_config, type: isc::d2::D2CfgContextPtr, direction: in
  • name: error, type: std::string, direction: out
• 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. If the library uses any IO operations, it should create a local IOService object and register it with the IOServiceMgr. This way the local IOService is used by the server to run asynchronous operations. The hooks library can use the local IOService object to schedule asynchronous tasks which are triggered by the D2 server's main loop. The hook library can use the local IOService until the library is unloaded at which stage it must unregister it. The "io_context" parameter gives access to the main IOService, but it's use has been deprecated in favor of a local IOService to avoid issues when unloading the library. The parameter has been deprecated and will be removed in future versions. The D2CfgContext object provides access to the D2 running configuration.
• Next step status: 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.

select_key

• Arguments:
  • name: current_server, type: isc::d2::DnsServerInfoPtr, direction: in
  • name: tsig_key, type: isc::d2::D2TsigKeyPtr, direction: in/out
• 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.
• Next step status: If any callout sets the status to a different value than CONTINUE the current server is skipped.