ctrl-channel.xml 6.97 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 the 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
19
20
21
    is that if the new configuration is invalid for whatever reason,
    the server may refuse to start, which will further extend the
    downtime period, until the issue is resolved.</para>

    <para>To avoid such problems, both DHCPv4 and DHCPv6 servers
22
    introduced support for a mechanism that will allow
23
24
25
26
27
28
29
30
31
32
33
34
    on-line reconfiguration, without requiring server shutdown.
    Both servers can be instructed to open control sockets, which
    is a communication channel. The server is able to receive
    commands on that channel, act on them and report back status.
    While the set of commands supported in Kea 0.9.2 is limited,
    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
38
    <section id="ctrl-channel-syntax">
    <title>Data syntax</title>
39
    <para>Communication over control channel is conducted using JSON
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
    structures. If configured, Kea will open a socket and will listen
    for any incoming connections. A process connecting to this socket
    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
    format is command specific.</para>

    <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
76
    used as a generic error, but additional error codes may be added in the
    future.<command>text</command> field typically appears when result is
77
78
    non-zero and contains a description of the error encountered, but it may
    also appear for successful results. That's command specific.
79
    <command>arguments</command> is a map of additional data values returned by
80
    the server, specific to the command issued. The map is always present, even
81
82
83
84
85
86
87
88
89
    if it contains no data values.</para>
    </section>

    <section id="ctrl-channel-client">
    <title>Using control channel</title>

    <para>ISC does not provide a client for using control channel.  The primary
    reason for that is the expectation is that the entity using control channel
    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
93
94
95
    be written in languages different than C or C++. Therefore we only provide
    examples how one can take advantage of the API.</para>

    <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
106
configuration file.</para>

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

    </section>

    <section id="commands-common">
      <title>Commands supported by both 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
      <section id="command-leases-reclaim">
        <title>leases-reclaim command</title>
        <para>
          <emphasis>leases-reclaim</emphasis> command instructs the server to
          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
        the same client which used this lease before. See the
        <xref linkend="lease-affinity"/> for the details. Also, see the
        <xref linkend="lease-reclamation"/> for the general information
        about the processing of expired leases (leases reclamation).</para>
      </section>

142
143
144
145
146
      <section id="command-list-commands">
      <title>list-commands command</title>

      <para>
	<emphasis>list-commands</emphasis> command retrieves a list of all
147
	commands supported by the server. It does not take any arguments.
148
149
150
151
152
153
154
155
156
157
	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
158
	arguments element will be a list of strings. Each string will convey
159
160
161
162
163
164
165
166
167
	one supported command.
      </para>
    </section> <!-- end of command-list-commands -->

    <section id="command-shutdown">
      <title>shutdown command</title>

      <para>
	<emphasis>shutdown</emphasis> command instructs the server to initiate
168
	its shutdown procedure. It is the equivalent of sending a SIGTERM singal
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
	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 -->

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

186
  </chapter>