%version; ]> A classic approach to daemon configuration assumes that the server's configuration is stored in the 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 DHCPv4 and DHCPv6 servers introduced support for a mechanism that will allow 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 supported in Kea 0.9.2 is limited, the number is expected to grow over time. Currently the only supported type of control channel is UNIX stream socket. For details how to configure it, see and . It is likely that support for other control channel types will be added in the future.

Communication over control channel is conducted using JSON structures. If configured, Kea will open a socket and will listen for any 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 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.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's command specific. arguments is a map of additional data values returned by the server, specific to the command issued. The map is always present, even if it contains no data values.

ISC does not provide a client for using control channel. The primary reason for that is the expectation is that the entity using 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 we only provide examples 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. 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.

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.

shutdown command instructs the server to initiate its shutdown procedure. It is the equivalent of sending a SIGTERM singal 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.