Management API

Data Syntax Communication over the control channel is conducted using JSON structures. If configured, Kea will open a socket and listen for incoming connections. A process connecting to this socket is expected to send JSON commands structured as follows: { "command": "foo", "arguments": { "param1": "value1", "param2": "value2", ... } } command is the name of command to execute and is mandatory. arguments is a map of parameters required to carry out the given command. The exact content and format of the map is command specific. The server will process the incoming command and then send a response of the form: { "result": 0|1, "text": "textual description", "arguments": { "argument1": "value1", "argument2": "value2", ... } } result indicates the outcome of the command. A value of 0 means success while any non-zero value designates an error. Currently 1 is used as a generic error, but additional error codes may be added in the future. The text field typically appears when result is non-zero and contains a description of the error encountered, but it may also appear for successful results (that is command specific). arguments is a map of additional data values returned by the server which is specific to the command issued. The map is always present, even if it contains no data values.

Using the Control Channel Kea does not currently provide a client for using the control channel. The primary reason for this is the expectation is that the entity using the control channel is typically an IPAM or similar network management/monitoring software which may have quite varied expectations regarding the client and is even likely to be written in languages different than C or C++. Therefore only examples are provided to show how one can take advantage of the API. The easiest way is to use a tool called socat, a tool available from socat homepage, but it is also widely available in Linux and BSD distributions. Once Kea is started, one could connect to the control interface using the following command: $ socat UNIX:/path/to/the/kea/socket - where /path/to/the/kea/socket is the path specified in the Dhcp4/control-socket/socket-name parameter in the Kea configuration file. Text passed to socat will be sent to Kea and the responses received from Kea printed to standard output. It is also easy to open UNIX socket programatically. An example of such a simplistic client written in C is available in the Kea Developer's Guide, chapter Control Channel Overview, section Using Control Channel.

Commands Supported by Both the DHCPv4 and DHCPv6 Servers

build-report The build-report command returns on the control channel what the command line -W argument displays, i.e. the embedded content of the config.report file. This command does not take any parameters. { "command": "build-report" }

config-get The config-get command retrieves the current configuration used by the server. This command does not take any parameters. The configuration returned is roughly equal to the configuration that was loaded using -c command line option during server start-up or later set using set-config command. However, there may be certain differences. Comments are not retained. If the original configuration used file inclusion, the returned configuration will include all parameters from all the included files. Note that returned configuration is not redacted, i.e. it will contain database passwords in plain text if those were specified in the original configuration. Care should be taken to not expose the command channel to unprivileged users. An example command invocation looks like this: { "command": "config-get" }

config-write The config-write command instructs Kea server to write its current configuration to a file on disk. It takes one optional argument called filename that specifies the name of the file to write configuration to. If not specified, the name used when starting Kea (passed as -c argument) will be used. Note that the filename specified must not contain .. or backslashes. Kea should be able to write its files only in the directory it is running and any attempts to step out of that directory will be rejected. An example command invocation looks like this: { "command": "config-write", "parameters": { "filename": "config-modified-2017-03-15.json" } }

leases-reclaim The leases-reclaim command instructs the server to reclaim all expired leases immediately. The command has the following JSON syntax: { "command": "leases-reclaim", "arguments": { "remove": true } } The remove boolean parameter is mandatory and it indicates whether the reclaimed leases should be removed from the lease database (if true), or they should be left in the expired-reclaimed state (if false). The latter facilitates lease affinity, i.e. ability to re-assign expired lease to the same client which used this lease before. See for the details. Also, see for the general information about the processing of expired leases (leases reclamation).

libreload The libreload command will first unload and then load all currently loaded hook libraries. This is primarily intended to allow one or more hook libraries to be replaced with newer versions without requiring Kea servers to be reconfigured or restarted. Note the hook libraries will be passed the same parameter values (if any) they were passed when originally loaded. { "command": "libreload", "arguments": { } } The server will respond with a result of 0 indicating success, or 1 indicating a failure.

list-commands The list-commands command retrieves a list of all commands supported by the server. It does not take any arguments. An example command may look like this: { "command": "list-commands", "arguments": { } } The server will respond with a list of all supported commands. The arguments element will be a list of strings. Each string will convey one supported command.

set-config The set-config command instructs the server to replace its current configuration with the new configuration supplied in the command's arguments. The supplied configuration is expected to be the full configuration for the target server along with an optional Logger configuration. While optional, the Logger configuration is highly recommended as without it the server will revert to its default logging configuration. The structure of the command is as follows: { "command": "set-config", "arguments": { "<server>": { }, "Logging": { } } } where <server> is the configuration element name for a given server such as "Dhcp4" or "Dhcp6". For example: { "command": "set-config", "arguments": { "Dhcp6": { : }, "Logging": { : } } } If the new configuration proves to be invalid the server will retain its current configuration. Please note that the new configuration is retained in memory only. If the server is restarted or a configuration reload is triggered via a signal, the server will use the configuration stored in its configuration file. The server's response will contain a numeric code, "result" (0 for success, non-zero on failure), and a string, "text", describing the outcome: {"result": 0, "text": "Configuration successful." } or {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }

shutdown The shutdown command instructs the server to initiate its shutdown procedure. It is the equivalent of sending a SIGTERM signal to the process. This command does not take any arguments. An example command may look like this: { "command": "shutdown", "arguments": { } } The server will respond with a confirmation that the shutdown procedure has been initiated.

version-get The version-get command returns on the control channel what the command line -v argument displays with in arguments the extended version, i.e., what the command line -V argument displays. This command does not take any parameters. { "command": "version-get" }