A classic approach to daemon configuration assumes that the server's configuration is stored in configuration files and, when the configuration is changed, the daemon is restarted. This approach has the significant disadvantage of introducing periods of downtime, when client traffic is not handled. Another risk is that if the new configuration is invalid for whatever reason, the server may refuse to start, which will further extend the downtime period until the issue is resolved. To avoid such problems, both the DHCPv4 and DHCPv6 servers include support for a mechanism that allows on-line reconfiguration without requiring server shutdown. Both servers can be instructed to open control sockets, which is a communication channel. The server is able to receive commands on that channel, act on them and report back status. While the set of commands in Kea 1.2.0 is limited, the number is expected to grow over time. The DHCPv4 and DHCPv6 servers receive commands over the unix domain sockets. The details how to configure these sockets, see and . While it is possible control the servers directly using unix domain sockets it requires that the controlling client be running on the same machine as the server. In order to connect remotely SSH is usually used to connect to the controlled machine. The network administrators usually prefer using some form of a RESTful API to control the servers, rather than using unix domain sockets directly. Therefore, as of Kea 1.2.0 release, Kea includes a new component called Control Agent (or CA) which exposes a RESTful API to the controlling clients and can forward commands to the respective Kea services over the unix domain sockets. The CA configuration has been described in . The HTTP requests received by the CA contain the control commands encapsulated within HTTP requests. Simply speaking, the CA is responsible for stripping the HTTP layer from the received commands and forwarding the commands in a JSON format over the unix domain sockets to respective services. Because the CA receives commands for all services it requires additional "forwarding" information to be included in the client's messages. This "forwarding" information is carried within the service parameter of the received command. If the service parameter is not included or if the parameter is a blank list the CA will assume that the control command is targetted at the CA itself and will try to handle it on its own. Control connections over both HTTP and unix domain sockets are guarded with timeouts. The default timeout value is set to 10s and is not configurable. The timeout configuration will be implemented in the future. Kea 1.2.0 release and earlier had a limitation of 64kB on the maximum size of a command and a response sent over the unix domain socket. This limitation has been removed in Kea 1.3.0 release.

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", "service": [ "dhcp4" ] "arguments": { "param1": "value1", "param2": "value2", ... } } The same command sent over the RESTful interface to the CA will have the following structure. POST / HTTP/1.1\r\n Content-Type: application/json\r\n Content-Length: 147\r\n\r\n { "command": "foo", "service": [ "dhcp4" ] "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. service is a list of the servers at which the control command is targetted. In the example above, the control command is targetted at the DHCPv4 server. In most cases, the CA will simply forward this command to the DHCPv4 server for processing via unix domain socket. Sometimes, the command including a service value may also be processed by the CA, if the CA is running a hooks library which handles such command for the given server. As an example, the hooks library loaded by the CA may perform some operations on the database (like adding host reservations, modifying leases etc.). An advantage of performing DHCPv4 specific administrative operations in the CA rather than forwarding it to the DHCPv4 server is the ability to perform these operations without disrupting the DHCPv4 service (DHCPv4 server doesn't have to stop processing DHCP messages to apply changes to the database). Nevertheless, these situations are rather rare and, in most cases, when the service parameter contains a name of the service the commands are simply forwarded by the CA. The forwarded command includes the service parameter but this parameter is ignored by the receiving server. This parameter is only meaningful to the CA. If the command received by the CA does not include a service parameter or this list is empty, the CA will simply process this message on its own. For example, the config-get command which doesn't include service parameter will return Control Agent's own configuration. The config-get including a service value "dhcp4" will be forwarded to the DHCPv4 server and will return DHCPv4 server's configuration and so on. The following list contains a mapping of the values carried within the service parameter to the servers to which the commands are forwarded: dhcp4 - the command is forwarded to the kea-dhcp4 server, dhcp6 - the command is forwarded to the kea-dhcp6 server, d2 - the command is forwarded to the kea-d2 server. The server processing the incoming command will send a response of the form: { "result": 0|1|2|3, "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 or at least a failure to complete the requested action. Currently 1 is used as a generic error, 2 means that a command is not supported and 3 means that the requested operation was completed, but the requested object was not found. Additional error codes may be added in the future. For example a well formed command that requests a subnet that exists in server's configuration would return result 0. If the server encounters an error condition, it would return 1. If the command was asking for IPv6 subnet, but was sent to DHCPv4 server, it would return 2. If the query was asking for a subnet-id and there is no subnet with such id, the result would be set to 3. The text field typically appears when result is non-zero and contains a description of the error encountered, but it often also appears for successful outcomes. The exact text is command specific, but in general uses plain English to describe the outcome of the command. arguments is a map of additional data values returned by the server which is specific to the command issued. The map is may be present, but that depends on specific command. When sending commands via Control Agent, it is possible to specify multiple services at which the command is targetted. CA will forward this command to each service individually. Thus, the CA response to the controlling client will contain an array of individual responses.

Kea development team is actively working on providing client applications which can be used to control the servers. These applications are, however, in the early stages of development and as of Kea 1.2.0 release have certain limitations. The easiest way to start interacting with the control API is to use common Unix/Linux tools such as socat and curl. In order to control the given Kea service via unix domain socket, use socat in interactive mode as follows: $ socat UNIX:/path/to/the/kea/socket - or in batch mode, include the "ignoreeof" option as shown below to ensure socat waits long enough for the server to respond: $ echo "{ some command...}" | socat UNIX:/path/to/the/kea/socket -,ignoreeof 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. This approach communicates with the specific server directly and bypasses Control Agent. It is also easy to open UNIX socket programmatically. 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. In order to use Kea's RESTful API with curl you may use the following: $ curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get", "service": [ "dhcp4" ] }' http://ca.example.org:8000/ This assumes that the Control Agent is running on host ca.example.org and runs RESTful service on port 8000.

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" }

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 config-set 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" }

The config-reload command instructs Kea to load again the configuration file that was used previously. This operation is useful if the configuration file has been changed by some external sources. For example, a sysadmin can tweak the configuration file and use this command to force Kea pick up the changes. Caution should be taken when mixing this with config-set commands. Kea remembers the location of the configuration file it was started with. This configuration can be significantly changed using config-set command. When config-reload is issued after config-set, Kea will attempt to reload its original configuration from the file, possibly losing all changes introduced using config-set or other commands. config-reload does not take any parameters. An example command invocation looks like this: { "command": "config-reload" }

The config-test command instructs the server to check whether the new configuration supplied in the command's arguments can be loaded. The supplied configuration is expected to be the full configuration for the target server along with an optional Logger configuration. As for the -t command some sanity checks are not performed so it is possible a configuration which successfully passes this command will still fail in config-set command or at launch time. The structure of the command is as follows: { "command": "config-test", "arguments": { "<server>": { }, "Logging": { } } } where <server> is the configuration element name for a given server such as "Dhcp4" or "Dhcp6". For example: { "command": "config-test", "arguments": { "Dhcp6": { : }, "Logging": { : } } } 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 seems sane..." } or {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }

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. If relative path is specified, Kea will write its files only in the directory it is running. An example command invocation looks like this: { "command": "config-write", "arguments": { "filename": "config-modified-2017-03-15.json" } }

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).

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.

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.

The config-set 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": "config-set", "arguments": { "<server>": { }, "Logging": { } } } where <server> is the configuration element name for a given server such as "Dhcp4" or "Dhcp6". For example: { "command": "config-set", "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)" }

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" } The server will respond with a confirmation that the shutdown procedure has been initiated.

The dhcp-disable command globally disables the DHCP service. The server continues to operate, but it drops all received DHCP messages. This command is useful when the server's maintenance requires that the server temporarily stops allocating new leases and renew existing leases. It is also useful in failover like configurations during a synchronization of the lease databases at startup or recovery after a failure. The optional parameter max-period specifies the time in seconds after which the DHCP service should be automatically re-enabled if the dhcp-enable command is not sent before this time elapses. { "command": "dhcp-disable", "arguments": { "max-period": 20 } }

The dhcp-enable command globally enables the DHCP service. { "command": "dhcp-enable" }

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" }

The following commands listed in are also supported by the Control Agent, i.e. when the service parameter is blank the commands are handled by the CA and they relate to the CA process itself: build-report config-get config-test config-write list-commands shutdown version-get