Kea 2.0.2
ca_command_mgr.cc
Go to the documentation of this file.
1// Copyright (C) 2017-2020 Internet Systems Consortium, Inc. ("ISC")
2//
3// This Source Code Form is subject to the terms of the Mozilla Public
4// License, v. 2.0. If a copy of the MPL was not distributed with this
5// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6
7#include <config.h>
8
9#include <agent/ca_cfg_mgr.h>
11#include <agent/ca_controller.h>
12#include <agent/ca_log.h>
13#include <agent/ca_process.h>
15#include <asiolink/io_service.h>
18#include <cc/data.h>
19#include <cc/json_feed.h>
21#include <config/timeouts.h>
22#include <boost/pointer_cast.hpp>
23#include <iterator>
24#include <sstream>
25#include <string>
26#include <vector>
27
28using namespace isc::asiolink;
29using namespace isc::config;
30using namespace isc::data;
31using namespace isc::hooks;
32using namespace isc::process;
33
34namespace isc {
35namespace agent {
36
37CtrlAgentCommandMgr&
39 static CtrlAgentCommandMgr command_mgr;
40 return (command_mgr);
41}
42
43CtrlAgentCommandMgr::CtrlAgentCommandMgr()
45}
46
49 ConstElementPtr answer = HookedCommandMgr::processCommand(cmd);
50
51 // Responses from the Kea Control Agent must be always wrapped
52 // in a list because in general they contain responses from
53 // multiple daemons.
54 if (answer->getType() == Element::list) {
55 return (answer);
56 }
57 ElementPtr answer_list = Element::createList();
58 answer_list->add(boost::const_pointer_cast<Element>(answer));
59
60 return (answer_list);
61}
62
64CtrlAgentCommandMgr::handleCommand(const std::string& cmd_name,
65 const isc::data::ConstElementPtr& params,
66 const isc::data::ConstElementPtr& original_cmd) {
67
68 ConstElementPtr services = Element::createList();
69
70 // Retrieve 'service' parameter to determine if we should forward the
71 // command or handle it on our own.
72 if (original_cmd && original_cmd->contains("service")) {
73 services = original_cmd->get("service");
74 // If 'service' value is not a list, this is a fatal error. We don't want
75 // to try processing commands that don't adhere to the required format.
76 if (services->getType() != Element::list) {
77 return (createAnswer(CONTROL_RESULT_ERROR, "service value must be a list"));
78 }
79 }
80
81 // 'service' parameter hasn't been specified which indicates that the command
82 // is intended to be processed by the CA. The following command will try to
83 // process the command with hooks libraries (if available) or by one of the
84 // CA's native handlers.
85 if (services->empty()) {
86
87 // It is frequent user error to not include the 'service' parameter in
88 // the commands that should be forwarded to Kea servers. If the command
89 // lacks this parameter the CA will try to process it and often fail
90 // because it is not supported by the CA. In the future we may want to
91 // make this parameter mandatory. For now, we're going to improve the
92 // situation by clearly explaining to the controlling client that the
93 // command is not supported by the CA, but it is possible that he may
94 // achieve what he wants by providing the 'service' parameter.
95
96 // Our interface is very restrictive so we walk around this by const
97 // casting the returned pointer. It is certainly easier to do than
98 // changing the whole data interface.
99 ElementPtr answer = boost::const_pointer_cast<Element>
100 (HookedCommandMgr::handleCommand(cmd_name, params, original_cmd));
101
102 try {
103 // Check what error code was returned by the handler.
104 int rcode = 0;
105 ConstElementPtr text = parseAnswer(rcode, answer);
106
107 // There is a dedicated error code for unsupported command case.
109
110 // Append the explanatory text to the text reported by the handler.
111 // Smart, eh?
112 std::ostringstream s;
113 s << text->stringValue();
114 s << " You did not include \"service\" parameter in the command,"
115 " which indicates that Kea Control Agent should process this"
116 " command rather than forward it to one or more Kea servers. If you"
117 " aimed to send this command to one of the Kea servers you"
118 " should include the \"service\" parameter in your request, e.g."
119 " \"service\": [ \"dhcp4\" ] to forward the command to the DHCPv4"
120 " server, or \"service\": [ \"dhcp4\", \"dhcp6\", \"d2\" ] to forward it to"
121 " DHCPv4, DHCPv6 and D2 servers etc.";
122
123 answer->set(CONTROL_TEXT, Element::create(s.str()));
124 }
125
126 } catch (...) {
127 // Exceptions are not really possible assuming that the BaseCommandMgr
128 // creates the response correctly.
129 }
130
131 return (answer);
132 }
133
134 ElementPtr answer_list = Element::createList();
135
136 // Before the command is forwarded we check if there are any hooks libraries
137 // which would process the command.
138 if (HookedCommandMgr::delegateCommandToHookLibrary(cmd_name, params, original_cmd,
139 answer_list)) {
140 // The command has been processed by hooks library. Return the result.
141 return (answer_list);
142 }
143
144 // We don't know whether the hooks libraries modified the value of the
145 // answer list, so let's be safe and re-create the answer_list.
146 answer_list = Element::createList();
147
148 // For each value within 'service' we have to try forwarding the command.
149 for (unsigned i = 0; i < services->size(); ++i) {
150 if (original_cmd) {
151 ConstElementPtr answer;
152 try {
155 .arg(cmd_name).arg(services->get(i)->stringValue());
156
157 answer = forwardCommand(services->get(i)->stringValue(),
158 cmd_name, original_cmd);
159
160 } catch (const CommandForwardingError& ex) {
163 .arg(cmd_name).arg(ex.what());
164 answer = createAnswer(CONTROL_RESULT_ERROR, ex.what());
165 }
166
167 answer_list->add(boost::const_pointer_cast<Element>(answer));
168 }
169 }
170
171 return (answer_list);
172}
173
175CtrlAgentCommandMgr::forwardCommand(const std::string& service,
176 const std::string& cmd_name,
177 const isc::data::ConstElementPtr& command) {
178 // Context will hold the server configuration.
180
181 // There is a hierarchy of the objects through which we need to pass to get
182 // the configuration context. We may simplify this at some point but since
183 // we're in the singleton we want to make sure that we're using most current
184 // configuration.
185 boost::shared_ptr<CtrlAgentController> controller =
186 boost::dynamic_pointer_cast<CtrlAgentController>(CtrlAgentController::instance());
187 if (controller) {
188 CtrlAgentProcessPtr process = controller->getCtrlAgentProcess();
189 if (process) {
190 CtrlAgentCfgMgrPtr cfgmgr = process->getCtrlAgentCfgMgr();
191 if (cfgmgr) {
192 ctx = cfgmgr->getCtrlAgentCfgContext();
193 }
194 }
195 }
196
197 // This is highly unlikely but keep the checks just in case someone messes up
198 // in the code.
199 if (!ctx) {
200 isc_throw(CommandForwardingError, "internal server error: unable to retrieve"
201 " Control Agent configuration information");
202 }
203
204 // Now that we know what service it should be forwarded to, we should
205 // find a matching forwarding socket. If this socket is not configured,
206 // we have to communicate it to the client.
207 ConstElementPtr socket_info = ctx->getControlSocketInfo(service);
208 if (!socket_info) {
209 isc_throw(CommandForwardingError, "forwarding socket is not configured"
210 " for the server type " << service);
211 }
212
213 // If the configuration does its job properly the socket-name must be
214 // specified and must be a string value.
215 std::string socket_name = socket_info->get("socket-name")->stringValue();
216
217 // Forward command and receive reply.
218 IOServicePtr io_service(new IOService());;
219 ClientConnection conn(*io_service);
220 boost::system::error_code received_ec;
221 ConstJSONFeedPtr received_feed;
222 conn.start(ClientConnection::SocketPath(socket_name),
223 ClientConnection::ControlCommand(command->toWire()),
224 [&io_service, &received_ec, &received_feed]
225 (const boost::system::error_code& ec, ConstJSONFeedPtr feed) {
226 // Capture error code and parsed data.
227 received_ec = ec;
228 received_feed = feed;
229 // Got the IO service so stop IO service. This causes to
230 // stop IO service when all handlers have been invoked.
231 io_service->stopWork();
233 io_service->run();
234
235 if (received_ec) {
236 isc_throw(CommandForwardingError, "unable to forward command to the "
237 << service << " service: " << received_ec.message()
238 << ". The server is likely to be offline");
239 }
240
241 // This shouldn't happen because the fact that there was no time out indicates
242 // that the whole response has been read and it should be stored within the
243 // feed. But, let's check to prevent assertions.
244 if (!received_feed) {
245 isc_throw(CommandForwardingError, "internal server error: empty response"
246 " received from the unix domain socket");
247 }
248
249 ConstElementPtr answer;
250 try {
251 answer = received_feed->toElement();
252
254 .arg(cmd_name).arg(service);
255
256 } catch (const std::exception& ex) {
257 isc_throw(CommandForwardingError, "internal server error: unable to parse"
258 " server's answer to the forwarded message: " << ex.what());
259 }
260
261 return (answer);
262}
263
264
265} // end of namespace isc::agent
266} // end of namespace isc
virtual const char * what() const
Returns a C-style character string of the cause of the exception.
Exception thrown when an error occurred during control command forwarding.
Command Manager for Control Agent.
virtual isc::data::ConstElementPtr handleCommand(const std::string &cmd_name, const isc::data::ConstElementPtr &params, const isc::data::ConstElementPtr &original_cmd)
Handles the command having a given name and arguments.
static CtrlAgentCommandMgr & instance()
Returns sole instance of the Command Manager.
virtual isc::data::ConstElementPtr processCommand(const isc::data::ConstElementPtr &cmd)
Triggers command processing.
static process::DControllerBasePtr & instance()
Static singleton instance method.
Represents client side connection over the unix domain socket.
Command Manager which can delegate commands to a hook library.
This file contains several functions and constants that are used for handling commands and responses ...
#define isc_throw(type, stream)
A shortcut macro to insert known values into exception arguments.
#define LOG_INFO(LOGGER, MESSAGE)
Macro to conveniently test info output and log it.
Definition: macros.h:20
#define LOG_DEBUG(LOGGER, LEVEL, MESSAGE)
Macro to conveniently test debug output and log it.
Definition: macros.h:14
const isc::log::MessageID CTRL_AGENT_COMMAND_FORWARD_BEGIN
Definition: ca_messages.h:12
boost::shared_ptr< CtrlAgentCfgContext > CtrlAgentCfgContextPtr
Pointer to a configuration context.
Definition: ca_cfg_mgr.h:21
boost::shared_ptr< CtrlAgentProcess > CtrlAgentProcessPtr
Defines a shared pointer to CtrlAgentProcess.
Definition: ca_process.h:150
const isc::log::MessageID CTRL_AGENT_COMMAND_FORWARDED
Definition: ca_messages.h:11
isc::log::Logger agent_logger("ctrl-agent")
Control Agent logger.
Definition: ca_log.h:18
boost::shared_ptr< CtrlAgentCfgMgr > CtrlAgentCfgMgrPtr
Defines a shared pointer to CtrlAgentCfgMgr.
Definition: ca_cfg_mgr.h:311
const isc::log::MessageID CTRL_AGENT_COMMAND_FORWARD_FAILED
Definition: ca_messages.h:13
boost::shared_ptr< const JSONFeed > ConstJSONFeedPtr
Pointer to the const JSONFeed.
Definition: json_feed.h:27
const char * CONTROL_TEXT
String used for storing textual description ("text")
const int CONTROL_RESULT_ERROR
Status code indicating a general failure.
const int CONTROL_RESULT_COMMAND_UNSUPPORTED
Status code indicating that the specified command is not supported.
ConstElementPtr createAnswer(const int status_code, const std::string &text, const ConstElementPtr &arg)
ConstElementPtr parseAnswer(int &rcode, const ConstElementPtr &msg)
constexpr long TIMEOUT_AGENT_FORWARD_COMMAND
Timeout for the Control Agent to forward command to a Kea server, e.g.
Definition: timeouts.h:31
boost::shared_ptr< const Element > ConstElementPtr
Definition: data.h:27
boost::shared_ptr< Element > ElementPtr
Definition: data.h:24
const int DBGLVL_COMMAND
This debug level is reserved for logging the exchange of messages/commands between processes,...
Definition: log_dbglevels.h:54
Defines the logger used by the top-level component of kea-lfc.