]>

Kea Control Agent (CA) is a daemon, first included in Kea 1.2, which exposes a RESTful control interface for managing Kea servers. The daemon can receive control commands over HTTP and either forward these commands to the respective Kea servers or handle these commands on its own. The determination whether the command should be handled by the CA or forwarded is made by checking the value of the 'service' parameter which may be included in the command from the controlling client. The details of the supported commands as well as their structures are provided in . Hook libraries can be attached to the CA to provide support for additional commands or custom behavior of existing commands. Such hook libraries must implement callouts for 'control_command_receive' hook point. Details about creating new hook libraries and supported hook points can be found in Kea Developer's Guide. The CA processes received commands according to the following algorithm: Pass command into any installed hooks (regardless of service value(s)). If the command is handled by a hook, return the response. If the service specifies one more or services, the CA will forward the command to specified services and return the accumulated responses. If service is not specified or is an empty list, the CA will handle the command if it supports it.

The following example demonstrates the basic CA configuration. { "Control-agent": { "http-host": "10.20.30.40", "http-port": 8080, "control-sockets": { "dhcp4-server": { "socket-type": "unix", "socket-name": "/path/to/the/unix/socket-v4" }, "dhcp6-server": { "socket-type": "unix", "socket-name": "/path/to/the/unix/socket-v4" } }, "hooks-libraries": [ { "library": "/opt/local/control-agent-commands.so", "parameters": { "param1": "foo" } } ] }, "Logging": { "loggers": [ { "name": "kea-ctrl-agent", "severity": "INFO" } ] } } In the Kea 1.2 release the Control Agent configuration can't be specified within the same configuration file as DHCPv4, DHCPv6 and D2 configuration. The default configuration file for the CA is installed in the etc/kea/kea-ca.conf. In the Kea 1.2 final release the CA configuration will be merged into the default etc/kea/kea.conf. The http-host and http-port specify an IP address and port to which HTTP service will be bound. In case of the example configuration provided above, the RESTful service will be available under the URL of http://10.20.30.40:8080/. If these parameters are not specified, the default URL is http://127.0.0.1:8000/ It has been mentioned in the that CA can forward received commands to the specific Kea servers for processing. For example, config-get is sent to retrieve configuration of one of the Kea services. When CA receives this command, including a service parameter indicating that the client desires to retrieve configuration of the DHCPv4 server, the CA will forward this command to this server and then pass the received response back to the client. More about the service parameter and general structure of the commands can be found in . The CA uses unix domain sockets to forward control commands and receive responses from other Kea services. The dhcp4-server, dhcp6-server and d2-server maps specify the files to which unix domain sockets are bound. In case of the configuration above, the CA will connect to the DHCPv4 server via /path/to/the/unix/socket-v4 to forward the commands to it. Obviously, the DHCPv4 server must be configured to listen to connections via this same socket. In other words, the command socket configuration for the DHCPv4 server and CA (for this server) must match. Consult the and the to learn how the socket configuration is specified for the DHCPv4 and DHCPv6 services. Hooks libraries can be attached to the Control Agent just like to DHCPv4 and DHCPv6 servers. It currently supports one hook point 'control_command_receive' which makes it possible to delegate processing of some commands to the hooks library. The hooks-libraries list contains the list of hooks libraries that should be loaded by the CA, along with their configuration information specified with parameters. Please consult for the details how to configure logging. The CA's root logger's name is kea-ctrl-agent as given in the example above.

Control Agent doesn't natively support secure HTTP connections like SSL or TLS. In order to setup secure connection please use one of the available third party HTTP servers and configure it to run as a reverse proxy to the Control Agent.

Control Agent is a new component, first released in Kea 1.2. In this release it comes with two notable limitations: CA configuration must be specified in a separate configuration file from the configurations of other components. The default confirguation file for CA is located in etc/kea/kea-ca.conf. keactrl hasn't been updated to manage the Control Agent (start, stop reload). As a result, the CA must be started directly as described in

The CA is started by running its binary and specifying the configuration file it should use. For example: $ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ca.conf

For an example of tool that can take advantage of the RESTful API, see .