Kea  2.3.2-git
isc::process::CBControlBase< ConfigBackendMgrType > Class Template Referenceabstract

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  FetchMode { FetchMode::FETCH_ALL, FetchMode::FETCH_UPDATE }
 Fetch mode used in invocations to databaseConfigFetch. More...
 

Public Member Functions

 CBControlBase ()
 Constructor. More...
 
virtual ~CBControlBase ()
 Virtual destructor. More...
 
bool databaseConfigConnect (const ConfigPtr &srv_cfg)
 (Re)connects to the specified configuration backends. More...
 
void databaseConfigDisconnect ()
 Disconnects from the configuration backends. More...
 
virtual void databaseConfigFetch (const ConfigPtr &srv_cfg, const FetchMode &fetch_mode=FetchMode::FETCH_ALL)
 Fetches the entire or partial configuration from the database. More...
 
void reset ()
 Resets the state of this object. More...
 

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. More...
 
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. More...
 
ConfigBackendMgrType & getMgr () const
 Returns the instance of the Config Backend Manager used by this object. More...
 
void updateLastAuditRevisionTimeId (const db::AuditEntryCollection &audit_entries)
 Updates timestamp of the most recent audit entry fetched from the database. More...
 

Static Protected Member Functions

static boost::posix_time::ptime getInitialAuditRevisionTime ()
 Convenience method returning initial timestamp to set the last_audit_revision_time_ to. More...
 

Protected Attributes

uint64_t last_audit_revision_id_
 Stores the most recent audit revision identifier. More...
 
boost::posix_time::ptime last_audit_revision_time_
 Stores the most recent audit revision timestamp. More...
 

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
ConfigBackendMgrTypeType 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 80 of file cb_ctl_base.h.

Member Enumeration Documentation

◆ FetchMode

template<typename ConfigBackendMgrType>
enum 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 88 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 97 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 105 of file cb_ctl_base.h.

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_selectorBackend selector.
server_selectorServer selector.
lb_modification_timeLower bound modification time for the configuration elements to be fetched.
audit_entriesAudit 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< ConfigBackendDHCPv4Mgr >::databaseConfigFetch(), and isc::process::CBControlBase< ConfigBackendDHCPv4Mgr >::fetchConfigElement().

◆ 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_cfgPointer 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 131 of file cb_ctl_base.h.

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

◆ databaseConfigDisconnect()

template<typename ConfigBackendMgrType>
void isc::process::CBControlBase< ConfigBackendMgrType >::databaseConfigDisconnect ( )
inline

◆ 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_cfgpointer 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_modevalue 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 173 of file cb_ctl_base.h.

◆ 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_entriescollection od audit entries to filter.
object_typeobject 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 262 of file cb_ctl_base.h.

◆ 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 320 of file cb_ctl_base.h.

Referenced by isc::process::CBControlBase< ConfigBackendDHCPv4Mgr >::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 312 of file cb_ctl_base.h.

Referenced by isc::process::CBControlBase< ConfigBackendDHCPv4Mgr >::databaseConfigConnect(), isc::process::CBControlBase< ConfigBackendDHCPv4Mgr >::databaseConfigDisconnect(), and isc::process::CBControlBase< ConfigBackendDHCPv4Mgr >::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 113 of file cb_ctl_base.h.

◆ 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_entriesreference to the collection of the fetched audit entries.

Definition at line 333 of file cb_ctl_base.h.

Referenced by isc::process::CBControlBase< ConfigBackendDHCPv4Mgr >::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 356 of file cb_ctl_base.h.

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

◆ last_audit_revision_time_

template<typename ConfigBackendMgrType>
boost::posix_time::ptime isc::process::CBControlBase< ConfigBackendMgrType >::last_audit_revision_time_
protected

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