.. _ctrl-channel:

**************
Management API
**************

A classic approach to daemon configuration assumes that the server's
configuration is stored in configuration files and, when the
configuration is changed, the daemon is restarted. This approach has the
significant disadvantage of introducing periods of downtime when client
traffic is not handled. Another risk is that if the new configuration is
invalid for any reason, the server may refuse to start, which will
further extend the downtime period until the issue is resolved.

To avoid such problems, the DHCPv4, DHCPv6, and D2 servers in Kea include
support for a mechanism that allows online reconfiguration without
requiring server shutdown. Both servers can be instructed to open
control sockets, which is a communications channel. The server is able
to receive commands on that channel, act on them, and report back
status.

The DHCPv4, DHCPv6, and D2 servers receive commands over the UNIX domain
sockets. For details on how to configure these sockets, see
:ref:`dhcp4-unix-ctrl-channel`, :ref:`dhcp6-unix-ctrl-channel` and
:ref:`d2-unix-ctrl-channel`. While
it is possible to control the servers directly using UNIX domain sockets,
that requires that the controlling client be running on the same machine
as the server. SSH is usually used to connect remotely to the controlled
machine.

Network administrators usually prefer using some form of a RESTful API
to control the servers, rather than using UNIX domain sockets directly.
Therefore, Kea includes a component called the Control Agent (CA), which
exposes a RESTful API to the controlling clients and can forward
commands to the respective Kea services over the UNIX domain sockets.
The CA configuration is described in
:ref:`agent-configuration`.

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
the 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
assumes that the control command is targeted at the CA itself and
attempts to respond.

Control connections over both HTTP and UNIX domain sockets are guarded
with timeouts. The timeout value is set to 10 seconds and is not
configurable.

This API can be used by external tools to manage and monitor Kea operation.
An example of such a monitoring tool is ISC's Stork. For details, see
:ref:`stork`.

.. _ctrl-channel-syntax:

Data Syntax
===========

Communication over the control channel is conducted using JSON
structures. If configured, Kea opens a socket and listens for
incoming connections. A process connecting to this socket is expected to
send JSON commands structured as follows:

::

   {
       "command": "foo",
       "service": [ "dhcp4" ],
       "arguments": {
           "param1": "value1",
           "param2": "value2",
           ...
       }
   }

The same command sent over the RESTful interface to the CA has 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",
               ...
           }
       }

The ``command`` parameter contains the name of the command to execute and it
is mandatory.
The ``arguments`` map contains the parameters required to carry out the
given command. The exact content and format of the map are command-specific.

The ``service`` list contains the servers at which the                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        