Base class for implementing server specific mechanisms to control the use of the Configuration Backends. More...

#include <cb_ctl_base.h>

Inheritance diagram for isc::process::CBControlBase< ConfigBackendMgrType >:

Public Types
enum class	FetchMode { FETCH_ALL , FETCH_UPDATE }
	Fetch mode used in invocations to `databaseConfigFetch`. More...

Public Member Functions
	CBControlBase ()
	Constructor.

virtual	~CBControlBase ()
	Virtual destructor.

bool	databaseConfigConnect (const ConfigPtr &srv_cfg)
	(Re)connects to the specified configuration backends.

void	databaseConfigDisconnect ()
	Disconnects from the configuration backends.

virtual void	databaseConfigFetch (const ConfigPtr &srv_cfg, const FetchMode &fetch_mode=FetchMode::FETCH_ALL)
	Fetches the entire or partial configuration from the database.

void	reset ()
	Resets the state of this object.

Protected Member Functions
virtual void	databaseConfigApply (const db::BackendSelector &backend_selector, const db::ServerSelector &server_selector, const boost::posix_time::ptime &lb_modification_time, const db::AuditEntryCollection &audit_entries)=0
	Server specific method to fetch and apply back end configuration into the local configuration.

db::AuditEntryCollection	fetchConfigElement (const db::AuditEntryCollection &audit_entries, const std::string &object_type) const
	Returns audit entries for new or updated configuration elements of specific type to be fetched from the database.

ConfigBackendMgrType &	getMgr () const
	Returns the instance of the Config Backend Manager used by this object.

void	updateLastAuditRevisionTimeId (const db::AuditEntryCollection &audit_entries)
	Updates timestamp of the most recent audit entry fetched from the database.

Static Protected Member Functions
static boost::posix_time::ptime	getInitialAuditRevisionTime ()
	Convenience method returning initial timestamp to set the `last_audit_revision_time_` to.

Protected Attributes
uint64_t	last_audit_revision_id_
	Stores the most recent audit revision identifier.

boost::posix_time::ptime	last_audit_revision_time_
	Stores the most recent audit revision timestamp.

Detailed Description

template<typename ConfigBackendMgrType>
class isc::process::CBControlBase< ConfigBackendMgrType >

Base class for implementing server specific mechanisms to control the use of the Configuration Backends.

Every Kea server using Config Backend as a configuration repository fetches configuration available for this server during startup and then periodically while it is running. In both cases, the server has to take into account that there is some existing configuration that the server already knows, into which the configuration from the database has to be merged.

When the server starts up, the existing configuration is the one that the server reads from the configuration file. Usually, the configuration fetched from the file will be disjointed with the configuration in the database, e.g. all subnets should be specified either in the configuration file or a database, not in both. However, there may be other cases when option definitions are held in the configuration file, but the DHCP options using them are stored in the database. The typical configuration sequence upon the server startup will be to build the staging configuration from the data stored in the configuration file and then build another partial configuration from the data fetched from the database. Finally, both configurations should be merged and committed if they are deemed sane.

When the server is already running it may use "audit" (a.k.a. journal) to periodically check if there are any pending configuration updates. If changes are present, it will be fetched and used to create a new configuration object (derived from the ConfigBase) holding this partial configuration. This configuration has to be subsequently merged into the current configuration that the server is using.

Note the difference between these two use cases is that in the first case the fetched configuration is fetched into the staging configuration and then committed, and in the second case it has to be directly merged into the running configuration.

This class contains some common logic to facilitate both scenarios which will be used by all server types. It also contains some pure virtual methods to be implemented by specific servers. The common logic includes the following operations:

use the "config-control" specification to connect to the specified databases via the configuration backends,
fetch the audit trail to detect configuration updates,
store the timestamp and id of the most recent audit entry fetched from the database, so as next time it can fetch only the later updates.

The server specific part to be implemented in derived classes must correctly interpret the audit entries and make appropriate API calls to fetch the indicated configuration changes. It should also merge the fetched configuration into the staging or current configuration. Note that this class doesn't recognize whether it is a staging or current configuration it is merging into. It simply uses the instance provided by the caller.

Template Parameters

ConfigBackendMgrType Type of the Config Backend Manager used by the server implementing this class. For example, for the DHCPv4 server it will be ConfigBackendDHCPv4Mgr.

Definition at line 82 of file cb_ctl_base.h.

Member Enumeration Documentation

◆ FetchMode

template<typename ConfigBackendMgrType >

enum class isc::process::CBControlBase::FetchMode

strong

Fetch mode used in invocations to databaseConfigFetch.

One of the values indicates that the entire configuration should be fetched. The other one indicates that only configuration updates should be fetched.

Enumerator
FETCH_ALL
FETCH_UPDATE

Definition at line 90 of file cb_ctl_base.h.

Constructor & Destructor Documentation

◆ CBControlBase()

template<typename ConfigBackendMgrType >

isc::process::CBControlBase< ConfigBackendMgrType >::CBControlBase ( )

inline

Constructor.

Sets the time of the last fetched audit entry to Jan 1st, 2000, with id 0.

Definition at line 99 of file cb_ctl_base.h.

◆ ~CBControlBase()

template<typename ConfigBackendMgrType >

virtual isc::process::CBControlBase< ConfigBackendMgrType >::~CBControlBase ( )

inlinevirtual

Virtual destructor.

It is always needed when there are virtual methods.

Definition at line 107 of file cb_ctl_base.h.

References isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigDisconnect().

Here is the call graph for this function:

Member Function Documentation

◆ databaseConfigApply()

template<typename ConfigBackendMgrType >

virtual void isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigApply	(	const db::BackendSelector &	backend_selector,
		const db::ServerSelector &	server_selector,
		const boost::posix_time::ptime &	lb_modification_time,
		const db::AuditEntryCollection &	audit_entries )

protectedpure virtual

Server specific method to fetch and apply back end configuration into the local configuration.

This pure virtual method must be implemented in the derived classes to provide server specific implementation of fetching and applying the configuration. The implementations should perform the following sequence of operations:

Check if any audit entries exist. If none exist, assume that this is the case of full server (re)configuration, otherwise assume that configuration update is being performed.
Select audit entries which indicate deletion of any configuration elements. For each such audit entry delete the given object from the local configuration.
If the server is performing full reconfiguration, fetch the entire configuration for the server. If the server is merely updating the server configuration, fetch only those objects for which (create/update) audit entries exist.
Merge the fetched configuration into the local server's configuration.

Parameters

backend_selector	Backend selector.
server_selector	Server selector.
lb_modification_time	Lower bound modification time for the configuration elements to be fetched.
audit_entries	Audit entries fetched from the database since the last configuration update. This collection is empty if there were no updates.

Implemented in isc::dhcp::CBControlDHCPv4, and isc::dhcp::CBControlDHCPv6.

Referenced by isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigFetch().

◆ databaseConfigConnect()

template<typename ConfigBackendMgrType >

bool isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigConnect ( const ConfigPtr & srv_cfg )

inline

(Re)connects to the specified configuration backends.

This method disconnects from any existing configuration backends and then connects to those listed in the ConfigControlInfo structure within the srv_cfg argument. This method is called when the server starts up. It is not called when it merely fetches configuration updates.

Parameters

srv_cfg Pointer to the staging server configuration.

Returns: true if the server found at least one backend to connect to, false if there are no backends available.

Definition at line 133 of file cb_ctl_base.h.

References isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigDisconnect(), isc::process::DCTL_DB_OPEN_CONNECTION_WITH_RETRY_FAILED, isc::process::dctl_logger, isc::process::DCTL_OPEN_CONFIG_DB, isc::process::CBControlBase< ConfigBackendMgrType >::getMgr(), LOG_INFO, and isc::Exception::what().

Referenced by isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigFetch().

Here is the call graph for this function:

◆ databaseConfigDisconnect()

template<typename ConfigBackendMgrType >

void isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigDisconnect ( )

inline

Disconnects from the configuration backends.

Definition at line 163 of file cb_ctl_base.h.

References isc::process::CBControlBase< ConfigBackendMgrType >::getMgr().

Referenced by isc::process::CBControlBase< ConfigBackendMgrType >::~CBControlBase(), isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigConnect(), and isc::process::CBControlBase< ConfigBackendMgrType >::reset().

Here is the call graph for this function:

◆ databaseConfigFetch()

template<typename ConfigBackendMgrType >

virtual void isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigFetch	(	const ConfigPtr &	srv_cfg,
		const FetchMode &	fetch_mode = FetchMode::FETCH_ALL )

inlinevirtual

Fetches the entire or partial configuration from the database.

This method is called by the starting up server to fetch and merge the entire configuration from the database or to fetch configuration updates periodically, e.g. as a result of triggering an interval timer callback.

Parameters

srv_cfg	pointer to the staging configuration that should hold the config backends list and other partial configuration read from the file in case the method is called upon the server's start up. It is a pointer to the current server configuration if the method is called to fetch configuration updates.
fetch_mode	value indicating if the method is called upon the server start up or it is called to fetch configuration updates.

Todo: We need a separate API call for the latter case to only fetch the last audit entry rather than all of them.

Todo: Consider reverting to the initial value to reload the entire configuration if the update failed.

Definition at line 181 of file cb_ctl_base.h.

References isc::db::ServerSelector::ALL(), isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigApply(), isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigConnect(), isc::process::DCTL_CONFIG_FETCH, isc::process::dctl_logger, isc::process::CBControlBase< ConfigBackendMgrType >::FETCH_ALL, isc::process::CBControlBase< ConfigBackendMgrType >::getMgr(), isc::process::CBControlBase< ConfigBackendMgrType >::last_audit_revision_id_, isc::process::CBControlBase< ConfigBackendMgrType >::last_audit_revision_time_, LOG_INFO, isc::db::ServerSelector::ONE(), isc::db::BackendSelector::UNSPEC, and isc::process::CBControlBase< ConfigBackendMgrType >::updateLastAuditRevisionTimeId().

Here is the call graph for this function:

◆ fetchConfigElement()

template<typename ConfigBackendMgrType >

db::AuditEntryCollection isc::process::CBControlBase< ConfigBackendMgrType >::fetchConfigElement	(	const db::AuditEntryCollection &	audit_entries,
		const std::string &	object_type ) const

inlineprotected

Returns audit entries for new or updated configuration elements of specific type to be fetched from the database.

This is convenience method invoked from the implementations of the databaseConfigApply function. This method is invoked when the server should fetch the updates to the existing configuration. The collection of audit entries contains audit entries indicating the updates to be fetched. This method returns audit entries for updated configuration elements of the specific type the databaseConfigApply should fetch. The returned collection od audit entries contains CREATE or UPDATE entries of the specific type.

Parameters

audit_entries	collection od audit entries to filter.
object_type	object type to filter with.

Returns: audit entries collection with CREATE or UPDATE entries of the specific type be fetched from the database.

Definition at line 270 of file cb_ctl_base.h.

References isc::db::AuditEntry::DELETE.

◆ getInitialAuditRevisionTime()

template<typename ConfigBackendMgrType >

static boost::posix_time::ptime isc::process::CBControlBase< ConfigBackendMgrType >::getInitialAuditRevisionTime ( )

inlinestaticprotected

Convenience method returning initial timestamp to set the last_audit_revision_time_ to.

Returns: Returns 2000-Jan-01 00:00:00 in local time.

Definition at line 328 of file cb_ctl_base.h.

Referenced by isc::process::CBControlBase< ConfigBackendMgrType >::reset().

◆ getMgr()

template<typename ConfigBackendMgrType >

ConfigBackendMgrType & isc::process::CBControlBase< ConfigBackendMgrType >::getMgr ( ) const

inlineprotected

Returns the instance of the Config Backend Manager used by this object.

Returns: Reference to the CB Manager instance.

Definition at line 320 of file cb_ctl_base.h.

Referenced by isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigConnect(), isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigDisconnect(), and isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigFetch().

◆ reset()

template<typename ConfigBackendMgrType >

void isc::process::CBControlBase< ConfigBackendMgrType >::reset ( )

inline

Resets the state of this object.

Disconnects the configuration backends resets the recorded last audit revision time and id.

Definition at line 115 of file cb_ctl_base.h.

References isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigDisconnect(), isc::process::CBControlBase< ConfigBackendMgrType >::getInitialAuditRevisionTime(), isc::process::CBControlBase< ConfigBackendMgrType >::last_audit_revision_id_, and isc::process::CBControlBase< ConfigBackendMgrType >::last_audit_revision_time_.

Here is the call graph for this function:

◆ updateLastAuditRevisionTimeId()

template<typename ConfigBackendMgrType >

void isc::process::CBControlBase< ConfigBackendMgrType >::updateLastAuditRevisionTimeId ( const db::AuditEntryCollection & audit_entries )

inlineprotected

Updates timestamp of the most recent audit entry fetched from the database.

If the collection of audit entries is empty, this method simply returns without updating the timestamp.

Parameters

audit_entries reference to the collection of the fetched audit entries.

Definition at line 341 of file cb_ctl_base.h.

References isc::process::CBControlBase< ConfigBackendMgrType >::last_audit_revision_id_, and isc::process::CBControlBase< ConfigBackendMgrType >::last_audit_revision_time_.

Referenced by isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigFetch().

Member Data Documentation

◆ last_audit_revision_id_

template<typename ConfigBackendMgrType >

uint64_t isc::process::CBControlBase< ConfigBackendMgrType >::last_audit_revision_id_

protected

Stores the most recent audit revision identifier.

The identifier is used when two (or more) audit entries have the same timestamp. It is not used by itself because timestamps are more user friendly. Unfortunately old versions of MySQL do not support millisecond timestamps.

Definition at line 364 of file cb_ctl_base.h.

Referenced by isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigFetch(), isc::process::CBControlBase< ConfigBackendMgrType >::reset(), and isc::process::CBControlBase< ConfigBackendMgrType >::updateLastAuditRevisionTimeId().

◆ last_audit_revision_time_

template<typename ConfigBackendMgrType >

boost::posix_time::ptime isc::process::CBControlBase< ConfigBackendMgrType >::last_audit_revision_time_

protected

Stores the most recent audit revision timestamp.

Definition at line 356 of file cb_ctl_base.h.

Referenced by isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigFetch(), isc::process::CBControlBase< ConfigBackendMgrType >::reset(), and isc::process::CBControlBase< ConfigBackendMgrType >::updateLastAuditRevisionTimeId().

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

cb_ctl_base.h

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ FetchMode

Constructor & Destructor Documentation

◆ CBControlBase()

◆ ~CBControlBase()

Member Function Documentation

◆ databaseConfigApply()

◆ databaseConfigConnect()

◆ databaseConfigDisconnect()

◆ databaseConfigFetch()

◆ fetchConfigElement()

◆ getInitialAuditRevisionTime()

◆ getMgr()

◆ reset()

◆ updateLastAuditRevisionTimeId()

Member Data Documentation

◆ last_audit_revision_id_

◆ last_audit_revision_time_