Skip to content

Commit 1f88309

Browse files
fxdupontfxdupont
committed
[#3477] First attempt
1 parent 6f68380 commit 1f88309

File tree

5 files changed

+383
-31
lines changed

5 files changed

+383
-31
lines changed

‎doc/sphinx/arm/agent.rst

+8-2
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,12 @@ The CA processes received commands according to the following algorithm:
3737
- If the service is not specified or is an empty list, handle the
3838
command if the CA supports it.
3939

40+
.. note::
41+
42+
The CA will be deprecated by a future Kea release: its function has
43+
been moved to Kea servers since release 2.7.2, see the section about
44+
migration from CA (:ref:`ctrl-channel-migration`).
45+
4046
.. _agent-configuration:
4147

4248
Configuration
@@ -131,8 +137,8 @@ configuration above, the CA connects to the DHCPv4 server via
131137
Obviously, the DHCPv4 server must be configured to listen to connections
132138
via this same socket. In other words, the command-socket configuration
133139
for the DHCPv4 server and the CA (for that server) must match. Consult
134-
:ref:`dhcp4-ctrl-channel`, :ref:`dhcp6-ctrl-channel`, and
135-
:ref:`d2-ctrl-channel` to learn how the socket configuration is
140+
:ref:`dhcp4-unix-ctrl-channel`, :ref:`dhcp6-unix-ctrl-channel`, and
141+
:ref:`d2-unix-ctrl-channel` to learn how the UNIX socket configuration is
136142
specified for the DHCPv4, DHCPv6, and D2 services.
137143

138144
User contexts can store arbitrary data as long as they are in valid JSON

‎doc/sphinx/arm/ctrl-channel.rst

+38-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@ status.
2121

2222
The DHCPv4, DHCPv6, and D2 servers receive commands over the UNIX domain
2323
sockets. For details on how to configure these sockets, see
24-
:ref:`dhcp4-ctrl-channel` and :ref:`dhcp6-ctrl-channel`. While
24+
:ref:`dhcp4-unix-ctrl-channel`, :ref:`dhcp6-unix-ctrl-channel` and
25+
:ref:`d2-unix-ctrl-channel`. While
2526
it is possible to control the servers directly using UNIX domain sockets,
2627
that requires that the controlling client be running on the same machine
2728
as the server. SSH is usually used to connect remotely to the controlled
@@ -920,3 +921,39 @@ commands are handled by the CA and they relate to the CA process itself:
920921
- :isccmd:`status-get`
921922

922923
- :isccmd:`version-get`
924+
925+
.. _ctrl-channel-migration:
926+
927+
Migration from the Control Agent
928+
================================
929+
930+
Since Kea version 2.7.2 DHCP servers support HTTP/HTTPS control channels
931+
so the Control Agent (CA) is no longer needed.
932+
933+
The DHCPv4, DHCPv6, and D2 servers extend the ``control-socket`` entry
934+
to ``control-sockets`` list. To migrate a CA configuration add an element
935+
to this list with:
936+
937+
- ``socket-type`` set to ``http`` or ``https``
938+
939+
- ``socket-address`` with the content of CA ``http-host``
940+
941+
- ``socket-port`` with the content of CA ``http-port``
942+
943+
- ``trust-anchor`` (unchanged)
944+
945+
- ``cert-file`` (unchanged)
946+
947+
- ``key-file`` (unchanged)
948+
949+
- ``cert-required`` (unchanged)
950+
951+
- ``authentication`` (unchanged)
952+
953+
User context is supported too. Please look at respective HTTP control socket
954+
sections for defaults and other details (beware that two servers must use
955+
different address / port pairs): :ref:`dhcp4-http-ctrl-channel`,
956+
:ref:`dhcp6-http-ctrl-channel` and :ref:`d2-http-ctrl-channel`
957+
958+
For compatibility the JSON result of these HTTP/HTTPS control sockets is
959+
still encapsulated into a list.

‎doc/sphinx/arm/ddns.rst

+107-8
Original file line numberDiff line numberDiff line change
@@ -217,7 +217,7 @@ which is described below:
217217
- *Global Server Parameters* - define values which control connectivity and
218218
global server behavior.
219219

220-
- *Control Socket* - defines the Control Socket type and name.
220+
- *Control Sockets* - defines the Control Socket list.
221221

222222
- *TSIG Key Info* - defines the TSIG keys used for secure traffic with
223223
DNS servers.
@@ -274,28 +274,44 @@ illustrates how to change D2's global parameters so it will listen at
274274
If the ``ip-address`` and ``port`` are changed, the corresponding values in
275275
the DHCP servers' ``dhcp-ddns`` configuration section must be changed.
276276

277-
.. _d2-ctrl-channel:
277+
.. _d2-ctrl-channels:
278278

279279
Management API for the D2 Server
280280
--------------------------------
281281

282282
The management API allows the issuing of specific management commands,
283283
such as configuration retrieval or shutdown. For more details, see
284-
:ref:`ctrl-channel`. Currently, the only supported communication
285-
channel type is the UNIX stream socket. By default there are no sockets
284+
:ref:`ctrl-channel`. By default there are no sockets
286285
open; to instruct Kea to open a socket, the following entry in the
287286
configuration file can be used:
288287

289288
::
290289

291290
"DhcpDdns": {
292-
"control-socket": {
293-
"socket-type": "unix",
294-
"socket-name": "/path/to/the/unix/socket"
295-
},
291+
"control-sockets": [
292+
{
293+
"socket-type": "unix",
294+
"socket-name": "/path/to/the/unix/socket"
295+
}
296+
],
296297
...
297298
}
298299

300+
.. note:
301+
302+
For backward compatibility the ``control-socket`` keyword is still
303+
recognized by Kea version newer than 2.7.2: a ``control-socket`` entry
304+
is put into a ``control-sockets`` list by the configuration parser.
305+
306+
.. _d2-unix-ctrl-channel:
307+
308+
UNIX Control Socket
309+
~~~~~~~~~~~~~~~~~~~
310+
311+
Until Kea server 2.7.2 the only supported communication channel type was
312+
the UNIX stream socket with ``socket-type`` set to ``unix`` and
313+
``socket-name`` to the file path of the UNIX/LOCAL socket.
314+
299315
The length of the path specified by the ``socket-name`` parameter is
300316
restricted by the maximum length for the UNIX socket name on the
301317
operating system, i.e. the size of the ``sun_path`` field in the
@@ -354,6 +370,89 @@ An example command may look like this:
354370
}
355371
}
356372

373+
.. _d2-http-ctrl-channel:
374+
375+
HTTP/HTTPS Control Socket
376+
~~~~~~~~~~~~~~~~~~~~~~~~~
377+
378+
The ``socket-type`` must be ``http`` or ``https`` (whe the type is ``https``
379+
TLS is required). The ``socket-address`` (default ``127.0.0.1``) and
380+
``socket-port`` (default 8000) specify an IP address and port to which
381+
the HTTP service will be bound.
382+
383+
The ``trust-anchor``, ``cert-file``, ``key-file``, and ``cert-required``
384+
parameters specify the TLS setup for HTTP, i.e. HTTPS. If these parameters
385+
are not specified, HTTP is used. The TLS/HTTPS support in Kea is
386+
described in :ref:`tls`.
387+
388+
Basic HTTP authentication protects
389+
against unauthorized uses of the control agent by local users. For
390+
protection against remote attackers, HTTPS and reverse proxy of
391+
:ref:`agent-secure-connection` provide stronger security.
392+
393+
The authentication is described in the ``authentication`` block
394+
with the mandatory ``type`` parameter, which selects the authentication.
395+
Currently only the basic HTTP authentication (type basic) is supported.
396+
397+
The ``realm`` authentication parameter (default ``kea-dhcp-ddns-server``
398+
is used for error messages when the basic HTTP authentication is required
399+
but the client is not authorized.
400+
401+
When the ``clients`` authentication list is configured and not empty,
402+
basic HTTP authentication is required. Each element of the list
403+
specifies a user ID and a password. The user ID is mandatory, must
404+
be not empty, and must not contain the colon (:) character. The
405+
password is optional; when it is not specified an empty password
406+
is used.
407+
408+
.. note::
409+
410+
The basic HTTP authentication user ID and password are encoded
411+
in UTF-8, but the current Kea JSON syntax only supports the Latin-1
412+
(i.e. 0x00..0xff) Unicode subset.
413+
414+
To avoid exposing the user ID and/or the associated
415+
password, these values can be read from files. The syntax is extended by:
416+
417+
- The ``directory`` authentication parameter, which handles the common
418+
part of file paths. The default value is the empty string.
419+
420+
- The ``password-file`` client parameter, which, alongside the ``directory``
421+
parameter, specifies the path of a file that can contain the password,
422+
or when no user ID is given, the whole basic HTTP authentication secret.
423+
424+
- The ``user-file`` client parameter, which, with the ``directory`` parameter,
425+
specifies the path of a file where the user ID can be read.
426+
427+
When files are used, they are read when the configuration is loaded,
428+
to detect configuration errors as soon as possible.
429+
430+
::
431+
432+
"DhcpDdns": {
433+
"control-sockets": [
434+
{
435+
"socket-type": "https",
436+
"socket-address": "10.20.30.40",
437+
"socket-port": 8005,
438+
"trust-anchor": "/path/to/the/ca-cert.pem",
439+
"cert-file": "/path/to/the/agent-cert.pem",
440+
"key-file": "/path/to/the/agent-key.pem",
441+
"cert-required": true,
442+
"authentication": {
443+
"type": "basic",
444+
"realm": "kea-dhcp-ddns-server",
445+
"clients": [
446+
{
447+
"user": "admin",
448+
"password": "1234"
449+
} ]
450+
}
451+
}
452+
],
453+
...
454+
}
455+
357456
.. _d2-tsig-key-list-config:
358457

359458
TSIG Key List

‎doc/sphinx/arm/dhcp4-srv.rst

+115-11
Original file line numberDiff line numberDiff line change
@@ -7555,25 +7555,24 @@ Statistics can be retrieved periodically to gain more insight into Kea operation
75557555
leverages that capability is ISC Stork. See :ref:`stork` for details.
75567556

75577557

7558-
.. _dhcp4-ctrl-channel:
7558+
.. _dhcp4-ctrl-channels:
75597559

75607560
Management API for the DHCPv4 Server
75617561
====================================
75627562

75637563
The management API allows the issuing of specific management commands,
75647564
such as statistics retrieval, reconfiguration, or shutdown. For more
7565-
details, see :ref:`ctrl-channel`. Currently, the only supported
7566-
communication channel type is the UNIX stream socket. By default there are
7567-
no sockets open; to instruct Kea to open a socket, the following entry
7568-
in the configuration file can be used:
7569-
7570-
::
7565+
details, see :ref:`ctrl-channel`. By default there are no sockets
7566+
open; to instruct Kea to open a socket, the following entry in the
7567+
configuration file can be used: ::
75717568

75727569
"Dhcp4": {
7573-
"control-socket": {
7574-
"socket-type": "unix",
7575-
"socket-name": "/path/to/the/unix/socket"
7576-
},
7570+
"control-socket": [
7571+
{
7572+
"socket-type": "unix",
7573+
"socket-name": "/path/to/the/unix/socket"
7574+
}
7575+
],
75777576

75787577
"subnet4": [
75797578
{
@@ -7584,6 +7583,21 @@ in the configuration file can be used:
75847583
...
75857584
}
75867585

7586+
.. note:
7587+
7588+
For backward compatibility the ``control-socket`` keyword is still
7589+
recognized by Kea version newer than 2.7.2: a ``control-socket`` entry
7590+
is put into a ``control-sockets`` list by the configuration parser.
7591+
7592+
.. _dhcp4-unix-ctrl-channel:
7593+
7594+
UNIX Control Socket
7595+
-------------------
7596+
7597+
Until Kea server 2.7.2 the only supported communication channel type was
7598+
the UNIX stream socket with ``socket-type`` set to ``unix`` and
7599+
``socket-name`` to the file path of the UNIX/LOCAL socket.
7600+
75877601
The length of the path specified by the ``socket-name`` parameter is
75887602
restricted by the maximum length for the UNIX socket name on the administrator's
75897603
operating system, i.e. the size of the ``sun_path`` field in the
@@ -7630,6 +7644,96 @@ following statistics-related commands:
76307644

76317645
as described in :ref:`command-stats`.
76327646

7647+
.. _dhcp4-http-ctrl-channel:
7648+
7649+
HTTP/HTTPS Control Socket
7650+
-------------------------
7651+
7652+
The ``socket-type`` must be ``http`` or ``https`` (whe the type is ``https``
7653+
TLS is required). The ``socket-address`` (default ``127.0.0.1``) and
7654+
``socket-port`` (default 8000) specify an IP address and port to which
7655+
the HTTP service will be bound.
7656+
7657+
The ``trust-anchor``, ``cert-file``, ``key-file``, and ``cert-required``
7658+
parameters specify the TLS setup for HTTP, i.e. HTTPS. If these parameters
7659+
are not specified, HTTP is used. The TLS/HTTPS support in Kea is
7660+
described in :ref:`tls`.
7661+
7662+
Basic HTTP authentication protects
7663+
against unauthorized uses of the control agent by local users. For
7664+
protection against remote attackers, HTTPS and reverse proxy of
7665+
:ref:`agent-secure-connection` provide stronger security.
7666+
7667+
The authentication is described in the ``authentication`` block
7668+
with the mandatory ``type`` parameter, which selects the authentication.
7669+
Currently only the basic HTTP authentication (type basic) is supported.
7670+
7671+
The ``realm`` authentication parameter (default ``kea-dhcpv4-server``
7672+
is used for error messages when the basic HTTP authentication is required
7673+
but the client is not authorized.
7674+
7675+
When the ``clients`` authentication list is configured and not empty,
7676+
basic HTTP authentication is required. Each element of the list
7677+
specifies a user ID and a password. The user ID is mandatory, must
7678+
be not empty, and must not contain the colon (:) character. The
7679+
password is optional; when it is not specified an empty password
7680+
is used.
7681+
7682+
.. note::
7683+
7684+
The basic HTTP authentication user ID and password are encoded
7685+
in UTF-8, but the current Kea JSON syntax only supports the Latin-1
7686+
(i.e. 0x00..0xff) Unicode subset.
7687+
7688+
To avoid exposing the user ID and/or the associated
7689+
password, these values can be read from files. The syntax is extended by:
7690+
7691+
- The ``directory`` authentication parameter, which handles the common
7692+
part of file paths. The default value is the empty string.
7693+
7694+
- The ``password-file`` client parameter, which, alongside the ``directory``
7695+
parameter, specifies the path of a file that can contain the password,
7696+
or when no user ID is given, the whole basic HTTP authentication secret.
7697+
7698+
- The ``user-file`` client parameter, which, with the ``directory`` parameter,
7699+
specifies the path of a file where the user ID can be read.
7700+
7701+
When files are used, they are read when the configuration is loaded,
7702+
to detect configuration errors as soon as possible.
7703+
7704+
::
7705+
7706+
"Dhcp4": {
7707+
"control-sockets": [
7708+
{
7709+
"socket-type": "https",
7710+
"socket-name": "10.20.30.40",
7711+
"socket-port": 8004,
7712+
"trust-anchor": "/path/to/the/ca-cert.pem",
7713+
"cert-file": "/path/to/the/agent-cert.pem",
7714+
"key-file": "/path/to/the/agent-key.pem",
7715+
"cert-required": true,
7716+
"authentication": {
7717+
"type": "basic",
7718+
"realm": "kea-dhcpv4-server",
7719+
"clients": [
7720+
{
7721+
"user": "admin",
7722+
"password": "1234"
7723+
} ]
7724+
}
7725+
}
7726+
],
7727+
7728+
"subnet4": [
7729+
{
7730+
...
7731+
},
7732+
...
7733+
],
7734+
...
7735+
}
7736+
76337737
.. _dhcp4-user-contexts:
76347738

76357739
User Contexts in IPv4

0 commit comments

Comments
 (0)