From: Francis Dupont Date: Mon, 13 Jul 2020 08:14:25 +0000 (+0200) Subject: [#1304] Updated CA doc X-Git-Tag: Kea-1.9.0~145 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ee3c8f2d1c30e33735b8876448a3a7f3d0ebb673;p=thirdparty%2Fkea.git [#1304] Updated CA doc --- diff --git a/doc/sphinx/arm/agent.rst b/doc/sphinx/arm/agent.rst index 51bd64aae0..37c215a12a 100644 --- a/doc/sphinx/arm/agent.rst +++ b/doc/sphinx/arm/agent.rst @@ -50,6 +50,7 @@ The following example demonstrates the basic CA configuration. "Control-agent": { "http-host": "10.20.30.40", "http-port": 8000, + "basic-authentication-realm": "kea-control-agent", "control-sockets": { "dhcp4": { @@ -68,6 +69,12 @@ The following example demonstrates the basic CA configuration. }, }, + "basic-authentications": [ + { + "user": "admin", + "password": "1234" + } ], + "hooks-libraries": [ { "library": "/opt/local/control-agent-commands.so", @@ -125,10 +132,32 @@ formatting; please consult the relevant hook library documentation for details. User contexts can be specified on either global scope, control socket, -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 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. + +The basic HTTP authentication was added by Kea 1.7.10. It protects +not authorized uses of the control agent by local users. For the +protection against remote attackers HTTPS and reverse proxy of +:ref:`agent-secure-connection` provide a stronger security. + +The ``basic-authentication-realm`` is used for error message when +the basic HTTP authentication is mandatory but the client is not +authorized. + +When the ``basic-authentications`` list is configured and not empty +the 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. Hooks 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 @@ -151,7 +180,7 @@ The Control Agent does not natively support secure HTTP connections like SSL or TLS. In order to setup 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 implentations working as a reverse proxy: Apache2 and nginx. +server implementations working as a reverse proxy: Apache2 and nginx. Example configurations, including extensive comments, are provided in the ``doc/examples/https/`` directory. @@ -205,6 +234,7 @@ server enables authentication of the clients using certificates. # -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. diff --git a/doc/sphinx/arm/shell.rst b/doc/sphinx/arm/shell.rst index 75ba6a543d..9380a316aa 100644 --- a/doc/sphinx/arm/shell.rst +++ b/doc/sphinx/arm/shell.rst @@ -22,6 +22,8 @@ As the primary purpose of the Kea shell is as a tool in a scripting environment, it is not interactive. However, following simple guidelines it can be run manually. +Kea 1.7.10 introduced basic HTTP authentication support. + Shell Usage =========== @@ -29,7 +31,7 @@ Shell Usage .. code-block:: console - $ kea-shell [--host hostname] [--port number] [--path path] [--timeout seconds] [--service service-name] [command] + $ kea-shell [--host hostname] [--port number] [--path path] [--auth-user] [--auth-password] [--timeout seconds] [--service service-name] [command] where: @@ -43,6 +45,13 @@ where: specified, an empty path is used. As the CA listens at the empty path, this parameter is useful only with a reverse proxy. +- ``--auth-user`` specifies the user id for basic HTTP authentication. + If not specified or specified as the empty string authentication is + not used. + +- ``--auth-password`` specifies the password for basic HTTP authentication. + If not specified but the user id is specified an empty password is used. + - ``--timeout seconds`` specifies the timeout (in seconds) for the connection. If not given, 10 seconds is used. diff --git a/doc/sphinx/man/kea-shell.8.rst b/doc/sphinx/man/kea-shell.8.rst index fb88cdc419..2fe12ee410 100644 --- a/doc/sphinx/man/kea-shell.8.rst +++ b/doc/sphinx/man/kea-shell.8.rst @@ -51,12 +51,12 @@ The arguments are as follows: parameter is useful only with a reverse proxy. ``--auth-user`` - Specifies the user name for basic HTTP authentication. If not specified + Specifies the user id for basic HTTP authentication. If not specified or specified as the empty string authentication is not used. ``--auth-password`` Specifies the password for basic HTTP authentication. If not specified - but the user name is specified an empty password is used. + but the user id is specified an empty password is used. ``--timeout`` Specifies the connection timeout in seconds. If not specified, 10 diff --git a/src/bin/shell/kea-shell.rst b/src/bin/shell/kea-shell.rst index 6a721f9699..b10483f97e 100644 --- a/src/bin/shell/kea-shell.rst +++ b/src/bin/shell/kea-shell.rst @@ -50,12 +50,12 @@ The arguments are as follows: parameter is useful only with a reverse proxy. ``--auth-user`` - Specifies the user name for basic HTTP authentication. If not specified + Specifies the user id for basic HTTP authentication. If not specified or specified as the empty string authentication is not used. ``--auth-password`` Specifies the password for basic HTTP authentication. If not specified - but the user name is specified an empty password is used. + but the user id is specified an empty password is used. ``--timeout`` Specifies the connection timeout in seconds. If not specified, 10