Adding upstream version 2.2.0.upstream/2.2.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 378 insertions, 0 deletions

diff --git a/doc/sphinx/arm/agent.rst b/doc/sphinx/arm/agent.rst
new file mode 100644
index 0000000..8e559b0
--- /dev/null
+++ b/doc/sphinx/arm/agent.rst
@@ -0,0 +1,378 @@
+.. _kea-ctrl-agent:
+
+*********************
+The Kea Control Agent
+*********************
+
+.. _agent-overview:
+
+Overview of the Kea Control Agent
+=================================
+
+The Kea Control Agent (CA) is a daemon which exposes a RESTful control
+interface for managing Kea servers. The daemon 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
+:ref:`ctrl-channel`.
+
+The CA can use hook libraries to provide support for additional commands
+or to program custom behavior of existing commands. Such hook libraries must
+implement callouts for the ``control_command_receive`` hook point. Details
+about creating new hook libraries and supported hook points can be found
+in the `Kea Developer's
+Guide <https://reports.kea.isc.org/dev_guide/>`__.
+
+The CA processes received commands according to the following algorithm:
+
+-  Pass command into any installed hooks (regardless of service
+   value(s)). If the command is handled by a hook, return the response.
+
+-  If the service specifies one or more services, forward the command to
+   the specified services and return the accumulated responses.
+
+-  If the service is not specified or is an empty list, handle the
+   command if the CA supports it.
+
+.. _agent-configuration:
+
+Configuration
+=============
+
+The following example demonstrates the basic CA configuration.
+
+::
+
+   {
+       "Control-agent": {
+           "http-host": "10.20.30.40",
+           "http-port": 8000,
+           "trust-anchor": "/path/to/the/ca-cert.pem",
+           "cert-file": "/path/to/the/agent-cert.pem",
+           "key-file": "/path/to/the/agent-key.pem",
+           "cert-required": true,
+           "authentication": {
+               "type": "basic",
+               "realm": "kea-control-agent",
+               "clients": [
+               {
+                   "user": "admin",
+                   "password": "1234"
+               } ]
+           },
+
+           "control-sockets": {
+               "dhcp4": {
+                   "comment": "main server",
+                   "socket-type": "unix",
+                   "socket-name": "/path/to/the/unix/socket-v4"
+               },
+               "dhcp6": {
+                   "socket-type": "unix",
+                   "socket-name": "/path/to/the/unix/socket-v6",
+                   "user-context": { "version": 3 }
+               },
+               "d2": {
+                   "socket-type": "unix",
+                   "socket-name": "/path/to/the/unix/socket-d2"
+               },
+           },
+
+           "hooks-libraries": [
+           {
+               "library": "/opt/local/control-agent-commands.so",
+               "parameters": {
+                   "param1": "foo"
+               }
+           } ],
+
+           "loggers": [ {
+               "name": "kea-ctrl-agent",
+               "severity": "INFO"
+           } ]
+       }
+   }
+
+The ``http-host`` and ``http-port`` parameters specify an IP address and
+port to which HTTP service will be bound. In the example configuration
+provided above, the RESTful service will be available at the URL
+``https://10.20.30.40:8000/``. If these parameters are not specified, the
+default URL is ``http://127.0.0.1:8000/``.
+
+When using Kea's HA hook library with multi-threading, make sure
+that the address:port combination used for CA is
+different from the HA peer URLs, which are strictly
+for internal HA traffic between the peers. User commands should
+still be sent via CA.
+
+The ``trust-anchor``, ``cert-file``, ``key-file``, and ``cert-required``
+parameters specify the TLS setup for HTTP, i.e. HTTPS. If these parameters
+are not specified, HTTP is used. The TLS/HTTPS support in Kea is
+described in :ref:`tls`.
+
+As mentioned in :ref:`agent-overview`, the CA can forward
+received commands to the Kea servers for processing. For example,
+``config-get`` is sent to retrieve the configuration of one of the Kea
+services. When the CA receives this command, including a ``service``
+parameter indicating that the client wishes to retrieve the
+configuration of the DHCPv4 server, the CA forwards the command to that
+server and passes the received response back to the client. More about
+the ``service`` parameter and the general structure of commands can be
+found in :ref:`ctrl-channel`.
+
+The CA uses UNIX domain sockets to forward control commands and receive
+responses from other Kea services. The ``dhcp4``, ``dhcp6``, and ``d2``
+maps specify the files to which UNIX domain sockets are bound. In the
+configuration above, the CA connects to the DHCPv4 server via
+``/path/to/the/unix/socket-v4`` to forward the commands to it.
+Obviously, the DHCPv4 server must be configured to listen to connections
+via this same socket. In other words, the command-socket configuration
+for the DHCPv4 server and the CA (for that server) must match. Consult
+:ref:`dhcp4-ctrl-channel`, :ref:`dhcp6-ctrl-channel`, and
+:ref:`d2-ctrl-channel` to learn how the socket configuration is
+specified for the DHCPv4, DHCPv6, and D2 services.
+
+User contexts can store arbitrary data as long as they are in valid JSON
+syntax and their top-level element is a map (i.e. the data must be
+enclosed in curly brackets). Some hook libraries may expect specific
+formatting; please consult the relevant hook library documentation for
+details.
+
+User contexts can be specified on either global scope, control socket,
+basic authentication, or loggers. One other useful feature is the
+ability to store comments or descriptions; the parser translates a
+"comment" entry into a user context with the entry, which allows a
+comment to be attached within the configuration itself.
+
+Basic HTTP authentication was added in Kea 1.9.0; it protects
+against unauthorized uses of the control agent by local users. For
+protection against remote attackers, HTTPS and reverse proxy of
+:ref:`agent-secure-connection` provide stronger security.
+
+The authentication is described in the ``authentication`` block
+with the mandatory ``type`` parameter, which selects the authentication.
+Currently only the basic HTTP authentication (type basic) is supported.
+
+The ``realm`` authentication parameter is used for error messages when
+the basic HTTP authentication is required but the client is not
+authorized.
+
+When the ``clients`` authentication list is configured and not empty,
+basic HTTP authentication is required. Each element of the list
+specifies a user ID and a password. The user ID is mandatory, must
+be not empty, and must not contain the colon (:) character. The
+password is optional; when it is not specified an empty password
+is used.
+
+.. note::
+
+   The basic HTTP authentication user ID and password are encoded
+   in UTF-8, but the current Kea JSON syntax only supports the Latin-1
+   (i.e. 0x00..0xff) Unicode subset.
+
+To avoid to expose the password or both the user ID and the associated
+password these values can be read from files. The syntax was extended by:
+
+-  The ``directory`` authentication parameter which handles the common
+   part of file paths. By default the value is the empty string.
+
+-  The``password-file`` client parameter which with the ``directory``
+   parameter specifies the path of a file where the password or when no
+   user ID is given the whole basic HTTP authentication secret before
+   encoding can be read.
+
+-  The ``user-file`` client parameter which with the ``directory`` parameter
+   specifies the path of a file where the user ID can be read.
+
+When files are used they are read when the configuration is loaded in order
+to detect configuration errors as soon as possible.
+
+Hook libraries can be loaded by the Control Agent in the same way as
+they are loaded by the DHCPv4 and DHCPv6 servers. The CA currently
+supports one hook point - ``control_command_receive`` - which makes it
+possible to delegate processing of some commands to the hook library.
+The ``hooks-libraries`` list contains the list of hook libraries that
+should be loaded by the CA, along with their configuration information
+specified with ``parameters``.
+
+Please consult :ref:`logging` for the details on how to configure
+logging. The CA's root logger's name is ``kea-ctrl-agent``, as given in
+the example above.
+
+.. _agent-secure-connection:
+
+Secure Connections (in Versions Prior to Kea 1.9.6)
+===================================================
+
+The Control Agent does not natively support secure HTTP connections, like
+SSL or TLS, before Kea 1.9.6.
+
+To set up a secure connection, please use one of the
+available third-party HTTP servers and configure it to run as a reverse
+proxy to the Control Agent. Kea has been tested with two major HTTP
+server implementations working as a reverse proxy: Apache2 and nginx.
+Example configurations, including extensive comments, are provided in
+the ``doc/examples/https/`` directory.
+
+The reverse proxy forwards HTTP requests received over a secure
+connection to the Control Agent using unsecured 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 well. In
+this case, security depends on the protection of the communications
+between the reverse proxy and the Control Agent.
+
+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
+authenticates the client by checking whether the presented certificate
+is signed by the certificate authority used by the server.
+
+To illustrate this, the following is 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.
+
+::
+
+   #   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 a
+   #   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
+   #
+   #   curl syntax for basic authentication is -u user:password
+   #
+   #
+   #   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 certificates 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:8000.
+           location /kea {
+               proxy_pass http://127.0.0.1:8000;
+           }
+       }
+   }
+
+.. note::
+
+   The configuration snippet provided above is for testing
+   purposes only. It should be modified according to the security
+   policies and best practices of the administrator's organization.
+
+When using an HTTP client without TLS support, such as ``kea-shell``, it
+is possible to use an HTTP/HTTPS translator such as ``stunnel`` in client mode. A
+sample configuration is provided in the ``doc/examples/https/shell/``
+directory.
+
+Secure Connections (in Kea 1.9.6 and Newer)
+===========================================
+
+Since Kea 1.9.6, the Control Agent natively supports secure
+HTTP connections using TLS. This allows protection against users from
+the node where the agent runs, something that a reverse proxy cannot
+provide. More about TLS/HTTPS support in Kea can be found in :ref:`tls`.
+
+TLS is configured using three string parameters, giving file names and
+a boolean parameter:
+
+-  The ``trust-anchor`` specifies the Certification Authority file name or
+   directory path.
+
+-  The ``cert-file`` specifies the server certificate file name.
+
+-  The ``key-file`` specifies the private key file name. The file must not
+   be encrypted.
+
+-  The ``cert-required`` specifies whether client certificates are required
+   or optional. The default is to require them and to perform mutual
+   authentication.
+
+The file format is PEM. Either all the string parameters are specified and
+HTTP over TLS (HTTPS) is used, or none is specified and plain HTTP is used.
+Configuring only one or two string parameters results in an error.
+
+.. note::
+
+   When client certificates are not required, only the server side is
+   authenticated, i.e. the communication is encrypted with an unknown
+   client. This protects only against passive attacks; active
+   attacks, such as "man-in-the-middle," are still possible.
+
+.. note::
+
+   No standard HTTP authentication scheme cryptographically binds its end
+   entity with TLS. This means that the TLS client and server can be
+   mutually authenticated, but there is no proof they are the same as
+   for the HTTP authentication.
+
+Since Kea 1.9.6, the ``kea-shell`` tool supports TLS.
+
+.. _agent-launch:
+
+Starting the Control Agent
+==========================
+
+The CA is started by running its binary and specifying the configuration
+file it should use. For example:
+
+.. code-block:: console
+
+   $ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf
+
+It can be started by ``keactrl`` as well (see :ref:`keactrl`).
+
+.. _agent-clients:
+
+Connecting to the Control Agent
+===============================
+
+For an example of a tool that can take advantage of the RESTful API, see
+:ref:`kea-shell`.