[5175] Added Guide sections about Control Agent.

doc/guide/agent.xml

@@ -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>

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.</para>
 
-    <para>Currently the only supported type of control channel
+    <para>The DHCPv4 and DHCPv6 servers receive commands over the
-    is UNIX stream socket. For details how to configure it, see
+    unix domain sockets. The details how to configure these sockets,
-    <xref linkend="dhcp4-ctrl-channel" /> and <xref
+    see <xref linkend="dhcp4-ctrl-channel" /> and <xref
-    linkend="dhcp6-ctrl-channel" />. It is likely that support
+    linkend="dhcp6-ctrl-channel" />. While it is possible control
-    for other control channel types will be added in the future.
+    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
+    <para>
-    response of the form:
+      <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
+    <para>Kea development team is actively working on the providing implementations
-    reason for this is the expectation is that the entity using the control channel
+    of the client applications which can be used to control the servers. However,
-    is typically an IPAM or similar network management/monitoring software which
+    these clients have certain limitations as of Kea 1.2.0 release. The easiest
-    may have quite varied expectations regarding the client and is even likely to
+    way to start playing with the control API is to use common Unix/Linux tools
-    be written in languages different than C or C++. Therefore only examples are provided to show
+    such as <command>socat</command> and <command>curl</command>.</para>
-    how one can take advantage of the API.</para>
+
-
+    <para>In order to control the given Kea service via unix domain socket, use
-    <para>The easiest way is to use a tool called <command>socat</command>,
+    <command>socat</command> as follows:
-    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:
 <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>

doc/guide/kea-guide.xml

@@ -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" />

doc/guide/logging.xml

@@ -183,6 +183,22 @@
         <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
               server. All components used by the DHCPv4 server inherit the
               settings from this logger.