1.. _kea-ctrl-agent: 2 3********************* 4The Kea Control Agent 5********************* 6 7.. _agent-overview: 8 9Overview of the Kea Control Agent 10================================= 11 12The Kea Control Agent (CA) is a daemon which exposes a RESTful control 13interface for managing Kea servers. The daemon can receive control 14commands over HTTP and either forward these commands to the respective 15Kea servers or handle these commands on its own. The determination 16whether the command should be handled by the CA or forwarded is made by 17checking the value of the `service` parameter, which may be included in 18the command from the controlling client. The details of the supported 19commands, as well as their structures, are provided in 20:ref:`ctrl-channel`. 21 22The CA can use hook libraries to provide support for additional commands 23or to program custom behavior of existing commands. Such hook libraries must 24implement callouts for the ``control_command_receive`` hook point. Details 25about creating new hook libraries and supported hook points can be found 26in the `Kea Developer's 27Guide <https://reports.kea.isc.org/dev_guide/>`__. 28 29The CA processes received commands according to the following algorithm: 30 31- Pass command into any installed hooks (regardless of service 32 value(s)). If the command is handled by a hook, return the response. 33 34- If the service specifies one or more services, forward the command to 35 the specified services and return the accumulated responses. 36 37- If the service is not specified or is an empty list, handle the 38 command if the CA supports it. 39 40.. _agent-configuration: 41 42Configuration 43============= 44 45The following example demonstrates the basic CA configuration. 46 47:: 48 49 { 50 "Control-agent": { 51 "http-host": "10.20.30.40", 52 "http-port": 8000, 53 "trust-anchor": "/path/to/the/ca-cert.pem", 54 "cert-file": "/path/to/the/agent-cert.pem", 55 "key-file": "/path/to/the/agent-key.pem", 56 "cert-required": true, 57 "authentication": { 58 "type": "basic", 59 "realm": "kea-control-agent", 60 "clients": [ 61 { 62 "user": "admin", 63 "password": "1234" 64 } ] 65 }, 66 67 "control-sockets": { 68 "dhcp4": { 69 "comment": "main server", 70 "socket-type": "unix", 71 "socket-name": "/path/to/the/unix/socket-v4" 72 }, 73 "dhcp6": { 74 "socket-type": "unix", 75 "socket-name": "/path/to/the/unix/socket-v6", 76 "user-context": { "version": 3 } 77 }, 78 "d2": { 79 "socket-type": "unix", 80 "socket-name": "/path/to/the/unix/socket-d2" 81 }, 82 }, 83 84 "hooks-libraries": [ 85 { 86 "library": "/opt/local/control-agent-commands.so", 87 "parameters": { 88 "param1": "foo" 89 } 90 } ], 91 92 "loggers": [ { 93 "name": "kea-ctrl-agent", 94 "severity": "INFO" 95 } ] 96 } 97 } 98 99The ``http-host`` and ``http-port`` parameters specify an IP address and 100port to which HTTP service will be bound. In the example configuration 101provided above, the RESTful service will be available at the URL 102``https://10.20.30.40:8000/``. If these parameters are not specified, the 103default URL is ``http://127.0.0.1:8000/``. 104 105When using Kea's HA hook library with multi-threading, make sure 106that the address:port combination used for CA is 107different from the HA peer URLs, which are strictly 108for internal HA traffic between the peers. User commands should 109still be sent via CA. 110 111The ``trust-anchor``, ``cert-file``, ```key-file``, and ``cert-required`` 112parameters specify the TLS setup for HTTP, i.e. HTTPS. If these parameters 113are not specified, HTTP is used. The TLS/HTTPS support in Kea is 114described in :ref:`tls`. 115 116As mentioned in :ref:`agent-overview`, the CA can forward 117received commands to the Kea servers for processing. For example, 118``config-get`` is sent to retrieve the configuration of one of the Kea 119services. When the CA receives this command, including a ``service`` 120parameter indicating that the client wishes to retrieve the 121configuration of the DHCPv4 server, the CA forwards the command to that 122server and passes the received response back to the client. More about 123the ``service`` parameter and the general structure of commands can be 124found in :ref:`ctrl-channel`. 125 126The CA uses UNIX domain sockets to forward control commands and receive 127responses from other Kea services. The ``dhcp4``, ``dhcp6``, and ``d2`` 128maps specify the files to which UNIX domain sockets are bound. In the 129configuration above, the CA connects to the DHCPv4 server via 130``/path/to/the/unix/socket-v4`` to forward the commands to it. 131Obviously, the DHCPv4 server must be configured to listen to connections 132via this same socket. In other words, the command-socket configuration 133for 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 136specified for the DHCPv4, DHCPv6, and D2 services. 137 138.. warning:: 139 140 ``dhcp4-server``, ``dhcp6-server``, and ``d2-server`` were renamed to 141 ``dhcp4``, ``dhcp6``, and ``d2`` respectively in Kea 1.2. If 142 migrating from Kea 1.2, be sure to modify the CA configuration to use 143 this new naming convention. 144 145User contexts can store arbitrary data as long as they are in valid JSON 146syntax and their top-level element is a map (i.e. the data must be 147enclosed in curly brackets). Some hook libraries may expect specific 148formatting; please consult the relevant hook library documentation for 149details. 150 151User contexts can be specified on either global scope, control socket, 152basic authentication, or loggers. One other useful feature is the 153ability to store comments or descriptions; the parser translates a 154"comment" entry into a user context with the entry, which allows a 155comment to be attached within the configuration itself. 156 157Basic HTTP authentication was added in Kea 1.9.0; it protects 158against unauthorized uses of the control agent by local users. For 159protection against remote attackers, HTTPS and reverse proxy of 160:ref:`agent-secure-connection` provide stronger security. 161 162The authentication is described in the ``authentication`` block 163with the mandatory ``type`` parameter, which selects the authentication. 164Currently only the basic HTTP authentication (type basic) is supported. 165 166The ``realm`` authentication parameter is used for error messages when 167the basic HTTP authentication is required but the client is not 168authorized. 169 170When the ``clients`` authentication list is configured and not empty, 171basic HTTP authentication is required. Each element of the list 172specifies a user ID and a password. The user ID is mandatory, must 173be not empty, and must not contain the colon (:) character. The 174password is optional; when it is not specified an empty password 175is used. 176 177.. note:: 178 179 The basic HTTP authentication user ID and password are encoded 180 in UTF-8, but the current Kea JSON syntax only supports the Latin-1 181 (i.e. 0x00..0xff) Unicode subset. 182 183Hook libraries can be loaded by the Control Agent in the same way as 184they are loaded by the DHCPv4 and DHCPv6 servers. The CA currently 185supports one hook point - ``control_command_receive`` - which makes it 186possible to delegate processing of some commands to the hook library. 187The ``hooks-libraries`` list contains the list of hook libraries that 188should be loaded by the CA, along with their configuration information 189specified with ``parameters``. 190 191Please consult :ref:`logging` for the details on how to configure 192logging. The CA's root logger's name is ``kea-ctrl-agent``, as given in 193the example above. 194 195.. _agent-secure-connection: 196 197Secure Connections (in Versions Prior to Kea 1.9.6) 198=================================================== 199 200The Control Agent does not natively support secure HTTP connections, like 201SSL or TLS, before Kea 1.9.6. 202 203To set up a secure connection, please use one of the 204available third-party HTTP servers and configure it to run as a reverse 205proxy to the Control Agent. Kea has been tested with two major HTTP 206server implementations working as a reverse proxy: Apache2 and nginx. 207Example configurations, including extensive comments, are provided in 208the ``doc/examples/https/`` directory. 209 210The reverse proxy forwards HTTP requests received over a secure 211connection to the Control Agent using unsecured HTTP. Typically, the 212reverse proxy and the Control Agent are running on the same machine, but 213it is possible to configure them to run on separate machines as well. In 214this case, security depends on the protection of the communications 215between the reverse proxy and the Control Agent. 216 217Apart from providing the encryption layer for the control channel, a 218reverse proxy server is also often used for authentication of the 219controlling clients. In this case, the client must present a valid 220certificate when it connects via reverse proxy. The proxy server 221authenticates the client by checking whether the presented certificate 222is signed by the certificate authority used by the server. 223 224To illustrate this, the following is a sample configuration for the 225nginx server running as a reverse proxy to the Kea Control Agent. The 226server enables authentication of the clients using certificates. 227 228:: 229 230 # The server certificate and key can be generated as follows: 231 # 232 # openssl genrsa -des3 -out kea-proxy.key 4096 233 # openssl req -new -x509 -days 365 -key kea-proxy.key -out kea-proxy.crt 234 # 235 # The CA certificate and key can be generated as follows: 236 # 237 # openssl genrsa -des3 -out ca.key 4096 238 # openssl req -new -x509 -days 365 -key ca.key -out ca.crt 239 # 240 # 241 # The client certificate needs to be generated and signed: 242 # 243 # openssl genrsa -des3 -out kea-client.key 4096 244 # openssl req -new -key kea-client.key -out kea-client.csr 245 # openssl x509 -req -days 365 -in kea-client.csr -CA ca.crt \ 246 # -CAkey ca.key -set_serial 01 -out kea-client.crt 247 # 248 # Note that the "common name" value used when generating the client 249 # and the server certificates must differ from the value used 250 # for the CA certificate. 251 # 252 # The client certificate must be deployed on the client system. 253 # In order to test the proxy configuration with "curl", run a 254 # command similar to the following: 255 # 256 # curl -k --key kea-client.key --cert kea-client.crt -X POST \ 257 # -H Content-Type:application/json -d '{ "command": "list-commands" }' \ 258 # https://kea.example.org/kea 259 # 260 # curl syntax for basic authentication is -u user:password 261 # 262 # 263 # nginx configuration starts here. 264 265 events { 266 } 267 268 http { 269 # HTTPS server 270 server { 271 # Use default HTTPS port. 272 listen 443 ssl; 273 # Set server name. 274 server_name kea.example.org; 275 276 # Server certificate and key. 277 ssl_certificate /path/to/kea-proxy.crt; 278 ssl_certificate_key /path/to/kea-proxy.key; 279 280 # Certificate Authority. Client certificates must be signed by the CA. 281 ssl_client_certificate /path/to/ca.crt; 282 283 # Enable verification of the client certificate. 284 ssl_verify_client on; 285 286 # For URLs such as https://kea.example.org/kea, forward the 287 # requests to http://127.0.0.1:8000. 288 location /kea { 289 proxy_pass http://127.0.0.1:8000; 290 } 291 } 292 } 293 294.. 295 296.. note:: 297 298 Note that the configuration snippet provided above is for testing 299 purposes only. It should be modified according to the security 300 policies and best practices of the administrator's organization. 301 302When using an HTTP client without TLS support, such as ``kea-shell``, it 303is possible to use an HTTP/HTTPS translator such as ``stunnel`` in client mode. A 304sample configuration is provided in the ``doc/examples/https/shell/`` 305directory. 306 307Secure Connections (in Kea 1.9.6 and Newer) 308=========================================== 309 310Since Kea 1.9.6, the Control Agent natively supports secure 311HTTP connections using TLS. This allows protection against users from 312the node where the agent runs, something that a reverse proxy cannot 313provide. More about TLS/HTTPS support in Kea can be found in :ref:`tls`. 314 315TLS is configured using three string parameters, giving file names and 316a boolean parameter: 317 318- The ``trust-anchor`` specifies the Certification Authority file name or 319 directory path. 320 321- The ``cert-file`` specifies the server certificate file name. 322 323- The ``key-file`` specifies the private key file name. The file must not 324 be encrypted. 325 326- The ``cert-required`` specifies whether client certificates are required 327 or optional. The default is to require them and to perform mutual 328 authentication. 329 330The file format is PEM. Either all the string parameters are specified and 331HTTP over TLS aka HTTPS is used, or none is specified and plain HTTP is used. 332Configuring only one or two string parameters results in an error. 333 334.. note:: 335 336 When client certificates are not required, only the server side is 337 authenticated, i.e. the communication is encrypted with an unknown 338 client. This protects only against passive attacks; active 339 attacks, such as "Man in the Middle," are still possible. 340 341.. note:: 342 343 No standard HTTP authentication scheme cryptographically binds its end 344 entity with TLS. This means that the TLS client and server can be 345 mutually authenticated, but there is no proof they are the same as 346 for the HTTP authentication. 347 348Since Kea 1.9.6, the ``kea-shell`` tool supports TLS. 349 350.. _agent-launch: 351 352Starting the Control Agent 353========================== 354 355The CA is started by running its binary and specifying the configuration 356file it should use. For example: 357 358.. code-block:: console 359 360 $ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf 361 362It can be started by keactrl as well (see :ref:`keactrl`). 363 364.. _agent-clients: 365 366Connecting to the Control Agent 367=============================== 368 369For an example of a tool that can take advantage of the RESTful API, see 370:ref:`kea-shell`. 371