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.

virtual	~CtrlAgentProcess ()
	Destructor.

virtual isc::data::ConstElementPtr	configure (isc::data::ConstElementPtr config_set, bool check_only=false)
	Processes the given configuration.

CtrlAgentCfgMgrPtr	getCtrlAgentCfgMgr ()
	Returns a pointer to the configuration manager.

http::ConstHttpListenerPtr	getHttpListener () const
	Returns a const pointer to the HTTP listener used by the process.

virtual void	init ()
	Initialize the Control Agent process.

bool	isListening () const
	Checks if the process is listening to the HTTP requests.

virtual void	run ()
	Implements the process's event loop.

virtual isc::data::ConstElementPtr	shutdown (isc::data::ConstElementPtr args)
	Initiates the process's shutdown process.

Public Member Functions inherited from isc::process::DProcessBase
	DProcessBase (const char *app_name, asiolink::IOServicePtr io_service, DCfgMgrBasePtr cfg_mgr)
	Constructor.

virtual	~DProcessBase ()
	Destructor.

virtual isc::data::ConstElementPtr	configure (isc::data::ConstElementPtr config_set, bool check_only=false)=0
	Processes the given configuration.

const std::string	getAppName () const
	Fetches the application name.

DCfgMgrBasePtr &	getCfgMgr ()
	Fetches the process's configuration manager.

asiolink::IOServicePtr &	getIOService ()
	Fetches the controller's IOService.

virtual void	init ()=0
	May be used after instantiation to perform initialization unique to application.

virtual void	run ()=0
	Implements the process's event loop.

void	setShutdownFlag (bool value)
	Sets the process shut down flag to the given value.

bool	shouldShutdown () const
	Checks if the process has been instructed to shut down.

virtual isc::data::ConstElementPtr	shutdown (isc::data::ConstElementPtr args)=0
	Initiates the process's shutdown process.

void	stopIOService ()
	Convenience method for stopping IOservice processing.

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

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

Definition at line 30 of file ca_process.cc.

◆ ~CtrlAgentProcess()

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

virtual

Destructor.

Definition at line 36 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_set	a new configuration (JSON) for the process
check_only	true 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.

Let postponed hook initializations run.

Implements isc::process::DProcessBase.

Definition at line 110 of file ca_process.cc.

References isc::agent::agent_logger, isc::config::CONTROL_RESULT_ERROR, isc::config::createAnswer(), isc::agent::CTRL_AGENT_HTTP_SERVICE_STARTED, isc::agent::CTRL_AGENT_HTTPS_SERVICE_STARTED, isc::process::DProcessBase::getCfgMgr(), isc::process::DProcessBase::getIOService(), isc::asiolink::IOServiceMgr::instance(), isc_throw, LOG_INFO, isc::config::parseAnswer(), isc::asiolink::IOServiceMgr::pollIOServices(), 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 236 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 241 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 41 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 248 of file ca_process.cc.

References getHttpListener().

Here is the call graph for this function:

◆ run()

void isc::agent::CtrlAgentProcess::run ( )

virtual

Implements the process's event loop.

Exceptions

DProcessBaseError if an operational error is encountered.

Implements isc::process::DProcessBase.

Definition at line 45 of file ca_process.cc.

References isc::agent::agent_logger, isc::agent::CTRL_AGENT_FAILED, isc::agent::CTRL_AGENT_RUN_EXIT, isc::agent::CTRL_AGENT_STARTED, isc::log::DBGLVL_START_SHUT, isc::agent::CtrlAgentController::instance(), isc_throw, LOG_DEBUG, LOG_FATAL, LOG_INFO, isc::process::DProcessBase::shouldShutdown(), isc::process::DProcessBase::stopIOService(), and isc::Exception::what().

Here is the call graph for this function:

◆ 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

args	an 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

DProcessBaseError if an operational error is encountered.

Implements isc::process::DProcessBase.

Definition at line 103 of file ca_process.cc.

References isc::config::CONTROL_RESULT_SUCCESS, 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:

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CtrlAgentProcess()

◆ ~CtrlAgentProcess()

Member Function Documentation

◆ configure()

◆ getCtrlAgentCfgMgr()

◆ getHttpListener()

◆ init()

◆ isListening()

◆ run()

◆ shutdown()