Kea  2.3.5-git
isc::agent::CtrlAgentProcess Class Reference

Kea Control Agent Application Process. More...

#include <ca_process.h>

+ Inheritance diagram for isc::agent::CtrlAgentProcess:

Public Member Functions

 CtrlAgentProcess (const char *name, const asiolink::IOServicePtr &io_service)
 Constructor. More...
 
virtual ~CtrlAgentProcess ()
 Destructor. More...
 
virtual isc::data::ConstElementPtr configure (isc::data::ConstElementPtr config_set, bool check_only=false)
 Processes the given configuration. More...
 
CtrlAgentCfgMgrPtr getCtrlAgentCfgMgr ()
 Returns a pointer to the configuration manager. More...
 
http::ConstHttpListenerPtr getHttpListener () const
 Returns a const pointer to the HTTP listener used by the process. More...
 
virtual void init ()
 Initialize the Control Agent process. More...
 
bool isListening () const
 Checks if the process is listening to the HTTP requests. More...
 
virtual void run ()
 Implements the process's event loop. More...
 
virtual isc::data::ConstElementPtr shutdown (isc::data::ConstElementPtr args)
 Initiates the process's shutdown process. More...
 
- Public Member Functions inherited from isc::process::DProcessBase
 DProcessBase (const char *app_name, asiolink::IOServicePtr io_service, DCfgMgrBasePtr cfg_mgr)
 Constructor. More...
 
virtual ~DProcessBase ()
 Destructor. More...
 
const std::string getAppName () const
 Fetches the application name. More...
 
DCfgMgrBasePtrgetCfgMgr ()
 Fetches the process's configuration manager. More...
 
asiolink::IOServicePtrgetIoService ()
 Fetches the controller's IOService. More...
 
void setShutdownFlag (bool value)
 Sets the process shut down flag to the given value. More...
 
bool shouldShutdown () const
 Checks if the process has been instructed to shut down. More...
 
void stopIOService ()
 Convenience method for stopping IOservice processing. More...
 

Detailed Description

Kea Control Agent Application Process.

CtrlAgentProcess provides top level application logic for the Control Agent, a process managing Kea servers.

The Control Agent receives JSON control commands over HTTP and forwards the JSON commands to the respective Kea servers. The JSON command includes a name of the server to which the command pertains. After receiving a response from the Kea server it is sent back over HTTP to the control API client.

Some commands are handled by the Control Agent process itself, rather than forwarded to the Kea servers. An example of such command is the one that instructs the agent to start a specific service.

Definition at line 32 of file ca_process.h.

Constructor & Destructor Documentation

◆ CtrlAgentProcess()

isc::agent::CtrlAgentProcess::CtrlAgentProcess ( const char *  name,
const asiolink::IOServicePtr io_service 
)

Constructor.

Parameters
namename is a text label for the process. Generally used in log statements, but otherwise arbitrary.
io_serviceis the io_service used by the caller for asynchronous event handling.

Definition at line 29 of file ca_process.cc.

◆ ~CtrlAgentProcess()

isc::agent::CtrlAgentProcess::~CtrlAgentProcess ( )
virtual

Destructor.

Definition at line 35 of file ca_process.cc.

Member Function Documentation

◆ configure()

isc::data::ConstElementPtr isc::agent::CtrlAgentProcess::configure ( isc::data::ConstElementPtr  config_set,
bool  check_only = false 
)
virtual

Processes the given configuration.

This method may be called multiple times during the process lifetime. Certainly once during process startup, and possibly later if the user alters configuration. This method must not throw, it should catch any processing errors and return a success or failure answer as described below.

A usual problem related to the system reconfiguration is how to preserve configuration integrity in case of errors. In this case, when the HTTP listener's configuration is modified there is a need to close all existing connections and gracefully shutdown the listener's instance. This, however, makes it possible that the control agent looses connectivity if opening a new listener is unsuccessful. In fact, this is quite possible scenario when the user is setting up the listener to use a restricted port range or non-existing IP address. In this case, the configuration parser will not signal the problem because IP address and/or port are syntactically correct.

This method deals with this problem by opening a new listener aside of the currently running listener (if the new listener settings are different than current settings). Both instances are held until the CtrlAgentProcess::garbageCollectListeners is invoked, which removes any listeners which are no longer used.

Parameters
config_seta new configuration (JSON) for the process
check_onlytrue if configuration is to be verified only, not applied
Returns
an Element that contains the results of configuration composed of an integer status value (0 means successful, non-zero means failure), and a string explanation of the outcome.
Todo:
: If the parameter is a hostname, we need to resolve it.

Implements isc::process::DProcessBase.

Definition at line 105 of file ca_process.cc.

References isc::agent::agent_logger, isc::agent::CTRL_AGENT_HTTP_SERVICE_STARTED, isc::agent::CTRL_AGENT_HTTPS_SERVICE_STARTED, isc::process::DProcessBase::getCfgMgr(), isc::process::DProcessBase::getIoService(), isc_throw, LOG_INFO, isc::config::parseAnswer(), isc::asiolink::SERVER, isc::config::TIMEOUT_AGENT_IDLE_CONNECTION_TIMEOUT, isc::config::TIMEOUT_AGENT_RECEIVE_COMMAND, isc::asiolink::IOAddress::toText(), and isc::Exception::what().

+ Here is the call graph for this function:

◆ getCtrlAgentCfgMgr()

CtrlAgentCfgMgrPtr isc::agent::CtrlAgentProcess::getCtrlAgentCfgMgr ( )

Returns a pointer to the configuration manager.

Definition at line 219 of file ca_process.cc.

References isc::process::DProcessBase::getCfgMgr().

+ Here is the call graph for this function:

◆ getHttpListener()

ConstHttpListenerPtr isc::agent::CtrlAgentProcess::getHttpListener ( ) const

Returns a const pointer to the HTTP listener used by the process.

Returns
Const pointer to the currently used listener or null pointer if we're not listening. In fact, the latter should never be the case given that we provide default listener configuration.

Definition at line 224 of file ca_process.cc.

Referenced by isListening().

◆ init()

void isc::agent::CtrlAgentProcess::init ( )
virtual

Initialize the Control Agent process.

This is invoked by the controller after command line arguments but prior to configuration reception. The base class provides this method as a place to perform any derivation-specific initialization steps that are inappropriate for the constructor but necessary prior to launch.

Implements isc::process::DProcessBase.

Definition at line 39 of file ca_process.cc.

◆ isListening()

bool isc::agent::CtrlAgentProcess::isListening ( ) const

Checks if the process is listening to the HTTP requests.

Returns
true if the process is listening.

Definition at line 231 of file ca_process.cc.

References getHttpListener().

+ Here is the call graph for this function:

◆ run()

◆ shutdown()

isc::data::ConstElementPtr isc::agent::CtrlAgentProcess::shutdown ( isc::data::ConstElementPtr  args)
virtual

Initiates the process's shutdown process.

This is last step in the shutdown event callback chain, that is intended to notify the process it is to begin its shutdown process.

Parameters
argsan Element set of shutdown arguments (if any) that are supported by the process derivation.
Returns
an Element that contains the results of argument processing, consisting of an integer status value (0 means successful, non-zero means failure), and a string explanation of the outcome.
Exceptions
DProcessBaseErrorif an operational error is encountered.

Implements isc::process::DProcessBase.

Definition at line 99 of file ca_process.cc.

References isc::config::createAnswer(), and isc::process::DProcessBase::setShutdownFlag().

+ Here is the call graph for this function:

The documentation for this class was generated from the following files: