Commit ef65766b authored by Marcin Siodelski's avatar Marcin Siodelski
Browse files

[5175] Added description of CA in the Developer's Guide.

parent 1a4d847e
......@@ -81,6 +81,11 @@
* - @subpage d2TransDetail
* - @subpage d2StateModel
* - @subpage d2TransExecExample
* - @subpage controlAgent
* - @subpage ctrlAgentHttp
* - @subpage ctrlAgentCreatingResponse
* - @subpage ctrlAgentCommandMgr
* - @subpage CtrlAgentSecurity
* - @subpage lfc
* - @subpage lfcProcessing
* - @subpage lfcFiles
......@@ -25,6 +25,33 @@
found in
<ulink url="">Kea Developer's Guide</ulink>.
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.
<section id="agent-configuration">
......@@ -118,7 +118,10 @@
processing DHCP messages to apply changes to the database). Nevetheless,
these situations are rather rare and, in most cases, when the
<command>service</command> parameter contains a name of the service
the commands are simply forwarded by the CA.
the commands are simply forwarded by the CA. The forwarded command
includes the <command>service</command> parameter but this parameter
is ignored by the receiving server. This parameter is only meaningful
to the CA.
......@@ -131,6 +134,29 @@
DHCPv4 server's configuration and so on.
The following list contains a mapping of the values carried within the
<command>service</command> parameter to the servers to which the commands
are forwarded:
<simpara><command>dhcp4</command> - the command is forwarded to the
<command>kea-dhcp4</command> server,</simpara>
<simpara><command>dhcp6</command> - the command is forwarded to the
<command>kea-dhcp6</command> server,</simpara>
<simpara><command>d2</command> - the command is forwarded to the
<command>kea-d2</command> server.</simpara>
<para>The server processing the incoming command will send a response of
the form:
......@@ -14,7 +14,7 @@ CLEANFILES = *.gcno *.gcda ca_messages.h s-messages
man_MANS = kea-ctrl-agent.8
EXTRA_DIST = $(man_MANS) kea-ctrl-agent.xml
EXTRA_DIST += agent_hooks.dox
EXTRA_DIST += agent.dox agent_hooks.dox
kea-ctrl-agent.8: kea-ctrl-agent.xml
// Copyright (C) 2017 Internet Systems Consortium, Inc. ("ISC")
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at
@page controlAgent Control Agent Component
Kea 1.2 release has introduced the Control Agent component (CA), which
is started by the "kea-ctrl-agent" binary. The CA exposes a RESTful API
which is used by the administrators to manage Kea servers' instances.
In the most typical case, the CA forwards commands received over the
RESTful API to the respetive Kea servers, e.g. DHCPv4 server, DHCPv6
server etc. The communication between the CA and other servers is
established with the use of unix domain sockets. This is possible because
the CA is running on the same system as other Kea services to which
messages are forwarded.
The CA can forward the same command to multiple Kea services and return
an aggregated response (from all services) over the RESTful API. The
"service" parameter included in the client's command can contain one
or multiple services at which the command is targetted. The CA will
iterate over this list and forward the command to each of them
In some cases, the commands containing the "service" value can be handled
directly by the CA. This is usually the case when the CA is running
with hooks libraries attached. The hooks libraries must implement
callouts for the "control_command_receive" hook point, which are
invoked by the CA when the command is received. If the hooks libraries
set the 'skip' status, it is an indication to the CA that the command
has been processed by the CA and simply return a response created by the
hooks libraries to the client. An example of the hooks library attached to
the CA and handling the commands for other services is the library which
stores or retrieves some data from the SQL database.
The "service" parameter is optional. If it is not included in the command
(or it is blank list), it is an indication that the command relates to
CA and that the CA should handle it, e.g. return its own configuration in
response to a "config-get" command.
@section ctrlAgentHttp Receiving commands over HTTP
Control Agent uses libkea-http library to establish HTTP connections,
receive messages and send responses over HTTP. This library uses boost ASIO
for creating TCP connections and asynchronously receive and send the data
over the sockets.
The @ref isc::http::HttpListener provides an entry point to this library.
It is used by the CA to bind the acceptor to the specific address and
port. When the client connects to this address and port, the acceptor's
callback function is invoked which opens new connection and starts
receiving the data over the socket. The @ref isc::http::HttpConnection
implements a logic to read and parse the received data. Each new TCP
connection has a unique instance of the @ref isc::http::HttpConnection
associated. When the portion of data is received (asynchronously) over
the socket the data is provided to the instance of the
@ref isc::http::HttpRequestParser object (unique per connection) and
data parsing is continued until the parser runs out of data or until
the entire HTTP request has been received. The
@ref isc::http::HttpRequestParser signals these events using the
@ref isc::http::HttpRequestParser::needData and
@ref isc::http::HttpRequestParser::httpParseOk respectively.
libkea-http is designed to handle processing messages carrying different
content types. The Control Agent uses "application/json" content
type which describes messages with JSON structures carried within the
message body. The JSON structures represent commands sent to the Kea
server(s) by the controlling clients. libkea-http provides generic classes
(derived from @ref isc::http::HttpRequest) which faciliate validation of
messsages holding various content types.
CA uses @ref isc::http::PostHttpRequestJson, which encapsulate messages
sent using HTTP POST and including JSON content, to represent received messages.
@section ctrlAgentCreatingResponse Creating HTTP responses
The @ref isc::http::HttpResponseCreatorFactory is an interface which should
be implemented by components using libkea-http to generate instances of
the HTTP responses of a desired type. The instance of the factory class is
provided to the @ref isc::http::HttpListener via its constructor. The listener
calls an implementation of the
@ref isc::http::HttpResponseCreatorFactory::create when the new HTTP
message has been received and parsed.
The CA component includes the @ref isc::agent::CtrlAgentResponseCreatorFactory
class. Its @c create() method implementation returns
an instance of the @ref isc::agent::CtrlAgentResponseCreator, which is a
derivation of the @ref isc::http::HttpResponseCreator. This creator creates
instances of the @ref isc::http::HttpResponseJson, holding responses to
the commands in the JSON format.
@section ctrlAgentCommandMgr Handling commands with Command Manager
The @ref isc::agent::CtrlAgentCommandMgr is a derivation of the
@ref isc::config::HookedCommandMgr and adds capability to forward received
(over HTTP) commands to the respective Kea servers. The
@ref isc::agent::CtrlAgentCommandMgr forwards commands over the unix domain
socket, using @ref isc::asiolink::UnixDomainSocket class. All responses
to a particular command (possibly received from multiple Kea servers) are
aggregated within a JSON list and sent back to the controlling client over
In some cases the responses may be generated locally (without forwarding).
Typically, the command will be generated by the CA when the command sent
by the client lacks the "service" parameter, which indicates that the
command is targetted at the CA itself. In some cases the commands can also
be processed by the hooks libraries attached to the CA.
@section CtrlAgentSecurity Security considerations
The Control Agent doesn't provide any mechanisms to secure the communication
over the RESTful API. In the design of the CA we have considered including builtin
HTTPS solutions (HTTP + TLS), making use of crypto libraries supported by Kea.
It was evetually decided to not implement the secure layer within Kea for the following resons:
- additional code complexity which requires maintenance, bug fixing and
monitoring for security vulnerabilities in the OpenSSL/Botan code,
- OpenSSL/Botan code may be awkward to use and it is likely we wouldn't
implement it right,
- need to support two crypto backends: OpenSSL and Botan which puts significant
burden on Kea maintenance.
In the installations where securing command channel is critical (most of the
installations?), a reverse HTTP proxy can be setup using one of the third
party HTTP server implementations, e.g. Apache, nginx etc.
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment