Kea  2.3.2-git
isc::process::DCfgMgrBase Class Referenceabstract

Configuration Manager. More...

#include <d_cfg_mgr.h>

+ Inheritance diagram for isc::process::DCfgMgrBase:

Public Member Functions

 DCfgMgrBase (ConfigPtr context)
 Constructor. More...
 
virtual ~DCfgMgrBase ()
 Destructor. More...
 
virtual std::string getConfigSummary (const uint32_t selection)=0
 Returns configuration summary in the textual format. More...
 
ConfigPtrgetContext ()
 Fetches the configuration context. More...
 
isc::data::ConstElementPtr redactConfig (isc::data::ConstElementPtr const &config) const
 Redact the configuration. More...
 
isc::data::ConstElementPtr simpleParseConfig (isc::data::ConstElementPtr config, bool check_only=false, const std::function< void()> &post_config_cb=nullptr)
 Acts as the receiver of new configurations. More...
 

Protected Member Functions

virtual ConfigPtr createNewContext ()=0
 Abstract factory which creates a context instance. More...
 
virtual std::list< std::list< std::string > > jsonPathsToRedact () const
 Return a list of all paths that contain passwords or secrets. More...
 
virtual isc::data::ConstElementPtr parse (isc::data::ConstElementPtr config, bool check_only)
 Parses actual configuration. More...
 
void resetContext ()
 Replaces existing context with a new, empty context. More...
 
virtual void setCfgDefaults (isc::data::ElementPtr mutable_config)
 Adds default values to the given config. More...
 
void setContext (ConfigPtr &context)
 Update the current context. More...
 

Detailed Description

Configuration Manager.

DCfgMgrBase is an abstract class that provides the mechanisms for managing an application's configuration. This includes services for parsing sets of configuration values, storing the parsed information in its converted form, and retrieving the information on demand. It is intended to be the worker class which is handed a set of configuration values to process by upper application management layers.

This class allows two configuration methods:

  1. classic method

The class presents a public method for receiving new configurations, parseConfig. This method coordinates the parsing effort as follows:

make backup copy of configuration context
Split top-level configuration elements into to sets:
1. Set of scalar elements (strings, booleans, ints, etc..)
2. Set of object elements (maps, lists, etc...)
For each entry in the scalar set:
get derivation-specific parser for element
run parser
update context with parsed results
break on error
For each entry in the object set;
get derivation-specific parser for element
run parser
update context with parsed results
break on error
if an error occurred or this is only a check
restore configuration context from backup

The above structuring ensures that global parameters are parsed first making them available during subsequent object element parsing. The order in which the object elements are processed is either:

  1. Natural order presented by the configuration set
  2. Specific order determined by a list of element ids

This allows a derivation to specify the order in which its elements are parsed if there are dependencies between elements.

To parse a given element, its id along with the element itself, is passed into the virtual method, parseElement. Derivations are expected to converts the element into application specific object(s), thereby isolating the CPL from application details.

In the event that an error occurs, parsing is halted and the configuration context is restored from backup.

See isc::d2::D2CfgMgr and isc::d2::D2Process for example use of this approach.

  1. simple configuration method

This approach assumes usage of isc::data::SimpleParser paradigm. It does not use any intermediate storage, does not use parser pointers, does not enforce parsing order.

Here's the expected control flow order:

  1. implementation calls simpleParseConfig from its configure method.
  2. simpleParseConfig makes a configuration context
  3. parse method from the derived class is called
  4. if the configuration was unsuccessful or this is only a check, the old context is reinstantiated. If not, the configuration is kept.

See isc::agent::CtrlAgentCfgMgr and isc::agent::CtrlAgentProcess for example use of this approach.

Definition at line 108 of file d_cfg_mgr.h.

Constructor & Destructor Documentation

◆ DCfgMgrBase()

isc::process::DCfgMgrBase::DCfgMgrBase ( ConfigPtr  context)

Constructor.

Parameters
contextis a pointer to the configuration context the manager will use for storing parsed results.
Exceptions
throwsDCfgMgrBaseError if context is null

Definition at line 38 of file d_cfg_mgr.cc.

◆ ~DCfgMgrBase()

isc::process::DCfgMgrBase::~DCfgMgrBase ( )
virtual

Destructor.

Definition at line 42 of file d_cfg_mgr.cc.

Member Function Documentation

◆ createNewContext()

virtual ConfigPtr isc::process::DCfgMgrBase::createNewContext ( )
protectedpure virtual

Abstract factory which creates a context instance.

This method is used at the beginning of configuration process to create a fresh, empty copy of the derivation-specific context. This new context will be populated during the configuration process and will replace the existing context provided the configuration process completes without error.

Returns
Returns a ConfigPtr to the new context instance.

Implemented in isc::d2::D2CfgMgr, isc::agent::CtrlAgentCfgMgr, and isc::netconf::NetconfCfgMgr.

◆ getConfigSummary()

virtual std::string isc::process::DCfgMgrBase::getConfigSummary ( const uint32_t  selection)
pure virtual

Returns configuration summary in the textual format.

This method returns the brief text describing the current configuration. It may be used for logging purposes, e.g. whn the new configuration is committed to notify a user about the changes in configuration.

Parameters
selectionBitfield which describes the parts of the configuration to be returned.
Returns
Summary of the configuration in the textual format.

Implemented in isc::d2::D2CfgMgr, isc::agent::CtrlAgentCfgMgr, and isc::netconf::NetconfCfgMgr.

◆ getContext()

ConfigPtr& isc::process::DCfgMgrBase::getContext ( )
inline

Fetches the configuration context.

Returns
returns a pointer reference to the configuration context.

Definition at line 151 of file d_cfg_mgr.h.

References isc::process::redactConfig().

+ Here is the call graph for this function:

◆ jsonPathsToRedact()

list< list< string > > isc::process::DCfgMgrBase::jsonPathsToRedact ( ) const
protectedvirtual

Return a list of all paths that contain passwords or secrets.

Used in isc::process::Daemon::redactConfig to only make copies and only redact configuration subtrees that contain passwords or secrets.

This method needs to be overridden in each process that has a distinct configuration structure.

Returns
the list of lists of sequential JSON map keys needed to reach the passwords and secrets.

Reimplemented in isc::agent::CtrlAgentCfgMgr, isc::d2::D2CfgMgr, and isc::netconf::NetconfCfgMgr.

Definition at line 69 of file d_cfg_mgr.cc.

◆ parse()

isc::data::ConstElementPtr isc::process::DCfgMgrBase::parse ( isc::data::ConstElementPtr  config,
bool  check_only 
)
protectedvirtual

Parses actual configuration.

This method is expected to be implemented in derived classes that employ SimpleParser paradigm (i.e. they call simpleParseConfig rather than parseConfig from their configure method).

Implementations that do not employ this method may provide dummy implementation.

Parameters
configthe Element tree structure that describes the configuration.
check_onlyfalse for normal configuration, true when verifying only
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.

Reimplemented in isc::d2::D2CfgMgr, isc::agent::CtrlAgentCfgMgr, and isc::netconf::NetconfCfgMgr.

Definition at line 158 of file d_cfg_mgr.cc.

References isc_throw.

◆ redactConfig()

ConstElementPtr isc::process::DCfgMgrBase::redactConfig ( isc::data::ConstElementPtr const &  config) const

Redact the configuration.

This method replaces passwords and secrets by asterisks. By default it follows all subtrees at the exception of user contexts. Please derive the method to allow a reasonable performance by following only subtrees where the syntax allows the presence of passwords and secrets.

Parameters
configthe Element tree structure that describes the configuration.
Returns
unmodified config or a copy of the config where passwords were replaced by asterisks so can be safely logged to an unprivileged place.

Definition at line 61 of file d_cfg_mgr.cc.

References isc::process::redactConfig().

+ Here is the call graph for this function:

◆ resetContext()

void isc::process::DCfgMgrBase::resetContext ( )
protected

Replaces existing context with a new, empty context.

Definition at line 46 of file d_cfg_mgr.cc.

◆ setCfgDefaults()

void isc::process::DCfgMgrBase::setCfgDefaults ( isc::data::ElementPtr  mutable_config)
protectedvirtual

Adds default values to the given config.

Provides derivations a means to add defaults to a configuration Element map prior to parsing it.

Parameters
mutable_config- configuration to which defaults should be added

Reimplemented in isc::d2::D2CfgMgr.

Definition at line 154 of file d_cfg_mgr.cc.

◆ setContext()

void isc::process::DCfgMgrBase::setContext ( ConfigPtr context)
protected

Update the current context.

Replaces the existing context with the given context.

Parameters
contextPointer to the new context.
Exceptions
DCfgMgrBaseErrorif context is NULL.

Definition at line 52 of file d_cfg_mgr.cc.

References isc_throw.

◆ simpleParseConfig()

isc::data::ConstElementPtr isc::process::DCfgMgrBase::simpleParseConfig ( isc::data::ConstElementPtr  config,
bool  check_only = false,
const std::function< void()> &  post_config_cb = nullptr 
)

Acts as the receiver of new configurations.

This method is similar to what parseConfig did, execept it employs the simple parser paradigm: no intermediate storage, no parser pointers no distinction between params_map and objects_map, parse order (if needed) can be enforced in the actual implementation by calling specific parsers first. See isc::agent::CtrlAgentCfgMgr::parse for example.

If check_only is true, the actual parsing is done to check if the configuration is sane, but is then reverted.

Parameters
configset of configuration elements to be parsed
check_onlytrue if the config is to be checked only, but not applied
post_config_cbCallback to be executed after the usual parsing stage. This can be specified as a C++ lambda which configures other parts of the system based on the parsed configuration information. The callback should throw an exception to signal an error. This method will catch this exception and place an exception string within the result returned.
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.

Definition at line 75 of file d_cfg_mgr.cc.

References isc::config::answerToText(), isc::config::createAnswer(), isc::log::DBGLVL_COMMAND, isc::process::DCTL_CONFIG_CHECK_COMPLETE, isc::process::DCTL_CONFIG_COMPLETE, isc::process::DCTL_CONFIG_START, isc::process::dctl_logger, isc::process::DCTL_PARSER_FAIL, LOG_DEBUG, LOG_ERROR, LOG_INFO, isc::config::parseAnswer(), and isc::process::redactConfig().

+ Here is the call graph for this function:

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