diff --git a/doc/guide/agent.xml b/doc/guide/agent.xml
new file mode 100644
index 0000000000..00bb9416a8
--- /dev/null
+++ b/doc/guide/agent.xml
@@ -0,0 +1,178 @@
+
+
+]>
+
+
+ Kea Control Agent
+
+
+ Overview
+ Kea Control Agent (CA) is a daemon, first included in Kea 1.2, which
+ exposes RESTful control interface for managing Kea servers. The deamon
+ 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. 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.
+
+
+
+
+ Configuration
+ 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 beta 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 some received commands to the respective 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 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 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.
+
+
+
+
+ Secure Connections
+
+ 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 Limitations
+
+ Control Agent is a new component, first released in Kea 1.2 beta. 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
+
+
+
+
+
+
+
+
+ Starting Control Agent
+
+ 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
+
+
+
+
diff --git a/doc/guide/ctrl-channel.xml b/doc/guide/ctrl-channel.xml
index 266282ff39..e1a816c2d4 100644
--- a/doc/guide/ctrl-channel.xml
+++ b/doc/guide/ctrl-channel.xml
@@ -24,14 +24,40 @@
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.1.0 is limited,
+ While the set of commands in Kea 1.2.0 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.
+ 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 is either 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 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.
@@ -44,6 +70,7 @@
{
"command": "foo",
+ "service": [ "dhcp4" ]
"arguments": {
"param1": "value1",
"param2": "value2",
@@ -52,13 +79,60 @@
}
+ 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.
- The server will process the incoming command and then send a
- response of the form:
+
+ 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 attached to 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). Nevetheless,
+ 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.
+
+
+
+ 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 server processing the incoming command will send a response of
+ the form:
{
"result": 0|1,
@@ -79,23 +153,29 @@
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.
+
+
+
+ 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 separatelly. Thus, the CA response to the
+ controlling client will contain an array of individual responses.
+
+
+
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.
+ Kea development team is actively working on the providing implementations
+ of the client applications which can be used to control the servers. However,
+ these clients have certain limitations as of Kea 1.2.0 release. The easiest
+ way to start playing with the control API is to use common Unix/Linux tools
+ such as socat and curl.
- 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:
+ In order to control the given Kea service via unix domain socket, use
+ socat as follows:
$ socat UNIX:/path/to/the/kea/socket -
@@ -108,6 +188,16 @@ will be sent to Kea and the responses received from Kea printed to standard outp
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 try 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.
+
+
@@ -404,4 +494,36 @@ will be sent to Kea and the responses received from Kea printed to standard outp
+
+ Commands Supported by Control Agent
+ 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
+
+
+
+
+
diff --git a/doc/guide/kea-guide.xml b/doc/guide/kea-guide.xml
index de59667525..430c9a0033 100644
--- a/doc/guide/kea-guide.xml
+++ b/doc/guide/kea-guide.xml
@@ -64,6 +64,8 @@
+
+
diff --git a/doc/guide/logging.xml b/doc/guide/logging.xml
index 315c9822b4..6b871e2366 100644
--- a/doc/guide/logging.xml
+++ b/doc/guide/logging.xml
@@ -181,6 +181,22 @@
Currently defined loggers are:
+
+
+ kea-ctrl-agent - the root logger for the
+ Control Agent exposing RESTful control API. All components used
+ by the Control Agent inherit the settings from this logger.
+
+
+
+
+
+ kea-ctrl-agent.http - a logger which outputs
+ log messages related to receiving, parsing and sending HTTP
+ messages.
+
+
+
kea-dhcp4 - the root logger for the DHCPv4