mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-30 21:45:37 +00:00
Code Issues Releases Wiki Activity

[5175] Added Guide sections about Control Agent.

Browse Source
This commit is contained in:
Marcin Siodelski
2017-03-31 12:51:20 +02:00
parent c13adb8da7
commit ca5c01ea3b
4 changed files with 337 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

178
doc/guide/agent.xml Normal file
View File

@@ -0,0 +1,178 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash "&#x2017;" >
]>
<chapter id="kea-ctrl-agent">
<title>Kea Control Agent</title>
<section id="agent-overview">
<title>Overview</title>
<para>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
<xref linkend="ctrl-channel"/>.</para>
<para>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
<ulink url="https://jenkins.isc.org/job/Kea_doc/doxygen/">Kea Developer's Guide</ulink>.
</para>
</section>
<section id="agent-configuration">
<title>Configuration</title>
<para>The following example demonstrates the basic CA configuration.</para>
<para>
<screen>
{
"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"
} ]
}
}</screen>
</para>
<warning>
<simpara>
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 <filename>etc/kea/kea-ca.conf</filename>. In the Kea 1.2 final
release the CA configuration will be merged into the default
<filename>etc/kea/kea.conf.</filename>
</simpara>
</warning>
<para>
The <command>http-host</command> and <command>http-port</command>
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
<command>http://10.20.30.40:8080/</command>. If these parameters
are not specified, the default URL is http://127.0.0.1:8000/
</para>
<para>
It has been mentioned in the <xref linkend="agent-overview"/> that
CA can forward some received commands to the respective Kea servers for
processing. For example, <command>config-get</command> is sent to
retrieve configuration of one of the Kea services. When CA receives
this command, including a <command>service</command> 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 <command>service</command> parameter and general structure of
the commands can be found in <xref linkend="ctrl-channel"/>.
</para>
<para>
The CA uses unix domain sockets to forward control commands and receive
responses from other Kea services. The <command>dhcp4-server</command>,
<command>dhcp6-server</command> and <command>d2-server</command> 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 <filename>/path/to/the/unix/socket-v4</filename> 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 <xref linkend="dhcp4-ctrl-channel"/> and the
<xref linkend="dhcp6-ctrl-channel"/> to learn how the socket
configuration is specified for the DHCPv4 and DHCPv6 services.
</para>
<para>
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
<command>hooks-libraries</command> list contains hooks libraries
that should be loaded by the CA, along with their configuration
information specified with <command>parameters</command>.
</para>
<para>
Please consult <xref linkend="logging"/> for the details how to
configure logging. The CA's root logger's name is
<command>kea-ctrl-agent</command> as given in the example above.
</para>
</section>
<section id="agent-secure-connection">
<title>Secure Connections</title>
<para>
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.
</para>
</section>
<section id="agent-limitations">
<title>Control Agent Limitations</title>
<para>
Control Agent is a new component, first released in Kea 1.2 beta. In
this release it comes with two notable limitations:
<itemizedlist>
<listitem>
<simpara>
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 <filename>etc/kea/kea-ca.conf</filename>.
</simpara>
</listitem>
<listitem>
<simpara>
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
<xref linkend="agent-launch"/>
</simpara>
</listitem>
</itemizedlist>
</para>
</section>
<section id="agent-launch">
<title>Starting Control Agent</title>
<para>
The CA is started by running its binary and specifying the configuration file
it should use. For example:
<screen>
$ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ca.conf
</screen>
</para>
</section>
</chapter>

160
doc/guide/ctrl-channel.xml
View File

@@ -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.</para>
<para>Currently the only supported type of control channel
is UNIX stream socket. For details how to configure it, see
<xref linkend="dhcp4-ctrl-channel" /> and <xref
linkend="dhcp6-ctrl-channel" />. It is likely that support
for other control channel types will be added in the future.
<para>The DHCPv4 and DHCPv6 servers receive commands over the
unix domain sockets. The details how to configure these sockets,
see <xref linkend="dhcp4-ctrl-channel" /> and <xref
linkend="dhcp6-ctrl-channel" />. 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.</para>
<para>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
<xref linkend="agent-configuration"/>.</para>
<para>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
<command>service</command> parameter of the received command.
If the <command>service</command> 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.
</para>
<section id="ctrl-channel-syntax">
@@ -44,6 +70,7 @@
<screen>
{
"command": "foo",
"service": [ "dhcp4" ]
"arguments": {
"param1": "value1",
"param2": "value2",
@@ -52,13 +79,60 @@
}
</screen>
The same command sent over the RESTful interface to the CA will have
the following structure.
<screen>
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",
...
}
}
</screen>
<command>command</command> is the name of command to execute and
is mandatory. <command>arguments</command> is a map of parameters
required to carry out the given command. The exact content and
format of the map is command specific.</para>
<para>The server will process the incoming command and then send a
response of the form:
<para>
<command>service</command> 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
<command>service</command> parameter contains a name of the service
the commands are simply forwarded by the CA.
</para>
<para>
If the command received by the CA does not include a <command>service</command>
parameter or this list is empty, the CA will simply process this message
on its own. For example, the <command>config-get</command> command which
doesn't include service parameter will return Control Agent's own
configuration. The <command>config-get</command> including a service
value "dhcp4" will be forwarded to the DHCPv4 server and will return
DHCPv4 server's configuration and so on.
</para>
<para>The server processing the incoming command will send a response of
the form:
<screen>
{
"result": 0|1,
@@ -79,23 +153,29 @@
<command>arguments</command> 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.</para>
<note>
<simpara>
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.
</simpara>
</note>
</section>
<section id="ctrl-channel-client">
<title>Using the Control Channel</title>
<para>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.</para>
<para>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 <command>socat</command> and <command>curl</command>.</para>
<para>The easiest way is to use a tool called <command>socat</command>,
a tool available from <ulink url="http://www.dest-unreach.org/socat/">socat
homepage</ulink>, 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:
<para>In order to control the given Kea service via unix domain socket, use
<command>socat</command> as follows:
<screen>
$ socat UNIX:/path/to/the/kea/socket -
</screen>
@@ -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.</para>
<para>In order to use Kea's RESTful API with <command>curl</command> try the
following:
<screen>
$ curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get", "service": [ "dhcp4" ] }' http://ca.example.org:8000/
</screen>
This assumes that the Control Agent is running on host
<filename>ca.example.org</filename> and runs RESTful service on port 8000.
</para>
</section>
<section id="commands-common">
@@ -404,4 +494,36 @@ will be sent to Kea and the responses received from Kea printed to standard outp
</section> <!-- end of commands supported by both servers -->
<section id="agent-commands">
<title>Commands Supported by Control Agent</title>
<para>The following commands listed in <xref linkend="commands-common"/>
are also supported by the Control Agent, i.e. when the
<command>service</command> parameter is blank the commands are handled
by the CA and they relate to the CA process itself:
<itemizedlist>
<listitem>
<simpara>build-report</simpara>
</listitem>
<listitem>
<simpara>config-get</simpara>
</listitem>
<listitem>
<simpara>config-test</simpara>
</listitem>
<listitem>
<simpara>config-write</simpara>
</listitem>
<listitem>
<simpara>list-commands</simpara>
</listitem>
<listitem>
<simpara>shutdown</simpara>
</listitem>
<listitem>
<simpara>version-get</simpara>
</listitem>
</itemizedlist>
</para>
</section>
</chapter>

2
doc/guide/kea-guide.xml
View File

@@ -64,6 +64,8 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="keactrl.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="agent.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp4-srv.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp6-srv.xml" />

16
doc/guide/logging.xml
View File

@@ -181,6 +181,22 @@
Currently defined loggers are:
</para>
<itemizedlist>
<listitem>
<simpara>
<command>kea-ctrl-agent</command> - the root logger for the
Control Agent exposing RESTful control API. All components used
by the Control Agent inherit the settings from this logger.
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-ctrl-agent.http</command> - a logger which outputs
log messages related to receiving, parsing and sending HTTP
messages.
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-dhcp4</command> - the root logger for the DHCPv4