ctrl-channel.xml 20.5 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
<?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  "&#x2014;" >
<!ENTITY % version SYSTEM "version.ent">
%version;
]>

  <chapter id="ctrl-channel">
    <title>Management API</title>
11

12
    <para>A classic approach to daemon configuration assumes that
13
14
    the server's configuration is stored in configuration files
    and, when the configuration is changed, the daemon is restarted.
15
16
    This approach has the significant disadvantage of introducing periods
    of downtime, when client traffic is not handled. Another risk
17
18
    is that if the new configuration is invalid for whatever reason,
    the server may refuse to start, which will further extend the
19
    downtime period until the issue is resolved.</para>
20

21
22
23
    <para>To avoid such problems, both the DHCPv4 and DHCPv6 servers
    include support for a mechanism that allows
    on-line reconfiguration without requiring server shutdown.
24
25
26
    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.
27
    While the set of commands in Kea 1.2.0 is limited,
28
29
    the number is expected to grow over time.</para>

30
31
32
33
34
    <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
35
    the controlling client be running on the same machine as
36
37
38
39
40
41
42
    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
43
    exposes a RESTful API to the controlling clients and can forward
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
    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.
61
62
    </para>

63
    <section id="ctrl-channel-syntax">
64
65
66
67
    <title>Data Syntax</title>
    <para>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
68
69
70
71
72
    is expected to send JSON commands structured as follows:

<screen>
{
    "command": "foo",
73
    "service": [ "dhcp4" ]
74
    "arguments": {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
75
76
77
        "param1": "value1",
        "param2": "value2",
        ...
78
79
80
81
    }
}
</screen>

82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
    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>

100
101
102
    <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
103
    format of the map is command specific.</para>
104

105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
    <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
121
122
123
124
      the commands are simply forwarded by the CA. The forwarded command
      includes the <command>service</command> parameter but this parameter
      is ignored by the receiving server. This parameter is only meaningful
      to the CA.
125
126
127
128
129
130
131
132
133
134
135
136
    </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>

137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
    <para>
      The following list contains a mapping of the values carried within the
      <command>service</command> parameter to the servers to which the commands
      are forwarded:

      <itemizedlist>
        <listitem>
          <simpara><command>dhcp4</command> - the command is forwarded to the
          <command>kea-dhcp4</command> server,</simpara>
        </listitem>

        <listitem>
          <simpara><command>dhcp6</command> - the command is forwarded to the
          <command>kea-dhcp6</command> server,</simpara>
        </listitem>

        <listitem>
          <simpara><command>d2</command> - the command is forwarded to the
          <command>kea-d2</command> server.</simpara>
        </listitem>
      </itemizedlist>
    </para>

160
161
    <para>The server processing the incoming command will send a response of
    the form:
162
163
164
165
166
<screen>
{
    "result": 0|1,
    "text": "textual description",
    "arguments": {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
167
168
169
        "argument1": "value1",
        "argument2": "value2",
        ...
170
171
172
173
    }
}
</screen>
    <command>result</command> indicates the outcome of the command. A value of 0
174
    means success while any non-zero value designates an error. Currently 1 is
175
    used as a generic error, but additional error codes may be added in the
176
    future. The <command>text</command> field typically appears when result is
177
    non-zero and contains a description of the error encountered, but it may
178
    also appear for successful results (that is command specific).
179
    <command>arguments</command> is a map of additional data values returned by
180
    the server which is specific to the command issued. The map is always present, even
181
    if it contains no data values.</para>
182
183
184
185
186

    <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
187
        command to each service individually. Thus, the CA response to the
188
189
190
191
        controlling client will contain an array of individual responses.
      </simpara>
    </note>

192
193
194
    </section>

    <section id="ctrl-channel-client">
195
    <title>Using the Control Channel</title>
196

197
198
199
200
    <para>Kea development team is actively working on providing client applications
    which can be used to control the servers. These applications are, however, in the
    early stages of development and as of Kea 1.2.0 release have certain limitatins.
    The easiest way to start playing with the control API is to use common Unix/Linux tools
201
202
203
204
    such as <command>socat</command> and <command>curl</command>.</para>

    <para>In order to control the given Kea service via unix domain socket, use
    <command>socat</command> as follows:
205
206
207
<screen>
$ socat UNIX:/path/to/the/kea/socket -
</screen>
208
209
where <command>/path/to/the/kea/socket</command> is the path specified in the
<command>Dhcp4/control-socket/socket-name</command> parameter in the Kea
210
211
configuration file. Text passed to <command>socat</command>
will be sent to Kea and the responses received from Kea printed to standard output.</para>
212

Andrei Pavel's avatar
Andrei Pavel committed
213
    <para>It is also easy to open UNIX socket programatically. An example of
214
    such a simplistic client written in C is available in the Kea Developer's
215
216
    Guide, chapter Control Channel Overview, section Using Control Channel.</para>

217
218
219
220
221
222
223
224
225
226
    <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>

227
228
229
    </section>

    <section id="commands-common">
230
      <title>Commands Supported by Both the DHCPv4 and DHCPv6 Servers</title>
231

Francis Dupont's avatar
Francis Dupont committed
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
      <section id="command-build-report">
        <title>build-report</title>
        <para>
          The <emphasis>build-report</emphasis> command returns
          on the control channel what the command line
          <command>-W</command> argument displays, i.e. the embedded
          content of the <filename>config.report</filename> file.
          This command does not take any parameters.
        </para>
<screen>
{
    "command": "build-report"
}
</screen>
      </section> <!-- end of command-build-report -->

248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
      <section id="command-config-get">
        <title>config-get</title>

        <para>The <emphasis>config-get</emphasis> command retrieves the current
        configuration used by the server. This command does not take any
        parameters. The configuration returned is roughly equal to the
        configuration that was loaded using -c command line option during server
        start-up or later set using set-config command. However, there may be
        certain differences. Comments are not retained. If the original
        configuration used file inclusion, the returned configuration will
        include all parameters from all the included files.</para>

        <para> Note that 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 to not expose the command
        channel to unprivileged users.</para>

        <para>
          An example command invocation looks like this:
<screen>
{
    "command": "config-get"
}
</screen>
        </para>
Francis Dupont's avatar
Francis Dupont committed
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
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
      </section> <!-- end of command-config-get -->

      <section id="command-config-test">
        <title>config-test</title>

      <para>
     The <emphasis>config-test</emphasis> command instructs the server to check
     whether the new 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 <command>-t</command> command some sanity checks
     are not performed so it is possible a configuration which successfully
     passes this command will still fail in <command>set-config</command>
     command or at launch time.
     The structure of the command is as follows:
      </para>
<screen>
{
    "command": "config-test",
    "arguments":  {
        "&#60;server&#62;": {
        },
        "Logging": {
        }
     }
}
</screen>
      <para>
    where &#60;server&#62; is the configuration element name for a given server
    such as "Dhcp4" or "Dhcp6".  For example:
      </para>
<screen>
{
    "command": "config-test",
    "arguments":  {
        "Dhcp6": {
            :
        },
        "Logging": {
            :
        }
     }
}
</screen>
      <para>
        The server's response will contain a numeric code, "result" (0 for success,
    non-zero on failure), and  a string, "text", describing the outcome:
<screen>
    {"result": 0, "text": "Configuration seems sane..." }

    or

    {"result": 1, "text": "unsupported parameter: BOGUS (&#60;string&#62;:16:26)" }
</screen>
      </para>
    </section> <!-- end of command-config-test -->
329
330
331
332
333
334
335

      <section id="command-config-write">
        <title>config-write</title>

        <para>The <emphasis>config-write</emphasis> command instructs Kea server
        to write its current configuration to a file on disk. It takes one
        optional argument called <emphasis>filename</emphasis> that specifies
Francis Dupont's avatar
Francis Dupont committed
336
        the name of the file to write configuration to. If not specified, the
337
338
339
        name used when starting Kea (passed as -c argument) will be used. Note
        that the filename specified must not contain .. or backslashes. Kea
        should be able to write its files only in the directory it is running
340
        and any attempts to step out of that directory will be rejected.</para>
341
342
343
344
345
346
347
348
349
350
351
        <para>
          An example command invocation looks like this:
<screen>
{
    "command": "config-write",
    "parameters": {
        "filename": "config-modified-2017-03-15.json"
    }
}
</screen>
        </para>
Francis Dupont's avatar
Francis Dupont committed
352
      </section> <!-- end of command-config-write -->
353

354
      <section id="command-leases-reclaim">
355
        <title>leases-reclaim</title>
356
        <para>
357
          The <emphasis>leases-reclaim</emphasis> command instructs the server to
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
          reclaim all expired leases immediately. The command has the following
          JSON syntax:
<screen>
{
    "command": "leases-reclaim",
    "arguments": {
        "remove": true
    }
}
</screen>
        </para>

        <para>The <emphasis>remove</emphasis> boolean parameter is mandatory
        and it indicates whether the reclaimed leases should be removed from
        the lease database (if true), or they should be left in the
        <emphasis>expired-reclaimed</emphasis> state (if false). The latter
        facilitates lease affinity, i.e. ability to re-assign expired lease to
375
376
        the same client which used this lease before. See
        <xref linkend="lease-affinity"/> for the details. Also, see
377
378
379
380
        <xref linkend="lease-reclamation"/> for the general information
        about the processing of expired leases (leases reclamation).</para>
      </section>

381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
      <section id="command-libreload">
        <title>libreload</title>

        <para>
          The <emphasis>libreload</emphasis> command will first unload and then
          load all currently loaded hook libraries.  This is primarily intended
          to allow one or more hook libraries to be replaced with newer versions
          without requiring Kea servers to be reconfigured or restarted.  Note
          the hook libraries will be passed the same parameter values (if any)
          they were passed when originally loaded.
<screen>
{
    "command": "libreload",
    "arguments": { }
}
</screen>
       </para>
       <para>
Francis Dupont's avatar
Francis Dupont committed
399
         The server will respond with a result of 0 indicating success, or 1
400
401
402
403
         indicating a failure.
       </para>
     </section> <!-- end of command-libreload -->

404
      <section id="command-list-commands">
405
      <title>list-commands</title>
406
407

      <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
408
409
410
        The <emphasis>list-commands</emphasis> command retrieves a list of all
        commands supported by the server. It does not take any arguments.
        An example command may look like this:
411
412
413
414
415
416
417
418
<screen>
{
    "command": "list-commands",
    "arguments": { }
}
</screen>
      </para>
      <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
419
420
421
        The server will respond with a list of all supported commands. The
        arguments element will be a list of strings. Each string will convey
        one supported command.
422
423
424
      </para>
    </section> <!-- end of command-list-commands -->

425
426
427
428
429
430
431
432
433
434
435
436
437
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
    <section id="command-set-config">
      <title>set-config</title>

      <para>
    The <emphasis>set-config</emphasis> command instructs the server to replace
    its current 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:
      </para>
<screen>
{
    "command": "set-config",
    "arguments":  {
        "&#60;server&#62;": {
        },
        "Logging": {
        }
     }
}
</screen>
      <para>
    where &#60;server&#62; is the configuration element name for a given server
    such as "Dhcp4" or "Dhcp6".  For example:
      </para>
<screen>
{
    "command": "set-config",
    "arguments":  {
        "Dhcp6": {
            :
        },
        "Logging": {
            :
        }
     }
}
</screen>
      <para>
    If the new configuration proves to be invalid the server will retain
    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 will use the configuration
    stored in its configuration file.

Tomek Mrugalski's avatar
Tomek Mrugalski committed
472
        The server's response will contain a numeric code, "result" (0 for success,
473
474
475
476
477
478
479
480
481
482
483
    non-zero on failure), and  a string, "text", describing the outcome:
<screen>
    {"result": 0, "text": "Configuration successful." }

    or

    {"result": 1, "text": "unsupported parameter: BOGUS (&#60;string&#62;:16:26)" }
</screen>
      </para>
    </section> <!-- end of command-set-config -->

484
    <section id="command-shutdown">
485
      <title>shutdown</title>
486
487

      <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
488
489
490
491
        The <emphasis>shutdown</emphasis> command instructs the server to initiate
        its shutdown 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:
492
493
494
495
496
497
498
499
<screen>
{
    "command": "shutdown",
    "arguments": { }
}
</screen>
      </para>
      <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
500
501
        The server will respond with a confirmation that the shutdown procedure
        has been initiated.
502
503
504
      </para>
    </section> <!-- end of command-shutdown -->

Francis Dupont's avatar
Francis Dupont committed
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
      <section id="command-version-get">
        <title>version-get</title>
        <para>
          The <emphasis>version-get</emphasis> command returns on the control
          channel what the command line <command>-v</command> argument
          displays with in arguments the extended version, i.e., what
          the command line <command>-V</command> argument displays. This command
          does not take any parameters.
        </para>
<screen>
{
    "command": "version-get"
}
</screen>
      </section> <!-- end of command-version-get -->
520

521
522
    </section> <!-- end of commands supported by both servers -->

523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
    <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>

555
  </chapter>