ctrl-channel.rst 19.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
.. _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.

15
To avoid such problems, the DHCPv4, DHCPv6, and D2 servers in Kea include
16 17 18 19 20 21
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.

22 23 24 25 26
The DHCPv4, DHCPv6, and D2 servers receive commands over the UNIX domain
sockets. For details on how to configure these sockets, see
:ref:`dhcp4-ctrl-channel` and :ref:`dhcp6-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
27 28 29 30 31
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.
32
Therefore, Kea includes a component called the Control Agent (or CA), which
33 34
exposes a RESTful API to the controlling clients and can forward
commands to the respective Kea services over the UNIX domain sockets.
35 36
The CA configuration is described in
:ref:`agent-configuration`.
37 38 39 40 41 42 43 44 45 46 47 48 49 50

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
will assume that the control command is targeted at the CA itself and
will try to handle it on its own.

Control connections over both HTTP and UNIX domain sockets are guarded
51
with timeouts. The default timeout value is set to 10 seconds and is not
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
configurable.

.. _ctrl-channel-syntax:

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

Communication over the control channel is conducted using JSON
structures. If configured, Kea will open a socket and listen 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 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 the command to execute and is mandatory.
95 96
``arguments`` is a map of the parameters required to carry out the given
command. The exact content and format of the map are command-specific.
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120

``service`` is a list of the servers at which the control command is
targeted. In the example above, the control command is targeted at the
DHCPv4 server. In most cases, the CA will simply forward this command to
the DHCPv4 server for processing via a 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 a command for
the given server. As an example, the hooks library loaded by the CA may
perform some operations on the database, such as 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, since the DHCPv4
server doesn't have to stop processing DHCP messages to apply changes to
the database. Nevertheless, 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. The forwarded
command includes the ``service`` parameter but this parameter is ignored
by the receiving server. This parameter is only meaningful to the CA.

If the command received by the CA does not include a ``service``
parameter or this list is empty, the CA simply processes this message on
its own. For example, a ``config-get`` command which includes no service
parameter returns the Control Agent's own configuration. The
121
``config-get`` command with a service value "dhcp4" is forwarded to the DHCPv4
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
server and returns the DHCPv4 server's configuration.

The following list shows the mapping of the values carried within the
``service`` parameter to the servers to which the commands are
forwarded:

-  ``dhcp4`` - the command is forwarded to the ``kea-dhcp4`` server.

-  ``dhcp6`` - the command is forwarded to the ``kea-dhcp6`` server.

-  ``d2`` - the command is forwarded to the ``kea-d2`` server.

The server processing the incoming command will send a response of the
form:

::

   {
       "result": 0|1|2|3,
       "text": "textual description",
       "arguments": {
           "argument1": "value1",
           "argument2": "value2",
           ...
       }
   }

``result`` indicates the outcome of the command. A value of 0 means
success, while any non-zero value designates an error or a failure to
complete the requested action. Currently 1 indicates a generic error, 2
means that a command is not supported, and 3 means that the requested
operation was completed, but the requested object was not found. For
example, a well-formed command that requests a subnet that exists in a
server's configuration returns the result 0. If the server encounters an
error condition, it returns 1. If the command asks for the IPv6 subnet,
but was sent to a DHCPv4 server, it returns 2. If the query asks for a
subnet-id and there is no subnet with such an id, the result is 3.

The ``text`` field typically appears when the result is non-zero and
contains a description of the error encountered, but it often also
appears for successful outcomes. The exact text is command-specific, but
in general uses plain English to describe the outcome of the command.
``arguments`` is a map of additional data values returned by the server
which are specific to the command issued. The map may be present, but
that depends on the specific command.

168
.. note::
169

170
   When sending commands via the Control Agent, it is possible to specify
171 172 173 174 175 176 177 178 179 180 181 182
   multiple services at which the command is targeted. CA forwards this
   command to each service individually. Thus, the CA response to the
   controlling client contains an array of individual responses.

.. _ctrl-channel-client:

Using the Control Channel
=========================

The easiest way to start interacting with the control API is to use
common UNIX/Linux tools such as ``socat`` and ``curl``.

183
In order to control the given Kea service via a UNIX domain socket, use
184 185
``socat`` in interactive mode as follows:

186
.. code-block:: console
187 188 189 190

   $ socat UNIX:/path/to/the/kea/socket -

or in batch mode, include the "ignoreeof" option as shown below to
191
ensure ``socat`` waits long enough for the server to respond:
192

193
.. code-block:: console
194 195 196 197 198 199 200 201 202 203 204

   $ echo "{ some command...}" | socat UNIX:/path/to/the/kea/socket -,ignoreeof

where ``/path/to/the/kea/socket`` is the path specified in the
``Dhcp4/control-socket/socket-name`` parameter in the Kea configuration
file. Text passed to ``socat`` is sent to Kea and the responses received
from Kea are printed to standard output. This approach communicates with
the specific server directly and bypasses the Control Agent.

It is also easy to open a UNIX socket programmatically. An example of a
simple client written in C is available in the Kea Developer's Guide, in
205 206
the Control Channel Overview chapter, in the
`Using Control Channel <https://jenkins.isc.org/job/Kea_doc/doxygen/d2/d96/ctrlSocket.html#ctrlSocketClient>`__
207 208
section.

209
To use Kea's RESTful API with ``curl``, use the following:
210

211
.. code-block:: console
212 213 214 215 216 217 218 219 220 221 222 223 224

   $ 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 is running the RESTful service on port 8000.

.. _commands-common:

Commands Supported by Both the DHCPv4 and DHCPv6 Servers
========================================================

.. _command-build-report:

225 226
The build-report Command
------------------------
227

228
The ``build-report`` command returns on the control channel what the
229 230 231 232 233 234 235 236 237 238 239
command line ``-W`` argument displays, i.e. the embedded content of the
``config.report`` file. This command does not take any parameters.

::

   {
       "command": "build-report"
   }

.. _command-config-get:

240 241
The config-get Command
----------------------
242

243
The ``config-get`` command retrieves the current configuration used by the
244 245
server. This command does not take any parameters. The configuration
returned is roughly equal to the configuration that was loaded using the
246 247
-c command line option during server start-up or later set using the
``config-set`` command. However, there may be certain differences, as
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266
comments are not retained. If the original configuration used file
inclusion, the returned configuration will include all parameters from
all the included files.

Note that the returned configuration is not redacted, i.e. it will
contain database passwords in plain text if those were specified in the
original configuration. Care should be taken not to expose the command
channel to unprivileged users.

An example command invocation looks like this:

::

   {
       "command": "config-get"
   }

.. _command-config-reload:

267 268
The config-reload Command
-------------------------
269

270
The ``config-reload`` command instructs Kea to load again the
271 272 273 274 275
configuration file that was used previously. This operation is useful if
the configuration file has been changed by some external source; for
example, a sysadmin can tweak the configuration file and use this
command to force Kea pick up the changes.

276
Caution should be taken when mixing this with ``config-set`` commands. Kea
277
remembers the location of the configuration file it was started with,
278 279
and this configuration can be significantly changed using the ``config-set``
command. When ``config-reload`` is issued after ``config-set``, Kea will attempt
280
to reload its original configuration from the file, possibly losing all
281
changes introduced using ``config-set`` or other commands.
282

283
``config-reload`` does not take any parameters. An example command
284 285 286 287 288 289 290 291 292 293
invocation looks like this:

::

   {
       "command": "config-reload"
   }

.. _command-config-test:

294 295
The config-test Command
-----------------------
296

297
The ``config-test`` command instructs the server to check whether the new
298 299 300
configuration supplied in the command's arguments can be loaded. The
supplied configuration is expected to be the full configuration for the
target server, along with an optional Logger configuration. As for the
301
``-t`` command, some sanity checks are not performed, so it is possible a
302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343
configuration which successfully passes this command will still fail in
the ``config-set`` command or at launch time. The structure of the
command is as follows:

::

   {
       "command": "config-test",
       "arguments":  {
           "<server>": {
           }
        }
   }

where <server> is the configuration element name for a given server such
as "Dhcp4" or "Dhcp6". For example:

::

   {
       "command": "config-test",
       "arguments":  {
           "Dhcp6": {
               :
           }
        }
   }

The server's response will contain a numeric code, "result" (0 for
success, non-zero on failure), and a string, "text", describing the
outcome:

::

       {"result": 0, "text": "Configuration seems sane..." }

       or

       {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }

.. _command-config-write:

344 345
The config-write Command
------------------------
346

347 348 349
The ``config-write`` command instructs the Kea server to write its current
configuration to a file on disk. It takes one optional argument, called
"filename", that specifies the name of the file to write the
350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
configuration to. If not specified, the name used when starting Kea
(passed as a -c argument) will be used. If a relative path is specified,
Kea will write its files only in the directory it is running.

An example command invocation looks like this:

::

   {
       "command": "config-write",
       "arguments": {
           "filename": "config-modified-2017-03-15.json"
       }
   }

.. _command-leases-reclaim:

367 368
The leases-reclaim Command
--------------------------
369

370
The ``leases-reclaim`` command instructs the server to reclaim all expired
371 372 373 374 375 376 377 378 379 380 381
leases immediately. The command has the following JSON syntax:

::

   {
       "command": "leases-reclaim",
       "arguments": {
           "remove": true
       }
   }

382
The ``remove`` boolean parameter is mandatory and indicates whether the
383
reclaimed leases should be removed from the lease database (if true), or
384
left in the "expired-reclaimed" state (if false). The latter facilitates
385
lease affinity, i.e. the ability to re-assign an expired lease to the
386 387 388
same client that used this lease before. See :ref:`lease-affinity`
for the details. Also, see :ref:`lease-reclamation` for general
information about the processing of expired leases (lease reclamation).
389 390 391

.. _command-libreload:

392 393
The libreload Command
---------------------
394

395 396 397 398
The ``libreload`` command first unloads and then loads all currently
loaded hooks libraries. This is primarily intended to allow one or more
hooks libraries to be replaced with newer versions without requiring Kea
servers to be reconfigured or restarted. Note that the hooks libraries
399 400 401 402 403 404 405 406 407 408 409 410 411 412 413
are passed the same parameter values (if any) that were passed when they
originally loaded.

::

   {
       "command": "libreload",
       "arguments": { }
   }

The server will respond with a result of either 0, indicating success,
or 1, indicating failure.

.. _command-list-commands:

414 415
The list-commands Command
-------------------------
416

417
The ``list-commands`` command retrieves a list of all commands supported
418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433
by the server. It does not take any arguments. An example command may
look like this:

::

   {
       "command": "list-commands",
       "arguments": { }
   }

The server responds with a list of all supported commands. The arguments
element is a list of strings, each of which conveys one supported
command.

.. _command-config-set:

434 435
The config-set Command
----------------------
436

437
The ``config-set`` command instructs the server to replace its current
438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486
configuration with the new configuration supplied in the command's
arguments. The supplied configuration is expected to be the full
configuration for the target server, along with an optional Logger
configuration. While optional, the Logger configuration is highly
recommended, as without it the server will revert to its default logging
configuration. The structure of the command is as follows:

::

   {
       "command": "config-set",
       "arguments":  {
           "<server>": {
           }
        }
   }

where <server> is the configuration element name for a given server such
as "Dhcp4" or "Dhcp6". For example:

::

   {
       "command": "config-set",
       "arguments":  {
           "Dhcp6": {
               :
           }
        }
   }

If the new configuration proves to be invalid, the server retains its
current configuration. Please note that the new configuration is
retained in memory only; if the server is restarted or a configuration
reload is triggered via a signal, the server uses the configuration
stored in its configuration file. The server's response contains a
numeric code, "result" (0 for success, non-zero on failure), and a
string, "text", describing the outcome:

::

       {"result": 0, "text": "Configuration successful." }

       or

       {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }

.. _command-shutdown:

487 488
The shutdown Command
--------------------
489

490
The ``shutdown`` command instructs the server to initiate its shutdown
491 492 493 494 495 496 497 498 499 500 501 502 503 504 505
procedure. It is the equivalent of sending a SIGTERM signal to the
process. This command does not take any arguments. An example command
may look like this:

::

   {
       "command": "shutdown"
   }

The server responds with a confirmation that the shutdown procedure has
been initiated.

.. _command-dhcp-disable:

506 507
The dhcp-disable Command
------------------------
508

509
The ``dhcp-disable`` command globally disables the DHCP service. The
510 511 512 513 514
server continues to operate, but it drops all received DHCP messages.
This command is useful when the server's maintenance requires that the
server temporarily stop allocating new leases and renew existing leases.
It is also useful in failover-like configurations during a
synchronization of the lease databases at startup, or recovery after a
515
failure. The optional parameter "max-period" specifies the time in
516
seconds after which the DHCP service should be automatically re-enabled,
517
if the ``dhcp-enable`` command is not sent before this time elapses.
518 519 520 521 522 523 524 525 526 527 528 529

::

   {
       "command": "dhcp-disable",
       "arguments": {
           "max-period": 20
       }
   }

.. _command-dhcp-enable:

530 531
The dhcp-enable Command
-----------------------
532

533
The ``dhcp-enable`` command globally enables the DHCP service.
534 535 536 537 538 539 540

::

   {
       "command": "dhcp-enable"
   }

541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557
.. _command-server-tag-get:

The server-tag-get Command:
---------------------------

The ``server-tag-get`` command returns the configured server tag of
the DHCPv4 or DHCPv6 server (:ref:`cb-sharing` explains the server tag concept)

.. _command-server-update:

The server-update Command:
--------------------------

The ``server-update`` command triggers the polling of Config Backends
(which should be configured for this command to do something)
explained in :ref:`dhcp4-cb-json`.

558 559
.. _command-version-get:

560 561
The version-get Command
-----------------------
562

563
The ``version-get`` command returns extended information about the Kea
564 565 566 567 568 569 570 571 572
version. It is the same information available via the ``-V``
command-line argument. This command does not take any parameters.

::

   {
       "command": "version-get"
   }

573 574
Commands Supported by the D2 Server
===================================
575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597

The D2 server supports only a subset of DHCPv4 / DHCPv6 server commands:

-  build-report

-  config-get

-  config-reload

-  config-set

-  config-test

-  config-write

-  list-commands

-  shutdown

-  version-get

.. _agent-commands:

598 599
Commands Supported by the Control Agent
=======================================
600

601
The following commands listed in :ref:`commands-common` are also supported by the
602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621
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-reload

-  config-set

-  config-test

-  config-write

-  list-commands

-  shutdown

-  version-get