| Kea 3.0.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 >:
[legend]

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

References getInitialAuditRevisionTime(), last_audit_revision_id_, and last_audit_revision_time_.

Referenced by isc::dhcp::CBControlDHCP< ConfigBackendMgrType >::CBControlDHCP().

Here is the call graph for this function:

## ◆ ~CBControlBase()

template<typename ConfigBackendMgrType>

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

Virtual destructor.

It is always needed when there are virtual methods.

Definition at line 107 of file cb_ctl_base.h.

References 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 )
| protected pure 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 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 databaseConfigDisconnect(), isc::process::DCTL_DB_OPEN_CONNECTION_WITH_RETRY_FAILED, isc::process::dctl_logger, isc::process::DCTL_OPEN_CONFIG_DB, getMgr(), LOG_INFO, and isc::Exception::what().

Referenced by 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 getMgr().

Referenced by ~CBControlBase(), databaseConfigConnect(), and 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 )
| inline virtual

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(), databaseConfigApply(), databaseConfigConnect(), isc::process::DCTL_CONFIG_FETCH, isc::process::dctl_logger, FETCH_ALL, getMgr(), last_audit_revision_id_, last_audit_revision_time_, LOG_INFO, isc::db::ServerSelector::ONE(), isc::db::BackendSelector::UNSPEC, and 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
| inline protected

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>

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

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 CBControlBase(), and reset().

## ◆ getMgr()

template<typename ConfigBackendMgrType>

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

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 databaseConfigConnect(), databaseConfigDisconnect(), and 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 databaseConfigDisconnect(), getInitialAuditRevisionTime(), last_audit_revision_id_, and 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 | ) |
| inline protected

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 last_audit_revision_id_, and last_audit_revision_time_.

Referenced by 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 CBControlBase(), databaseConfigFetch(), reset(), and 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 CBControlBase(), databaseConfigFetch(), reset(), and updateLastAuditRevisionTimeId().

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

- cb_ctl_base.h