Kea 2.7.4
|
Welcome to Kea Stat Commands Hooks Library. This documentation is addressed to developers who are interested in the internal operation of the Stat Commands library. This file provides information needed to understand and perhaps extend this library.
This documentation is stand-alone: you should have read and understood the Kea Developer's Guide and in particular its section about hooks.
Stat Commands (or stat_cmds) is a Hook library that can be loaded by either kea-dhcp4 and kea-dhcp6 servers to extend them with additional statistics mechanisms.
The initial purpose of this library is provide supplemental commands for obtaining accurate lease statistics in deployments that share lease storage between multiple Kea DHCP servers. It is likely that additional statistics related commands will be added to this library in future releases as use cases for them arise.
The library is structured around command handlers. When the library is loaded it registers handlers for new commands. When a command is issued (be it directly via control channel or indirectly via REST interface from control agent), the code receives a JSON command with parameters. The command is routed the appropriate handler, its parameters are parsed and command executed accordingly. Lastly, a response is constructed and shipped back to the client.
This lease statistics commands interact with both the isc::dhcp::StatsMgr and the isc::dhcp::LeaseMgr instance. At the time of writing this text (May, 2018), Kea supports four types of lease managers: memfile, MySQL or PostgreSQL. The lease statistics commands provided by this library provide a unified interface supported by all four of these backends.
As with other hooks, this one keeps its code in a separate namespace which corresponds to the file name of the library: isc::stat_cmds.
For background on the design and design choices please refer to: Shared Lease Stats Design
Library operation starts with Kea calling the load() function (file stat_cmds_callouts.cc). This function registers the command callout functions for each of the libraries commands. For a list, see isc::stat_cmds::StatCmds class documentation. This class uses the Pimpl design pattern, and thus the actual implementation is hidden in isc::stat_cmds::LeaseStatCmdsImpl.
Unlike similar libraries, the Pimpl class is differentiated from the the StatCmds class by the prefix "Lease" and it is instantiated in the outer handler (e.g. isc::stat_cmds::StatCmds::statLease4GetHandler) rather than the StatCmds constructor. This was done in the event that commands, unrelated to lease statistics, are added to this library and that would be better served by Pimpl derivations specific to them.
There are two shared lease statistic commands, "stat-lease4-get" and "stat-lease6-get". Both of these support the same input parameters and have their own command handlers:
Briefly, the commands are intended to fetch the lease statistics per subnet for the range of subnets described by the input parameters. JSON text structure of the commands is as follows:
DHCPv4 command:
DHCPv6 command:
Command handling for both commands is symmetrical consists of the following steps:
DHCPv4 functions:
DHCPv6 functions:
A DHCPv4 response might look like this:
and DHCPv6 response might look like this:
The Stat Commands Hook library is compatible with multi-threading. All commands are executed inside a critical section, i.e. with threads stopped. It makes sense to not have lease state changes when retrieving lease counts.