Configuration Manager. More...

#include <d_cfg_mgr.h>

Inheritance diagram for isc::process::DCfgMgrBase:

Public Member Functions
	DCfgMgrBase (ConfigPtr context)
	Constructor.

virtual	~DCfgMgrBase ()
	Destructor.

virtual std::string	getConfigSummary (const uint32_t selection)=0
	Returns configuration summary in the textual format.

ConfigPtr &	getContext ()
	Fetches the configuration context.

isc::data::ConstElementPtr	redactConfig (isc::data::ConstElementPtr const &config) const
	Redact the configuration.

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.

Protected Member Functions
virtual ConfigPtr	createNewContext ()=0
	Abstract factory which creates a context instance.

virtual std::list< std::list< std::string > >	jsonPathsToRedact () const
	Return a list of all paths that contain passwords or secrets.

virtual isc::data::ConstElementPtr	parse (isc::data::ConstElementPtr config, bool check_only)
	Parses actual configuration.

void	resetContext ()
	Replaces existing context with a new, empty context.

virtual void	setCfgDefaults (isc::data::ElementPtr mutable_config)
	Adds default values to the given config.

void	setContext (ConfigPtr &context)
	Update the current context.

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:

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:

Natural order presented by the configuration set
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.

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:

implementation calls simpleParseConfig from its configure method.
simpleParseConfig makes a configuration context
parse method from the derived class is called
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

context is a pointer to the configuration context the manager will use for storing parsed results.

Exceptions

throws DCfgMgrBaseError if context is null

Definition at line 37 of file d_cfg_mgr.cc.

References setContext().

Here is the call graph for this function:

◆ ~DCfgMgrBase()

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

virtual

Destructor.

Definition at line 41 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::agent::CtrlAgentCfgMgr, isc::d2::D2CfgMgr, and isc::netconf::NetconfCfgMgr.

Referenced by resetContext().

◆ 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

selection Bitfield which describes the parts of the configuration to be returned.

Returns: Summary of the configuration in the textual format.

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

Referenced by simpleParseConfig().

◆ 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.

Referenced by isc::agent::CtrlAgentCfgMgr::getCtrlAgentCfgContext(), isc::d2::D2CfgMgr::getD2CfgContext(), and isc::d2::D2CfgMgr::parse().

◆ 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 68 of file d_cfg_mgr.cc.

Referenced by redactConfig().

◆ 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

config	the Element tree structure that describes the configuration.
check_only	false 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::agent::CtrlAgentCfgMgr, isc::d2::D2CfgMgr, and isc::netconf::NetconfCfgMgr.

Definition at line 157 of file d_cfg_mgr.cc.

References isc_throw.

Referenced by simpleParseConfig().

◆ 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

config the 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 60 of file d_cfg_mgr.cc.

References jsonPathsToRedact(), and isc::process::redactConfig().

Referenced by simpleParseConfig().

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 45 of file d_cfg_mgr.cc.

References createNewContext(), and setContext().

Referenced by simpleParseConfig().

Here is the call graph for this function:

◆ 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 153 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

context Pointer to the new context.

Exceptions

DCfgMgrBaseError if context is NULL.

Definition at line 51 of file d_cfg_mgr.cc.

References isc_throw.

Referenced by DCfgMgrBase(), and resetContext().

◆ 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

config	set of configuration elements to be parsed
check_only	true if the config is to be checked only, but not applied
post_config_cb	Callback 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 74 of file d_cfg_mgr.cc.

References isc::config::answerToText(), isc::process::Daemon::configureLogger(), isc::config::CONTROL_RESULT_ERROR, 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, getConfigSummary(), LOG_DEBUG, LOG_ERROR, LOG_INFO, parse(), isc::config::parseAnswer(), redactConfig(), and resetContext().

Here is the call graph for this function:

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

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ DCfgMgrBase()

◆ ~DCfgMgrBase()

Member Function Documentation

◆ createNewContext()

◆ getConfigSummary()

◆ getContext()

◆ jsonPathsToRedact()

◆ parse()

◆ redactConfig()

◆ resetContext()

◆ setCfgDefaults()

◆ setContext()

◆ simpleParseConfig()