ctrl-channel.xml 11.7 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.1.0 is limited,
28
29
30
31
32
33
34
    the number is expected to grow over time.</para>

    <para>Currently the only supported type of control channel
    is UNIX stream socket. For details how to configure it, see
    <xref linkend="dhcp4-ctrl-channel" /> and <xref
    linkend="dhcp6-ctrl-channel" />. It is likely that support
    for other control channel types will be added in the future.
35
36
    </para>

37
    <section id="ctrl-channel-syntax">
38
39
40
41
    <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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
    is expected to send JSON commands structured as follows:

<screen>
{
    "command": "foo",
    "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
58
    format of the map is command specific.</para>
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

    <para>The server will process the incoming command and then send a
    response of the form:
<screen>
{
    "result": 0|1,
    "text": "textual description",
    "arguments": {
	"argument1": "value1",
	"argument2": "value2",
	...
    }
}
</screen>
    <command>result</command> indicates the outcome of the command. A value of 0
74
    means success while any non-zero value designates an error. Currently 1 is
75
    used as a generic error, but additional error codes may be added in the
76
    future. The <command>text</command> field typically appears when result is
77
    non-zero and contains a description of the error encountered, but it may
78
    also appear for successful results (that is command specific).
79
    <command>arguments</command> is a map of additional data values returned by
80
    the server which is specific to the command issued. The map is always present, even
81
82
83
84
    if it contains no data values.</para>
    </section>

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

87
88
    <para>Kea does not currently provide a client for using the control channel.  The primary
    reason for this is the expectation is that the entity using the control channel
89
    is typically an IPAM or similar network management/monitoring software which
90
    may have quite varied expectations regarding the client and is even likely to
91
92
    be written in languages different than C or C++. Therefore only examples are provided to show
    how one can take advantage of the API.</para>
93
94
95

    <para>The easiest way is to use a tool called <command>socat</command>,
    a tool available from <ulink url="http://www.dest-unreach.org/socat/">socat
96
    homepage</ulink>, but it is also widely available in Linux and BSD
97
98
99
100
101
    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>
102
103
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
104
105
configuration file. Text passed to <command>socat</command>
will be sent to Kea and the responses received from Kea printed to standard output.</para>
106

Andrei Pavel's avatar
Andrei Pavel committed
107
    <para>It is also easy to open UNIX socket programatically. An example of
108
    such a simplistic client written in C is available in the Kea Developer's
109
110
111
112
113
    Guide, chapter Control Channel Overview, section Using Control Channel.</para>

    </section>

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

116
117
118
119
120
121
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
      <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>
      </section>

      <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
        the name of the file to write configuration to. If not specifed, the
        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
        and any attempts to step out of that directory is rejected.</para>
        <para>
          An example command invocation looks like this:
<screen>
{
    "command": "config-write",
    "parameters": {
        "filename": "config-modified-2017-03-15.json"
    }
}
</screen>
        </para>
      </section>

167
      <section id="command-leases-reclaim">
168
        <title>leases-reclaim</title>
169
        <para>
170
          The <emphasis>leases-reclaim</emphasis> command instructs the server to
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
          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
188
189
        the same client which used this lease before. See
        <xref linkend="lease-affinity"/> for the details. Also, see
190
191
192
193
        <xref linkend="lease-reclamation"/> for the general information
        about the processing of expired leases (leases reclamation).</para>
      </section>

194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
      <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
212
         The server will respond with a result of 0 indicating success, or 1
213
214
215
216
         indicating a failure.
       </para>
     </section> <!-- end of command-libreload -->

217
      <section id="command-list-commands">
218
      <title>list-commands</title>
219
220

      <para>
221
	The <emphasis>list-commands</emphasis> command retrieves a list of all
222
	commands supported by the server. It does not take any arguments.
223
224
225
226
227
228
229
230
231
232
	An example command may look like this:
<screen>
{
    "command": "list-commands",
    "arguments": { }
}
</screen>
      </para>
      <para>
	The server will respond with a list of all supported commands. The
233
	arguments element will be a list of strings. Each string will convey
234
235
236
237
	one supported command.
      </para>
    </section> <!-- end of command-list-commands -->

238
239
240
241
242
243
244
245
246
247
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
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
    <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.

	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 successful." }

    or

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

297
    <section id="command-shutdown">
298
      <title>shutdown</title>
299
300

      <para>
301
	The <emphasis>shutdown</emphasis> command instructs the server to initiate
302
	its shutdown procedure. It is the equivalent of sending a SIGTERM signal
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
	to the process. This command does not take any arguments.  An example
	command may look like this:
<screen>
{
    "command": "shutdown",
    "arguments": { }
}
</screen>
      </para>
      <para>
	The server will respond with a confirmation that the shutdown procedure
	has been initiated.
      </para>
    </section> <!-- end of command-shutdown -->

318
319


320
321
    </section> <!-- end of commands supported by both servers -->

322
  </chapter>