From: Marcin Siodelski Date: Mon, 3 Apr 2017 13:27:00 +0000 (+0200) Subject: [5175] Added description of CA in the Developer's Guide. X-Git-Tag: trac5196_base~9^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ef65766be5b14b484f2d5b998d9fd178218e2244;p=thirdparty%2Fkea.git [5175] Added description of CA in the Developer's Guide. --- diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox index 594abc6275..602cdfc22e 100644 --- a/doc/devel/mainpage.dox +++ b/doc/devel/mainpage.dox @@ -81,6 +81,11 @@ * - @subpage d2TransDetail * - @subpage d2StateModel * - @subpage d2TransExecExample + * - @subpage controlAgent + * - @subpage ctrlAgentHttp + * - @subpage ctrlAgentCreatingResponse + * - @subpage ctrlAgentCommandMgr + * - @subpage CtrlAgentSecurity * - @subpage lfc * - @subpage lfcProcessing * - @subpage lfcFiles diff --git a/doc/guide/agent.xml b/doc/guide/agent.xml index 50f8ceb312..decf592318 100644 --- a/doc/guide/agent.xml +++ b/doc/guide/agent.xml @@ -25,6 +25,33 @@ found in Kea Developer's 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 more or services, the CA will forward the + command to specified services and return the accumulated responses. + + + + + + If service is not specified or is an empty list, the CA will handle + the command if it supports it. + + + + +
diff --git a/doc/guide/ctrl-channel.xml b/doc/guide/ctrl-channel.xml index d057752cc6..b24b38f09f 100644 --- a/doc/guide/ctrl-channel.xml +++ b/doc/guide/ctrl-channel.xml @@ -118,7 +118,10 @@ processing DHCP messages to apply changes to the database). Nevetheless, these situations are rather rare and, in most cases, when the service parameter contains a name of the service - the commands are simply forwarded by the CA. + the commands are simply forwarded by the CA. The forwarded command + includes the service parameter but this parameter + is ignored by the receiving server. This parameter is only meaningful + to the CA. @@ -131,6 +134,29 @@ DHCPv4 server's configuration and so on. + + The following list contains a mapping of the values carried within the + service parameter to the servers to which the commands + are forwarded: + + + + dhcp4 - the command is forwarded to the + kea-dhcp4 server, + + + + dhcp6 - the command is forwarded to the + kea-dhcp6 server, + + + + d2 - the command is forwarded to the + kea-d2 server. + + + + The server processing the incoming command will send a response of the form: diff --git a/src/bin/agent/Makefile.am b/src/bin/agent/Makefile.am index cac15dcfda..e67c5727af 100644 --- a/src/bin/agent/Makefile.am +++ b/src/bin/agent/Makefile.am @@ -14,7 +14,7 @@ CLEANFILES = *.gcno *.gcda ca_messages.h ca_messages.cc s-messages man_MANS = kea-ctrl-agent.8 DISTCLEANFILES = $(man_MANS) EXTRA_DIST = $(man_MANS) kea-ctrl-agent.xml -EXTRA_DIST += agent_hooks.dox +EXTRA_DIST += agent.dox agent_hooks.dox if GENERATE_DOCS kea-ctrl-agent.8: kea-ctrl-agent.xml diff --git a/src/bin/agent/agent.dox b/src/bin/agent/agent.dox new file mode 100644 index 0000000000..b39d43f3a6 --- /dev/null +++ b/src/bin/agent/agent.dox @@ -0,0 +1,128 @@ +// Copyright (C) 2017 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/. + +/** + @page controlAgent Control Agent Component + +Kea 1.2 release has introduced the Control Agent component (CA), which +is started by the "kea-ctrl-agent" binary. The CA exposes a RESTful API +which is used by the administrators to manage Kea servers' instances. + +In the most typical case, the CA forwards commands received over the +RESTful API to the respetive Kea servers, e.g. DHCPv4 server, DHCPv6 +server etc. The communication between the CA and other servers is +established with the use of unix domain sockets. This is possible because +the CA is running on the same system as other Kea services to which +messages are forwarded. + +The CA can forward the same command to multiple Kea services and return +an aggregated response (from all services) over the RESTful API. The +"service" parameter included in the client's command can contain one +or multiple services at which the command is targetted. The CA will +iterate over this list and forward the command to each of them +individually. + +In some cases, the commands containing the "service" value can be handled +directly by the CA. This is usually the case when the CA is running +with hooks libraries attached. The hooks libraries must implement +callouts for the "control_command_receive" hook point, which are +invoked by the CA when the command is received. If the hooks libraries +set the 'skip' status, it is an indication to the CA that the command +has been processed by the CA and simply return a response created by the +hooks libraries to the client. An example of the hooks library attached to +the CA and handling the commands for other services is the library which +stores or retrieves some data from the SQL database. + +The "service" parameter is optional. If it is not included in the command +(or it is blank list), it is an indication that the command relates to +CA and that the CA should handle it, e.g. return its own configuration in +response to a "config-get" command. + +@section ctrlAgentHttp Receiving commands over HTTP + +Control Agent uses libkea-http library to establish HTTP connections, +receive messages and send responses over HTTP. This library uses boost ASIO +for creating TCP connections and asynchronously receive and send the data +over the sockets. + +The @ref isc::http::HttpListener provides an entry point to this library. +It is used by the CA to bind the acceptor to the specific address and +port. When the client connects to this address and port, the acceptor's +callback function is invoked which opens new connection and starts +receiving the data over the socket. The @ref isc::http::HttpConnection +implements a logic to read and parse the received data. Each new TCP +connection has a unique instance of the @ref isc::http::HttpConnection +associated. When the portion of data is received (asynchronously) over +the socket the data is provided to the instance of the +@ref isc::http::HttpRequestParser object (unique per connection) and +data parsing is continued until the parser runs out of data or until +the entire HTTP request has been received. The +@ref isc::http::HttpRequestParser signals these events using the +@ref isc::http::HttpRequestParser::needData and +@ref isc::http::HttpRequestParser::httpParseOk respectively. + +libkea-http is designed to handle processing messages carrying different +content types. The Control Agent uses "application/json" content +type which describes messages with JSON structures carried within the +message body. The JSON structures represent commands sent to the Kea +server(s) by the controlling clients. libkea-http provides generic classes +(derived from @ref isc::http::HttpRequest) which faciliate validation of +messsages holding various content types. +CA uses @ref isc::http::PostHttpRequestJson, which encapsulate messages +sent using HTTP POST and including JSON content, to represent received messages. + +@section ctrlAgentCreatingResponse Creating HTTP responses + +The @ref isc::http::HttpResponseCreatorFactory is an interface which should +be implemented by components using libkea-http to generate instances of +the HTTP responses of a desired type. The instance of the factory class is +provided to the @ref isc::http::HttpListener via its constructor. The listener +calls an implementation of the +@ref isc::http::HttpResponseCreatorFactory::create when the new HTTP +message has been received and parsed. + +The CA component includes the @ref isc::agent::CtrlAgentResponseCreatorFactory +class. Its @c create() method implementation returns +an instance of the @ref isc::agent::CtrlAgentResponseCreator, which is a +derivation of the @ref isc::http::HttpResponseCreator. This creator creates +instances of the @ref isc::http::HttpResponseJson, holding responses to +the commands in the JSON format. + +@section ctrlAgentCommandMgr Handling commands with Command Manager + +The @ref isc::agent::CtrlAgentCommandMgr is a derivation of the +@ref isc::config::HookedCommandMgr and adds capability to forward received +(over HTTP) commands to the respective Kea servers. The +@ref isc::agent::CtrlAgentCommandMgr forwards commands over the unix domain +socket, using @ref isc::asiolink::UnixDomainSocket class. All responses +to a particular command (possibly received from multiple Kea servers) are +aggregated within a JSON list and sent back to the controlling client over +HTTP. + +In some cases the responses may be generated locally (without forwarding). +Typically, the command will be generated by the CA when the command sent +by the client lacks the "service" parameter, which indicates that the +command is targetted at the CA itself. In some cases the commands can also +be processed by the hooks libraries attached to the CA. + +@section CtrlAgentSecurity Security considerations + +The Control Agent doesn't provide any mechanisms to secure the communication +over the RESTful API. In the design of the CA we have considered including builtin +HTTPS solutions (HTTP + TLS), making use of crypto libraries supported by Kea. +It was evetually decided to not implement the secure layer within Kea for the following resons: +- additional code complexity which requires maintenance, bug fixing and + monitoring for security vulnerabilities in the OpenSSL/Botan code, +- OpenSSL/Botan code may be awkward to use and it is likely we wouldn't + implement it right, +- need to support two crypto backends: OpenSSL and Botan which puts significant + burden on Kea maintenance. + +In the installations where securing command channel is critical (most of the +installations?), a reverse HTTP proxy can be setup using one of the third +party HTTP server implementations, e.g. Apache, nginx etc. + +*/ \ No newline at end of file diff --git a/src/bin/agent/agent-hooks.dox b/src/bin/agent/agent_hooks.dox similarity index 100% rename from src/bin/agent/agent-hooks.dox rename to src/bin/agent/agent_hooks.dox