agent.xml 12.3 KB
Newer Older
1
2
3
4
5
6
7
8
<!--
 - Copyright (C) 2017-2018 Internet Systems Consortium, Inc. ("ISC")
 -
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
-->

9
10
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-ctrl-agent">
11
12
  <title>Kea Control Agent</title>

13
  <section xml:id="agent-overview">
14
15
    <title>Overview</title>
    <para>Kea Control Agent (CA) is a daemon, first included in Kea 1.2, which
16
    exposes a RESTful control interface for managing Kea servers. The daemon
17
18
19
20
21
22
23
    can receive control commands over HTTP and either forward these commands
    to the respective Kea servers or handle these commands on its own. The
    determination whether the command should be handled by the CA or forwarded
    is made by checking the value of the 'service' parameter which may be
    included in the command from the controlling client. The details of the
    supported commands as well as their structures are provided in
    <xref linkend="ctrl-channel"/>.</para>
24
    <para>Hook libraries can be loaded by the CA to provide support for
25
26
27
28
    additional commands or custom behavior of existing commands. Such hook
    libraries must implement callouts for 'control_command_receive' hook point.
    Details about creating new hook libraries and supported hook points can be
    found in
29
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Kea_doc/doxygen/">Kea Developer's Guide</link>.
30
    </para>
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

    <para>
      The CA processes received commands according to the following algorithm:
      <itemizedlist>
        <listitem>
          <simpara>
            Pass command into any installed hooks (regardless of service value(s)).
            If the command is handled by a hook, return the response.
          </simpara>
        </listitem>

        <listitem>
          <simpara>
            If the service specifies one more or services, the CA will forward the
            command to specified services and return the accumulated responses.
          </simpara>
        </listitem>

        <listitem>
          <simpara>
            If service is not specified or is an empty list, the CA will handle
            the command if it supports it.
          </simpara>
        </listitem>

      </itemizedlist>
    </para>
58
59
  </section>

60
  <section xml:id="agent-configuration">
61
62
63
64
65
66
67
68
69
70
    <title>Configuration</title>
    <para>The following example demonstrates the basic CA configuration.</para>
    <para>
<screen>
{
    "Control-agent": {
        "http-host": "10.20.30.40",
        "http-port": 8080,

        "control-sockets": {
71
            "dhcp4": {
72
                "comment": "main server",
73
74
75
                "socket-type": "unix",
                "socket-name": "/path/to/the/unix/socket-v4"
            },
76
            "dhcp6": {
77
                "socket-type": "unix",
78
79
                "socket-name": "/path/to/the/unix/socket-v4",
                "user-context": { "version": 3 }
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
            }
        },

        "hooks-libraries": [
        {
            "library": "/opt/local/control-agent-commands.so",
            "parameters": {
                "param1": "foo"
            }
        } ]
    },

    "Logging": {
        "loggers": [ {
            "name": "kea-ctrl-agent",
            "severity": "INFO"
        } ]
    }
}</screen>
    </para>

    <para>
      The <command>http-host</command> and <command>http-port</command>
      specify an IP address and port to which HTTP service will be bound.
      In case of the example configuration provided above, the RESTful
      service will be available under the URL of
      <command>http://10.20.30.40:8080/</command>. If these parameters
      are not specified, the default URL is http://127.0.0.1:8000/
    </para>

    <para>
      It has been mentioned in the <xref linkend="agent-overview"/> that
112
      CA can forward received commands to the specific Kea servers for
113
114
115
116
117
118
119
120
121
122
123
124
      processing. For example, <command>config-get</command> is sent to
      retrieve configuration of one of the Kea services. When CA receives
      this command, including a <command>service</command> parameter
      indicating that the client desires to retrieve configuration of
      the DHCPv4 server, the CA will forward this command to this server
      and then pass the received response back to the client. More about
      the <command>service</command> parameter and general structure of
      the commands can be found in <xref linkend="ctrl-channel"/>.
    </para>

    <para>
      The CA uses unix domain sockets to forward control commands and receive
125
126
      responses from other Kea services. The <command>dhcp4</command>,
      <command>dhcp6</command> and <command>d2</command> maps
127
128
129
130
      specify the files to which unix domain sockets are bound. In case
      of the configuration above, the CA will connect to the DHCPv4 server
      via <filename>/path/to/the/unix/socket-v4</filename> to forward the
      commands to it. Obviously, the DHCPv4 server must be configured to
131
      listen to connections via this same socket. In other words, the command
132
133
134
135
136
137
      socket configuration for the DHCPv4 server and CA (for this server)
      must match. Consult the <xref linkend="dhcp4-ctrl-channel"/> and the
      <xref linkend="dhcp6-ctrl-channel"/> to learn how the socket
      configuration is specified for the DHCPv4 and DHCPv6 services.
    </para>

138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
    <warning>
      <simpara>
        We have renamed "dhcp4-server", "dhcp6-server" and "d2-server"
        to "dhcp4", "dhcp6" and "d2" respectively after release of Kea 1.2.
        If you are migrating from Kea 1.2 you need to tweak your CA config
        to use this new naming convention. We have made this incompatible
        change to facilitate future use cases where it will be possible to
        specify additional values of the "service" parameter to point to
        the particular instances of the Kea servers, e.g. "dhcp4/3"
        pointing to the 3rd instance of the DHCPv4 server in the
        multi-processed configuration. This is not yet supported but the
        current renaming lays the ground for it.
      </simpara>
    </warning>

153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
    <para>
      User contexts can store arbitrary data as long as it is valid JSON
      syntax and its top level element is a map (i.e. the data must be
      enclosed in curly brackets). Some hook libraries may expect specific
      formatting, though.  Please consult specific hook library
      documentation for details.
    </para>

    <para>
      User contexts can be specified on either global scope, control
      socket and loggers. One other useful usage is the ability to
      store comments or descriptions: the parser translates a
      "comment" entry into a user-context with the entry, this allows
      to attach a comment inside the configuration itself.
    </para>

169
    <para>
170
      Hooks libraries can be loaded by the Control Agent just like to
171
172
173
      DHCPv4 and DHCPv6 servers. It currently supports one hook point
      'control_command_receive' which makes it possible to delegate
      processing of some commands to the hooks library. The
174
175
      <command>hooks-libraries</command> list contains the list of hooks
      libraries that should be loaded by the CA, along with their configuration
176
177
178
179
180
181
182
183
184
185
      information specified with <command>parameters</command>.
    </para>

    <para>
      Please consult <xref linkend="logging"/> for the details how to
      configure logging. The CA's root logger's name is
      <command>kea-ctrl-agent</command> as given in the example above.
    </para>
  </section>

186
  <section xml:id="agent-secure-connection">
187
188
189
190
191
    <title>Secure Connections</title>
    <para>
      Control Agent doesn't natively support secure HTTP connections like
      SSL or TLS. In order to setup secure connection please use one
      of the available third party HTTP servers and configure it to run
192
193
194
195
196
      as a reverse proxy to the Control Agent. Kea has been tested with
      two major HTTP server implentations working as a reverse proxy:
      Apache2 and nginx. Example configurations including extensive
      comments are provided in the <filename>doc/examples/https/</filename>
      directory.
197
    </para>
198
199
200
201
202
203

    <para>
      The reverse proxy forwards HTTP requests received over secure
      connection to the Control Agent using (not secured) HTTP. Typically,
      the reverse proxy and the Control Agent are running on the same machine,
      but it is possible to configure them to run on separate machines as
204
205
      well. In this case, security depends on the protection of the
      communications between the reverse proxy and the Control Agent.
206
207
208
209
210
211
    </para>

    <para>Apart from providing the encryption layer for the control channel,
    a reverse proxy server is also often used for authentication of the
    controlling clients. In this case, the client must present a valid
    certificate when it connects via reverse proxy. The proxy server
Josh Soref's avatar
Josh Soref committed
212
    authenticates the client by checking if the presented certificate is
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
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
    signed by the certificate authority used by the server.</para>

    <para>To illustrate this, we provide a sample configuration for the
    nginx server running as a reverse proxy to the Kea Control Agent.
    The server enables authentication of the clients using
    certificates.</para>

<screen>
#   The server certificate and key can be generated as follows:
#
#   openssl genrsa -des3 -out kea-proxy.key 4096
#   openssl req -new -x509 -days 365 -key kea-proxy.key -out kea-proxy.crt
#
#   The CA certificate and key can be generated as follows:
#
#   openssl genrsa -des3 -out ca.key 4096
#   openssl req -new -x509 -days 365 -key ca.key -out ca.crt
#
#
#   The client certificate needs to be generated and signed:
#
#   openssl genrsa -des3 -out kea-client.key 4096
#   openssl req -new -key kea-client.key -out kea-client.csr
#   openssl x509 -req -days 365 -in kea-client.csr -CA ca.crt \
#           -CAkey ca.key -set_serial 01 -out kea-client.crt
#
#   Note that the 'common name' value used when generating the client
#   and the server certificates must differ from the value used
#   for the CA certificate.
#
#   The client certificate must be deployed on the client system.
#   In order to test the proxy configuration with 'curl' run
#   command similar to the following:
#
#   curl -k --key kea-client.key --cert kea-client.crt -X POST \
#        -H Content-Type:application/json -d '{ "command": "list-commands" }' \
#         https://kea.example.org/kea
#
#
#
#   nginx configuration starts here.

events {
}

http {
        #   HTTPS server
    server {
        #     Use default HTTPS port.
        listen 443 ssl;
        #     Set server name.
        server_name kea.example.org;

        #   Server certificate and key.
        ssl_certificate /path/to/kea-proxy.crt;
        ssl_certificate_key /path/to/kea-proxy.key;

        #   Certificate Authority. Client certificate must be signed by the CA.
        ssl_client_certificate /path/to/ca.crt;

        # Enable verification of the client certificate.
        ssl_verify_client on;

        # For URLs such as https://kea.example.org/kea, forward the
        # requests to http://127.0.0.1:8080.
        location /kea {
            proxy_pass http://127.0.0.1:8080;
        }
    }
}
</screen>

  <note>
    <simpara>Note that the configuration snippet provided above is for testing
    purposes only. Consult security policies and best practices of your
    organization which apply to this setup.</simpara>
  </note>

Thomas Markwalder's avatar
Thomas Markwalder committed
291
292
    <para>When you use an HTTP client without TLS support as <command>
    kea-shell</command> you can use an HTTP/HTTPS translator such as stunnel
293
294
295
    in client mode. A sample configuration is provided in the
    <filename>doc/examples/https/shell/</filename> directory</para>

296
297
  </section>

298
  <section xml:id="agent-launch">
299
300
301
302
303
    <title>Starting Control Agent</title>
    <para>
      The CA is started by running its binary and specifying the configuration file
      it should use. For example:
<screen>
304
$ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf
305
306
</screen>3
      It can be started by keactrl as well (see <xref linkend="keactrl"/>).
307
308
    </para>
  </section>
309

310
  <section xml:id="agent-clients">
311
    <title>Connecting to the Control Agent</title>
312
313
314
    <para>For an example of tool that can take advantage of the
    RESTful API, see <xref linkend="kea-shell"/>.</para>
  </section>
315
</chapter>