Kea  2.3.5-git
isc::process::DControllerBase Class Referenceabstract

Application Controller. More...

#include <d_controller.h>

+ Inheritance diagram for isc::process::DControllerBase:

Public Member Functions

 DControllerBase (const char *app_name, const char *bin_name)
 Constructor. More...
 
virtual ~DControllerBase ()
 Destructor. More...
 
isc::data::ConstElementPtr buildReportHandler (const std::string &command, isc::data::ConstElementPtr args)
 handler for 'build-report' command More...
 
virtual isc::data::ConstElementPtr checkConfig (isc::data::ConstElementPtr new_config)
 Instance method invoked by the configuration event handler and which processes the actual configuration check. More...
 
virtual isc::data::ConstElementPtr configFromFile ()
 Reconfigures the process from a configuration file. More...
 
isc::data::ConstElementPtr configGetHandler (const std::string &command, isc::data::ConstElementPtr args)
 handler for config-get command More...
 
isc::data::ConstElementPtr configReloadHandler (const std::string &command, isc::data::ConstElementPtr args)
 handler for config-reload command More...
 
isc::data::ConstElementPtr configSetHandler (const std::string &command, isc::data::ConstElementPtr args)
 handler for config-set command More...
 
isc::data::ConstElementPtr configTestHandler (const std::string &command, isc::data::ConstElementPtr args)
 handler for config-test command More...
 
isc::data::ConstElementPtr configWriteHandler (const std::string &command, isc::data::ConstElementPtr args)
 handler for config-write command More...
 
std::string getAppName () const
 Fetches the name of the application under control. More...
 
std::string getBinName () const
 Fetches the name of the application executable. More...
 
std::string getVersion (bool extended)
 returns Kea version on stdout and exit. More...
 
virtual int launch (int argc, char *argv[], const bool test_mode)
 Acts as the primary entry point into the controller execution and provides the outermost application control logic: More...
 
isc::data::ConstElementPtr serverTagGetHandler (const std::string &command, isc::data::ConstElementPtr args)
 handler for server-tag-get command More...
 
isc::data::ConstElementPtr shutdownHandler (const std::string &command, isc::data::ConstElementPtr args)
 handler for 'shutdown' command More...
 
isc::data::ConstElementPtr statusGetHandler (const std::string &command, isc::data::ConstElementPtr args)
 handler for status-get command More...
 
virtual isc::data::ConstElementPtr updateConfig (isc::data::ConstElementPtr new_config)
 Instance method invoked by the configuration event handler and which processes the actual configuration update. More...
 
isc::data::ConstElementPtr versionGetHandler (const std::string &command, isc::data::ConstElementPtr args)
 handler for version-get command More...
 
- Public Member Functions inherited from isc::process::Daemon
 Daemon ()
 Default constructor. More...
 
virtual ~Daemon ()
 Destructor. More...
 
void checkConfigFile () const
 Checks the configuration file name. More...
 
virtual void cleanup ()
 Performs final deconfiguration. More...
 
void createPIDFile (int pid=0)
 Creates the PID file. More...
 
std::string getConfigFile () const
 Returns config file name. More...
 
int getExitValue ()
 Fetches the exit value. More...
 
std::string getPIDFileDir () const
 Returns the directory used when forming default PID file name. More...
 
std::string getPIDFileName () const
 Returns the current PID file name. More...
 
virtual std::list< std::list< std::string > > jsonPathsToRedact () const
 Return a list of all paths that contain passwords or secrets. More...
 
isc::data::ConstElementPtr redactConfig (isc::data::ConstElementPtr const &config)
 Redact a configuration. More...
 
void setConfigFile (const std::string &config_file)
 Sets the configuration file name. More...
 
void setExitValue (int value)
 Sets the exit value. More...
 
void setPIDFileDir (const std::string &pid_file_dir)
 Sets the PID file directory. More...
 
void setPIDFileName (const std::string &pid_file_name)
 Sets PID file name. More...
 
virtual void shutdown ()
 Initiates shutdown procedure for the whole server. More...
 
virtual size_t writeConfigFile (const std::string &config_file, isc::data::ConstElementPtr cfg=isc::data::ConstElementPtr()) const
 Writes current configuration to specified file. More...
 

Protected Member Functions

void checkConfigOnly ()
 Check the configuration. More...
 
virtual DProcessBasecreateProcess ()=0
 Abstract method that is responsible for instantiating the application process object. More...
 
virtual bool customOption (int option, char *optarg)
 Virtual method that provides derivations the opportunity to support additional command line options. More...
 
virtual const std::string getCustomOpts () const
 Virtual method which returns a string containing the option letters for any custom command line options supported by the derivation. More...
 
asiolink::IOServicePtrgetIOService ()
 Getter for fetching the controller's IOService. More...
 
DProcessBasePtr getProcess ()
 Fetches the current process. More...
 
virtual const std::string getUsageText () const
 Virtual method which can be used to contribute derivation specific usage text. More...
 
virtual std::string getVersionAddendum ()
 Fetches text containing additional version specifics. More...
 
std::string handleOtherObjects (isc::data::ConstElementPtr args)
 Deals with other (i.e. More...
 
void initProcess ()
 Instantiates the application process and then initializes it. More...
 
void initSignalHandling ()
 Initializes signal handling. More...
 
bool isCheckOnly () const
 Supplies whether or not check only mode is enabled. More...
 
bool isVerbose () const
 Supplies whether or not verbose logging is enabled. More...
 
void parseArgs (int argc, char *argv[])
 Processes the command line arguments. More...
 
virtual isc::data::ConstElementPtr parseFile (const std::string &file_name)
 Parse a given file into Elements. More...
 
virtual isc::data::ConstElementPtr parseText (const std::string &input)
 Parse text into Elements. More...
 
virtual void processSignal (int signum)
 Application-level signal processing method. More...
 
void runProcess ()
 Invokes the application process's event loop,(DBaseProcess::run). More...
 
void setCheckOnly (bool value)
 Method for enabling or disabling check only mode. More...
 
void setVerbose (bool value)
 Method for enabling or disabling verbose logging. More...
 
isc::data::ConstElementPtr shutdownProcess (isc::data::ConstElementPtr args)
 Initiates shutdown procedure. More...
 
void usage (const std::string &text)
 Prints the program usage text to std error. More...
 
- Protected Member Functions inherited from isc::process::Daemon
std::string makePIDFileName () const
 Manufacture the pid file name. More...
 

Static Protected Member Functions

static DControllerBasePtrgetController ()
 Static getter which returns the singleton instance. More...
 
static void setController (const DControllerBasePtr &controller)
 Static setter which sets the singleton instance. More...
 

Friends

class DControllerTest
 

Additional Inherited Members

- Static Public Member Functions inherited from isc::process::Daemon
static void configureLogger (const isc::data::ConstElementPtr &log_config, const isc::process::ConfigPtr &storage)
 Configures logger. More...
 
static std::string getDefaultLoggerName ()
 Returns default logger name. More...
 
static std::string getProcName ()
 returns the process name This value is used as when forming the default PID file name More...
 
static bool getVerbose ()
 Returns if running in verbose mode. More...
 
static std::string getVersion (bool extended)
 returns Kea version on stdout and exits. More...
 
static void loggerInit (const char *log_name, bool verbose)
 Initializes logger. More...
 
static void setDefaultLoggerName (const std::string &logger)
 Sets the default logger name. More...
 
static void setProcName (const std::string &proc_name)
 Sets the process name. More...
 
static void setVerbose (const bool verbose)
 Sets or clears verbose mode. More...
 
- Protected Attributes inherited from isc::process::Daemon
isc::asiolink::IOSignalSetPtr signal_set_
 A pointer to the object installing custom signal handlers. More...
 
boost::posix_time::ptime start_
 Timestamp of the start of the daemon. More...
 

Detailed Description

Application Controller.

DControllerBase is an abstract singleton which provides the framework and services for managing an application process that implements the DProcessBase interface. It runs the process like a stand-alone, command line driven executable, which must be supplied a configuration file at startup. It coordinates command line argument parsing, process instantiation and initialization, and runtime control through external command and configuration event handling. It creates the IOService instance which is used for runtime control events and passes the IOService into the application process at process creation. It provides the callback handlers for command and configuration events which could be triggered by an external source. Such sources are intended to be registered with and monitored by the controller's IOService such that the appropriate handler can be invoked.

DControllerBase provides dynamic configuration file reloading upon receipt of SIGHUP, and graceful shutdown upon receipt of either SIGINT or SIGTERM.

NOTE: Derivations must supply their own static singleton instance method(s) for creating and fetching the instance. The base class declares the instance member in order for it to be available for static callback functions.

Definition at line 104 of file d_controller.h.

Constructor & Destructor Documentation

◆ DControllerBase()

isc::process::DControllerBase::DControllerBase ( const char *  app_name,
const char *  bin_name 
)

Constructor.

Parameters
app_nameis display name of the application under control. This name appears in log statements.
bin_nameis the name of the application executable.

Definition at line 36 of file d_controller.cc.

◆ ~DControllerBase()

isc::process::DControllerBase::~DControllerBase ( )
virtual

Destructor.

Definition at line 809 of file d_controller.cc.

References isc::process::dctl_logger, isc::process::DCTL_UNLOAD_LIBRARIES_ERROR, and LOG_ERROR.

Member Function Documentation

◆ buildReportHandler()

ConstElementPtr isc::process::DControllerBase::buildReportHandler ( const std::string &  command,
isc::data::ConstElementPtr  args 
)

handler for 'build-report' command

This method handles build-report command. It returns the output printed by configure script which contains most compilation parameters.

Parameters
command(ignored)
args(ignored)
Returns
answer with build report

Definition at line 694 of file d_controller.cc.

References isc::config::createAnswer(), and isc::detail::getConfigReport().

Referenced by isc::agent::CtrlAgentController::registerCommands().

+ Here is the call graph for this function:

◆ checkConfig()

ConstElementPtr isc::process::DControllerBase::checkConfig ( isc::data::ConstElementPtr  new_config)
virtual

Instance method invoked by the configuration event handler and which processes the actual configuration check.

Provides behavioral path for both integrated and stand-alone modes. The current implementation will merge the configuration update into the existing configuration and then invoke the application process' configure method with a final rollback.

Parameters
new_configis the new configuration
Returns
returns an Element that contains the results of configuration update composed of an integer status value (0 means successful, non-zero means failure), and a string explanation of the outcome.

Definition at line 443 of file d_controller.cc.

Referenced by checkConfigOnly(), and configTestHandler().

◆ checkConfigOnly()

void isc::process::DControllerBase::checkConfigOnly ( )
protected

Check the configuration.

Called by launch() when check_only_ mode is enabled

Exceptions
VersionMessagewhen successful but a message should be displayed
InvalidUsagewhen an error was detected

Definition at line 174 of file d_controller.cc.

References checkConfig(), getAppName(), isc::process::Daemon::getConfigFile(), handleOtherObjects(), initProcess(), isc_throw, isc::process::Daemon::loggerInit(), isc::config::parseAnswer(), parseFile(), isc::process::Daemon::setDefaultLoggerName(), isc::process::Daemon::setVerbose(), and isc::Exception::what().

Referenced by launch().

+ Here is the call graph for this function:

◆ configFromFile()

ConstElementPtr isc::process::DControllerBase::configFromFile ( )
virtual

Reconfigures the process from a configuration file.

By default the file is assumed to be a JSON text file whose contents include at least:

{ "<module-name>": {<module-config>}
}
where:
module-name : is a label which uniquely identifies the
configuration data for this controller's application
module-config: a set of zero or more JSON elements which comprise
the application's configuration values

To translate the JSON content into Elements, parseFile() is called first. This virtual method provides derivations a means to parse the file content using an alternate parser. If it returns an empty pointer than the JSON parsing providing by Element::fromJSONFile() is called.

Once parsed, the method extracts the set of configuration elements for the module-name that matches the controller's app_name_, looks for the loggers entry and, if present uses it to configure logging. It then passes that set into updateConfig() (or checkConfig()).

The file may contain an arbitrary number of other modules.

Returns
returns an Element that contains the results of configuration update composed of an integer status value (0 means successful, non-zero means failure), and a string explanation of the outcome.

Definition at line 347 of file d_controller.cc.

References isc::process::Daemon::configureLogger(), isc::config::createAnswer(), isc::db::error, getAppName(), isc::process::Daemon::getConfigFile(), handleOtherObjects(), isc_throw, parseFile(), and updateConfig().

Referenced by configReloadHandler(), launch(), and processSignal().

+ Here is the call graph for this function:

◆ configGetHandler()

ConstElementPtr isc::process::DControllerBase::configGetHandler ( const std::string &  command,
isc::data::ConstElementPtr  args 
)

handler for config-get command

This method handles the config-get command, which retrieves the current configuration and returns it in response.

Parameters
command(ignored)
args(ignored)
Returns
current configuration wrapped in a response

Definition at line 448 of file d_controller.cc.

References isc::config::createAnswer().

Referenced by isc::agent::CtrlAgentController::registerCommands().

+ Here is the call graph for this function:

◆ configReloadHandler()

ConstElementPtr isc::process::DControllerBase::configReloadHandler ( const std::string &  command,
isc::data::ConstElementPtr  args 
)

handler for config-reload command

This method handles the config-reload command, which reloads the configuration file.

Parameters
command(ignored)
args(ignored)
Returns
status of the command

Definition at line 581 of file d_controller.cc.

References configFromFile().

Referenced by isc::agent::CtrlAgentController::registerCommands().

+ Here is the call graph for this function:

◆ configSetHandler()

ConstElementPtr isc::process::DControllerBase::configSetHandler ( const std::string &  command,
isc::data::ConstElementPtr  args 
)

handler for config-set command

This method handles the config-set command, which loads configuration specified in args parameter.

Parameters
command(ignored)
argsconfiguration to be checked.
Returns
status of the command

Definition at line 587 of file d_controller.cc.

References isc::process::Daemon::configureLogger(), isc::config::createAnswer(), isc::db::error, getAppName(), handleOtherObjects(), isc::config::parseAnswer(), and updateConfig().

Referenced by isc::agent::CtrlAgentController::registerCommands().

+ Here is the call graph for this function:

◆ configTestHandler()

ConstElementPtr isc::process::DControllerBase::configTestHandler ( const std::string &  command,
isc::data::ConstElementPtr  args 
)

handler for config-test command

This method handles the config-test command, which checks configuration specified in args parameter.

Parameters
command(ignored)
argsconfiguration to be checked.
Returns
status of the command

Definition at line 535 of file d_controller.cc.

References checkConfig(), isc::config::createAnswer(), getAppName(), and handleOtherObjects().

Referenced by isc::agent::CtrlAgentController::registerCommands().

+ Here is the call graph for this function:

◆ configWriteHandler()

ConstElementPtr isc::process::DControllerBase::configWriteHandler ( const std::string &  command,
isc::data::ConstElementPtr  args 
)

handler for config-write command

This handle processes write-config command, which writes the current configuration to disk. This command takes one optional parameter called filename. If specified, the current configuration will be written to that file. If not specified, the file used during Kea start-up will be used. To avoid any exploits, the path is always relative and .. is not allowed in the filename. This is a security measure against exploiting file writes remotely.

Parameters
command(ignored)
argsmay contain optional string argument filename
Returns
status of the configuration file write

Definition at line 456 of file d_controller.cc.

References isc::config::CONTROL_RESULT_SUCCESS, isc::config::createAnswer(), isc::process::Daemon::getConfigFile(), isc::Exception::what(), and isc::process::Daemon::writeConfigFile().

Referenced by isc::agent::CtrlAgentController::registerCommands().

+ Here is the call graph for this function:

◆ createProcess()

virtual DProcessBase* isc::process::DControllerBase::createProcess ( )
protectedpure virtual

Abstract method that is responsible for instantiating the application process object.

It is invoked by the controller after command line argument parsing as part of the process initialization (see initProcess method).

Returns
returns a pointer to the new process object (DProcessBase*) or NULL if the create fails. Note this value is subsequently wrapped in a smart pointer.

Referenced by initProcess().

◆ customOption()

bool isc::process::DControllerBase::customOption ( int  option,
char *  optarg 
)
protectedvirtual

Virtual method that provides derivations the opportunity to support additional command line options.

It is invoked during command line argument parsing (see parseArgs method) if the option is not recognized as a stock DControllerBase option.

Parameters
optionis the option "character" from the command line, without any prefixing hyphen(s)
optargis the argument value (if one) associated with the option
Returns
must return true if the option was valid, false if it is invalid. (Note the default implementation always returns false.)

Definition at line 318 of file d_controller.cc.

Referenced by parseArgs().

◆ getAppName()

std::string isc::process::DControllerBase::getAppName ( ) const
inline

Fetches the name of the application under control.

Returns
returns the controller service name string

Definition at line 222 of file d_controller.h.

Referenced by checkConfigOnly(), configFromFile(), configSetHandler(), configTestHandler(), and handleOtherObjects().

◆ getBinName()

std::string isc::process::DControllerBase::getBinName ( ) const
inline

Fetches the name of the application executable.

Returns
returns the controller logger name string

Definition at line 229 of file d_controller.h.

◆ getController()

static DControllerBasePtr& isc::process::DControllerBase::getController ( )
inlinestaticprotected

Static getter which returns the singleton instance.

Returns
returns a pointer reference to the private singleton instance member.

Definition at line 466 of file d_controller.h.

◆ getCustomOpts()

virtual const std::string isc::process::DControllerBase::getCustomOpts ( ) const
inlineprotectedvirtual

Virtual method which returns a string containing the option letters for any custom command line options supported by the derivation.

These are added to the stock options of "c", "d", ..., during command line interpretation.

Returns
returns a string containing the custom option letters.

Definition at line 397 of file d_controller.h.

Referenced by parseArgs().

◆ getIOService()

asiolink::IOServicePtr& isc::process::DControllerBase::getIOService ( )
inlineprotected

Getter for fetching the controller's IOService.

Returns
returns a pointer reference to the IOService.

Definition at line 458 of file d_controller.h.

◆ getProcess()

DProcessBasePtr isc::process::DControllerBase::getProcess ( )
inlineprotected

Fetches the current process.

Returns
a pointer to the current process instance.

Definition at line 584 of file d_controller.h.

References usage().

+ Here is the call graph for this function:

◆ getUsageText()

virtual const std::string isc::process::DControllerBase::getUsageText ( ) const
inlineprotectedvirtual

Virtual method which can be used to contribute derivation specific usage text.

It is invoked by the usage() method under invalid usage conditions.

Returns
returns the desired text.

Definition at line 387 of file d_controller.h.

Referenced by usage().

◆ getVersion()

std::string isc::process::DControllerBase::getVersion ( bool  extended)

returns Kea version on stdout and exit.

redeclaration/redefinition. isc::process::Daemon::getVersion()

Definition at line 829 of file d_controller.cc.

References isc::log::Logger::getVersion(), and getVersionAddendum().

Referenced by parseArgs(), and versionGetHandler().

+ Here is the call graph for this function:

◆ getVersionAddendum()

virtual std::string isc::process::DControllerBase::getVersionAddendum ( )
inlineprotectedvirtual

Fetches text containing additional version specifics.

This method is provided so derivations can append any additional desired information such as library dependencies to the extended version text returned when DControllerBase::getVersion(true) is invoked.

Returns
a string containing additional version info

Reimplemented in isc::d2::D2Controller.

Definition at line 601 of file d_controller.h.

Referenced by getVersion().

◆ handleOtherObjects()

std::string isc::process::DControllerBase::handleOtherObjects ( isc::data::ConstElementPtr  args)
protected

Deals with other (i.e.

not application name) global objects.

Code shared between configuration handlers:

  • check obsolete or unknown (aka unsupported) objects.
Parameters
argsCommand arguments.
Returns
Error message or empty string.

Definition at line 513 of file d_controller.cc.

References isc::process::DCTL_CONFIG_DEPRECATED, isc::process::dctl_logger, getAppName(), and LOG_ERROR.

Referenced by checkConfigOnly(), configFromFile(), configSetHandler(), and configTestHandler().

+ Here is the call graph for this function:

◆ initProcess()

void isc::process::DControllerBase::initProcess ( )
protected

Instantiates the application process and then initializes it.

This is the second step taken during launch, following successful command line parsing. It is used to invoke the derivation-specific implementation of createProcess, following by an invoking of the newly instantiated process's init method.

Exceptions
throwsDControllerBaseError or indirectly DProcessBaseError if there is a failure creating or initializing the application process.

Definition at line 324 of file d_controller.cc.

References createProcess(), isc::log::DBGLVL_START_SHUT, isc::process::DCTL_INIT_PROCESS, isc::process::dctl_logger, isc_throw, LOG_DEBUG, and isc::Exception::what().

Referenced by checkConfigOnly(), and launch().

+ Here is the call graph for this function:

◆ initSignalHandling()

void isc::process::DControllerBase::initSignalHandling ( )
protected

Initializes signal handling.

This method configures the controller to catch and handle signals. It instantiates a IOSignalSet which listens for SIGHUP, SIGINT, and SIGTERM.

Todo:
block everything we don't handle

Definition at line 740 of file d_controller.cc.

References processSignal().

Referenced by launch().

+ Here is the call graph for this function:

◆ isCheckOnly()

bool isc::process::DControllerBase::isCheckOnly ( ) const
inlineprotected

Supplies whether or not check only mode is enabled.

Returns
returns true if check only is enabled.

Definition at line 442 of file d_controller.h.

Referenced by launch().

◆ isVerbose()

bool isc::process::DControllerBase::isVerbose ( ) const
inlineprotected

Supplies whether or not verbose logging is enabled.

Returns
returns true if verbose logging is enabled.

Definition at line 428 of file d_controller.h.

◆ launch()

int isc::process::DControllerBase::launch ( int  argc,
char *  argv[],
const bool  test_mode 
)
virtual

Acts as the primary entry point into the controller execution and provides the outermost application control logic:

  1. parse command line arguments
  2. instantiate and initialize the application process
  3. load the configuration file
  4. record the start timestamp
  5. initialize signal handling
  6. start and wait on the application process event loop
  7. exit to the caller

It is intended to be called from main() and be given the command line arguments.

This function can be run in "test mode". It prevents initialization of module logger. This is used in unit tests which initialize logger in their main function. Such a logger uses environmental variables to control severity, verbosity etc.

Parameters
argcis the number of command line arguments supplied
argvis the array of string (char *) command line arguments
test_modeis a bool value which indicates if DControllerBase::launch should be run in the test mode (if true). This parameter doesn't have default value to force test implementers to enable test mode explicitly.
Exceptions
throwsone of the following exceptions: InvalidUsage - Indicates invalid command line. ProcessInitError - Failed to create and initialize application process object. ProcessRunError - A fatal error occurred while in the application process event loop.
Returns
The value from Daemon::getExitValue().

Definition at line 62 of file d_controller.cc.

References isc::process::Daemon::checkConfigFile(), checkConfigOnly(), configFromFile(), isc::process::Daemon::createPIDFile(), isc::log::DBGLVL_START_SHUT, isc::process::DCTL_ALREADY_RUNNING, isc::process::DCTL_CONFIG_FILE_LOAD_FAIL, isc::process::DCTL_DEVELOPMENT_VERSION, isc::process::DCTL_INIT_PROCESS_FAIL, isc::process::dctl_logger, isc::process::DCTL_PID_FILE_ERROR, isc::process::DCTL_PROCESS_FAILED, isc::process::DCTL_SHUTDOWN, isc::process::DCTL_STANDALONE, isc::process::DCTL_STARTING, isc::process::Daemon::getExitValue(), initProcess(), initSignalHandling(), isc_throw, isCheckOnly(), LOG_DEBUG, LOG_FATAL, LOG_INFO, LOG_WARN, isc::process::Daemon::loggerInit(), isc::config::parseAnswer(), parseArgs(), runProcess(), isc::process::Daemon::setDefaultLoggerName(), isc::process::Daemon::setProcName(), isc::process::Daemon::setVerbose(), isc::process::Daemon::start_, usage(), and isc::Exception::what().

+ Here is the call graph for this function:

◆ parseArgs()

void isc::process::DControllerBase::parseArgs ( int  argc,
char *  argv[] 
)
protected

Processes the command line arguments.

It is the first step taken after the controller has been launched. It combines the stock list of options with those returned by getCustomOpts(), and uses cstdlib's getopt to loop through the command line. It handles stock options directly, and passes any custom options into the customOption method. Currently there are only some stock options -c/t for specifying the configuration file, -d for verbose logging, and -v/V/W for version reports.

Parameters
argcis the number of command line arguments supplied
argvis the array of string (char *) command line arguments
Exceptions
InvalidUsagewhen there are usage errors.
VersionMessageif the -v, -V or -W arguments is given.

Definition at line 238 of file d_controller.cc.

References customOption(), isc::detail::getConfigReport(), getCustomOpts(), getVersion(), isc_throw, and isc::process::Daemon::setConfigFile().

Referenced by launch().

+ Here is the call graph for this function:

◆ parseFile()

ConstElementPtr isc::process::DControllerBase::parseFile ( const std::string &  file_name)
protectedvirtual

Parse a given file into Elements.

This method provides a means for deriving classes to use alternate parsing mechanisms to parse configuration files into the corresponding isc::data::Elements. The elements produced must be equivalent to those which would be produced by the original JSON parsing. Implementations should throw when encountering errors.

The default implementation returns an empty pointer, signifying to callers that they should submit the file to the original parser.

Parameters
file_namepathname of the file to parse
Returns
pointer to the elements created

Reimplemented in isc::agent::CtrlAgentController, and isc::netconf::NetconfController.

Definition at line 56 of file d_controller.cc.

Referenced by checkConfigOnly(), and configFromFile().

◆ parseText()

virtual isc::data::ConstElementPtr isc::process::DControllerBase::parseText ( const std::string &  input)
inlineprotectedvirtual

Parse text into Elements.

This method provides a means for deriving classes to use alternate parsing mechanisms to parse configuration text into the corresponding isc::data::Elements. The elements produced must be equivalent to those which would be produced by the original JSON parsing. Implementations should throw when encountering errors.

The default implementation returns an empty pointer, signifying to callers that they should submit the text to the original parser.

Parameters
inputtext to parse
Returns
pointer to the elements created

Definition at line 527 of file d_controller.h.

◆ processSignal()

void isc::process::DControllerBase::processSignal ( int  signum)
protectedvirtual

Application-level signal processing method.

This method is the last step in processing a OS signal occurrence. It currently supports the following signals as follows:

  1. SIGHUP - instigates reloading the configuration file
  2. SIGINT - instigates a graceful shutdown
  3. SIGTERM - instigates a graceful shutdown If it receives any other signal, it will issue a debug statement and discard it. Derivations wishing to support additional signals could override this method with one that: processes the signal if it is one of additional signals, otherwise invoke this method (DControllerBase::processSignal()) with the signal value.
    Todo:
    Provide a convenient way for derivations to register additional signals.

Reimplemented in isc::netconf::NetconfController.

Definition at line 755 of file d_controller.cc.

References configFromFile(), isc::log::DBGLVL_START_SHUT, isc::process::DCTL_CFG_FILE_RELOAD_ERROR, isc::process::DCTL_CFG_FILE_RELOAD_SIGNAL_RECVD, isc::process::dctl_logger, isc::process::DCTL_SHUTDOWN_SIGNAL_RECVD, isc::process::DCTL_UNSUPPORTED_SIGNAL, isc::process::Daemon::getConfigFile(), LOG_DEBUG, LOG_ERROR, LOG_INFO, LOG_WARN, isc::config::parseAnswer(), and shutdownHandler().

Referenced by initSignalHandling(), and isc::netconf::NetconfController::processSignal().

+ Here is the call graph for this function:

◆ runProcess()

void isc::process::DControllerBase::runProcess ( )
protected

Invokes the application process's event loop,(DBaseProcess::run).

It is called during launch only after successfully completing the requested setup: command line parsing, application initialization, and session establishment (if not stand-alone). The process event loop is expected to only return upon application shutdown either in response to the shutdown command or due to an unrecoverable error.

Definition at line 422 of file d_controller.cc.

References isc::log::DBGLVL_START_SHUT, isc::process::dctl_logger, isc::process::DCTL_RUN_PROCESS, isc_throw, and LOG_DEBUG.

Referenced by launch().

◆ serverTagGetHandler()

ConstElementPtr isc::process::DControllerBase::serverTagGetHandler ( const std::string &  command,
isc::data::ConstElementPtr  args 
)

handler for server-tag-get command

This method handles the server-tag-get command, which retrieves the current server tag and returns it in response.

Parameters
command(ignored)
args(ignored)
Returns
current configuration wrapped in a response

Definition at line 653 of file d_controller.cc.

References isc::config::createAnswer().

+ Here is the call graph for this function:

◆ setCheckOnly()

void isc::process::DControllerBase::setCheckOnly ( bool  value)
inlineprotected

Method for enabling or disabling check only mode.

Todo:
this method and setVerbose are currently not used.
Parameters
valueis the new value to assign the flag.

Definition at line 451 of file d_controller.h.

◆ setController()

void isc::process::DControllerBase::setController ( const DControllerBasePtr controller)
staticprotected

Static setter which sets the singleton instance.

Parameters
controlleris a pointer to the singleton instance.
Exceptions
throwsDControllerBase error if an attempt is made to set the instance a second time.

Definition at line 44 of file d_controller.cc.

References isc_throw.

◆ setVerbose()

void isc::process::DControllerBase::setVerbose ( bool  value)
inlineprotected

Method for enabling or disabling verbose logging.

Parameters
valueis the new value to assign the flag.

Definition at line 435 of file d_controller.h.

◆ shutdownHandler()

ConstElementPtr isc::process::DControllerBase::shutdownHandler ( const std::string &  command,
isc::data::ConstElementPtr  args 
)

handler for 'shutdown' command

This method handles shutdown command. It initiates the shutdown procedure using CPL methods.

Parameters
command(ignored)
args(ignored)
Returns
answer confirming that the shutdown procedure is started

Definition at line 699 of file d_controller.cc.

References isc::config::CONTROL_RESULT_ERROR, isc::config::createAnswer(), isc::process::Daemon::setExitValue(), and shutdownProcess().

Referenced by processSignal(), and isc::agent::CtrlAgentController::registerCommands().

+ Here is the call graph for this function:

◆ shutdownProcess()

ConstElementPtr isc::process::DControllerBase::shutdownProcess ( isc::data::ConstElementPtr  args)
protected

Initiates shutdown procedure.

This method is invoked by executeCommand in response to the shutdown command. It will invoke the application process's shutdown method which causes the process to to begin its shutdown process.

Note, it is assumed that the process of shutting down is neither instantaneous nor synchronous. This method does not "block" waiting until the process has halted. Rather it is used to convey the need to shutdown. A successful return indicates that the shutdown has successfully commenced, but does not indicate that the process has actually exited.

Returns
returns an Element that contains the results of shutdown command composed of an integer status value (0 means successful, non-zero means failure), and a string explanation of the outcome.
Parameters
argsis a set of derivation-specific arguments (if any) for the shutdown command.

Definition at line 728 of file d_controller.cc.

References isc::config::createAnswer(), isc::process::dctl_logger, isc::process::DCTL_NOT_RUNNING, and LOG_WARN.

Referenced by shutdownHandler().

+ Here is the call graph for this function:

◆ statusGetHandler()

ConstElementPtr isc::process::DControllerBase::statusGetHandler ( const std::string &  command,
isc::data::ConstElementPtr  args 
)

handler for status-get command

This method handles the status-get command, which retrieves the server process information i.e. the pid and returns it in response.

Parameters
command(ignored)
args(ignored)
Returns
process information wrapped in a response

Definition at line 662 of file d_controller.cc.

References isc::config::createAnswer(), and isc::process::Daemon::start_.

Referenced by isc::agent::CtrlAgentController::registerCommands().

+ Here is the call graph for this function:

◆ updateConfig()

ConstElementPtr isc::process::DControllerBase::updateConfig ( isc::data::ConstElementPtr  new_config)
virtual

Instance method invoked by the configuration event handler and which processes the actual configuration update.

Provides behavioral path for both integrated and stand-alone modes. The current implementation will merge the configuration update into the existing configuration and then invoke the application process' configure method.

Parameters
new_configis the new configuration
Returns
returns an Element that contains the results of configuration update composed of an integer status value (0 means successful, non-zero means failure), and a string explanation of the outcome.

Definition at line 437 of file d_controller.cc.

Referenced by configFromFile(), and configSetHandler().

◆ usage()

void isc::process::DControllerBase::usage ( const std::string &  text)
protected

Prints the program usage text to std error.

Parameters
textis a string message which will preceded the usage text. This is intended to be used for specific usage violation messages.

Definition at line 788 of file d_controller.cc.

References getUsageText().

Referenced by launch().

+ Here is the call graph for this function:

◆ versionGetHandler()

ConstElementPtr isc::process::DControllerBase::versionGetHandler ( const std::string &  command,
isc::data::ConstElementPtr  args 
)

handler for version-get command

This method handles the version-get command. It returns the basic and extended version.

Parameters
command(ignored)
args(ignored)
Returns
answer with version details.

Definition at line 682 of file d_controller.cc.

References isc::config::createAnswer(), and getVersion().

Referenced by isc::agent::CtrlAgentController::registerCommands().

+ Here is the call graph for this function:

Friends And Related Function Documentation

◆ DControllerTest

friend class DControllerTest
friend

Definition at line 647 of file d_controller.h.


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