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 loaded by 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": { "comment": "main server", "socket-type": "unix", "socket-name": "/path/to/the/unix/socket-v4" }, "dhcp6": { "socket-type": "unix", "socket-name": "/path/to/the/unix/socket-v4", "user-context": { "version": 3 } } }, "hooks-libraries": [ { "library": "/opt/local/control-agent-commands.so", "parameters": { "param1": "foo" } } ] }, "Logging": { "loggers": [ { "name": "kea-ctrl-agent", "severity": "INFO" } ] } } 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, dhcp6 and d2 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. We have renamed "dhcp4-server", "dhcp6-server" and "d2-server" to "dhcp4", "dhcp6" and "d2" respectively after release of Kea 1.2. If you are migrating from Kea 1.2 you need to tweak your CA config to use this new naming convention. We have made this incompatible change to facilitate future use cases where it will be possible to specify additional values of the "service" parameter to point to the particular instances of the Kea servers, e.g. "dhcp4/3" pointing to the 3rd instance of the DHCPv4 server in the multi-processed configuration. This is not yet supported but the current renaming lays the ground for it. User contexts can store arbitrary data as long as it is valid JSON syntax and its top level element is a map (i.e. the data must be enclosed in curly brackets). Some hook libraries may expect specific formatting, though. Please consult specific hook library documentation for details. User contexts can be specified on either global scope, control socket and loggers. One other useful usage is the ability to store comments or descriptions: the parser translates a "comment" entry into a user-context with the entry, this allows to attach a comment inside the configuration itself. Hooks libraries can be loaded by 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. Kea has been tested with two major HTTP server implentations working as a reverse proxy: Apache2 and nginx. Example configurations including extensive comments are provided in the doc/examples/https/ directory. The reverse proxy forwards HTTP requests received over secure connection to the Control Agent using (not secured) HTTP. Typically, the reverse proxy and the Control Agent are running on the same machine, but it is possible to configure them to run on separate machines as well. In this case, security depends on the protection of the communications between the reverse proxy and the Control Agent. Apart from providing the encryption layer for the control channel, a reverse proxy server is also often used for authentication of the controlling clients. In this case, the client must present a valid certificate when it connects via reverse proxy. The proxy server authenticates the client by checking if the presented certificate is signed by the certificate authority used by the server. To illustrate this, we provide a sample configuration for the nginx server running as a reverse proxy to the Kea Control Agent. The server enables authentication of the clients using certificates. # The server certificate and key can be generated as follows: # # openssl genrsa -des3 -out kea-proxy.key 4096 # openssl req -new -x509 -days 365 -key kea-proxy.key -out kea-proxy.crt # # The CA certificate and key can be generated as follows: # # openssl genrsa -des3 -out ca.key 4096 # openssl req -new -x509 -days 365 -key ca.key -out ca.crt # # # The client certificate needs to be generated and signed: # # openssl genrsa -des3 -out kea-client.key 4096 # openssl req -new -key kea-client.key -out kea-client.csr # openssl x509 -req -days 365 -in kea-client.csr -CA ca.crt \ # -CAkey ca.key -set_serial 01 -out kea-client.crt # # Note that the 'common name' value used when generating the client # and the server certificates must differ from the value used # for the CA certificate. # # The client certificate must be deployed on the client system. # In order to test the proxy configuration with 'curl' run # command similar to the following: # # curl -k --key kea-client.key --cert kea-client.crt -X POST \ # -H Content-Type:application/json -d '{ "command": "list-commands" }' \ # https://kea.example.org/kea # # # # nginx configuration starts here. events { } http { # HTTPS server server { # Use default HTTPS port. listen 443 ssl; # Set server name. server_name kea.example.org; # Server certificate and key. ssl_certificate /path/to/kea-proxy.crt; ssl_certificate_key /path/to/kea-proxy.key; # Certificate Authority. Client certificate must be signed by the CA. ssl_client_certificate /path/to/ca.crt; # Enable verification of the client certificate. ssl_verify_client on; # For URLs such as https://kea.example.org/kea, forward the # requests to http://127.0.0.1:8080. location /kea { proxy_pass http://127.0.0.1:8080; } } } Note that the configuration snippet provided above is for testing purposes only. Consult security policies and best practices of your organization which apply to this setup. When you use an HTTP client without TLS support as kea-shell you can use an HTTP/HTTPS translator such as stunnel in client mode. A sample configuration is provided in the doc/examples/https/shell/ directory

Control Agent is a new component, first released in Kea 1.2. In this release it comes with one notable limitation: 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-ctrl-agent.conf

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