AppSuite:CrossContextDatabase - Revision history

Choeger at 07:54, 5 November 2021

2021-11-05T07:54:05Z

← Older revision		Revision as of 07:54, 5 November 2021
Line 3:		Line 3:
	{{VersionFrom\|7.8.0}}		{{VersionFrom\|7.8.0}}

	This article is valid from 7.8.0 to 7.10.1 and is not updated for newer versions anymore. For 7.10.2 and onwards you can find the corresponding documentation at https://documentation.open-xchange.com.		This article is valid from 7.8.0 to 7.10.1 and is not updated for newer versions anymore. For 7.10.2 and onwards you can find the corresponding documentation at https://documentation.open-xchange.com (currently https://documentation.open-xchange.com/latest/middleware/administration/global_database.html)

	__TOC__		__TOC__

Tobias.friedrich at 11:45, 12 April 2019

2019-04-12T11:45:35Z

← Older revision		Revision as of 11:45, 12 April 2019
Line 2:		Line 2:

	{{VersionFrom\|7.8.0}}		{{VersionFrom\|7.8.0}}

			This article is valid from 7.8.0 to 7.10.1 and is not updated for newer versions anymore. For 7.10.2 and onwards you can find the corresponding documentation at https://documentation.open-xchange.com.

	__TOC__		__TOC__

WolfgangRosenauer: /* Context Groups */

2018-11-14T07:35:31Z

Context Groups

← Older revision		Revision as of 07:35, 14 November 2018
Line 28:		Line 28:

	As already mentioned, data inside the global database is shared between and available to all contexts in the installation. For setups serving multiple different "brands" or "domains", this may not be the desired behavior, so that an additional level of data separation is needed for cross-context data. Therefore, one or more contexts can be classified into a specific "group". The association with the group is done by assigning the property <tt>com.openexchange.context.group</tt> to a context via config cascade. A context may only be part of one group, contexts without group association automatically fall into the "default" group.		As already mentioned, data inside the global database is shared between and available to all contexts in the installation. For setups serving multiple different "brands" or "domains", this may not be the desired behavior, so that an additional level of data separation is needed for cross-context data. Therefore, one or more contexts can be classified into a specific "group". The association with the group is done by assigning the property <tt>com.openexchange.context.group</tt> to a context via config cascade. A context may only be part of one group, contexts without group association automatically fall into the "default" group.

			Please note that context group names must not be longer than 32 characters!

	As an example, a hoster is selling his hosted e-mail services under two different brands, called "Clever Hosting" and "Smart Hosting". Each customer that registered an account at "Clever Hosting" now is put into the context group "clever_hosting" by setting the property <tt>com.openexchange.context.group</tt> at any level of the config cascade, e.g. during provisioning when creating the context like:		As an example, a hoster is selling his hosted e-mail services under two different brands, called "Clever Hosting" and "Smart Hosting". Each customer that registered an account at "Clever Hosting" now is put into the context group "clever_hosting" by setting the property <tt>com.openexchange.context.group</tt> at any level of the config cascade, e.g. during provisioning when creating the context like:

Choeger at 11:17, 30 August 2018

2018-08-30T11:17:36Z

← Older revision		Revision as of 11:17, 30 August 2018
Line 13:		Line 13:
	So, much similar to the groupware databases that store context-internal data, a new global database can be registered using the <tt>registerdatabase</tt> commandline tool. To prevent the registered database being picked up for groupware data, set the <tt>maxunit</tt> argument to <tt>0</tt>:		So, much similar to the groupware databases that store context-internal data, a new global database can be registered using the <tt>registerdatabase</tt> commandline tool. To prevent the registered database being picked up for groupware data, set the <tt>maxunit</tt> argument to <tt>0</tt>:

	$ ./registerdatabase -A oxadminmaster -P admin_master_password --name oxglobal --hostname localhost --dbuser openexchange --dbpasswd db_password --master true --maxunit 0		$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P admin_master_password --name oxglobal --hostname localhost --dbuser openexchange --dbpasswd db_password --master true --maxunit 0
	database 8 registered		database 8 registered

Line 20:		Line 20:
	Optionally, in case a database slave should be added, you can register it afterwards by specifying the database identifier as <tt>masterid</tt> like follows:		Optionally, in case a database slave should be added, you can register it afterwards by specifying the database identifier as <tt>masterid</tt> like follows:

	$ ./registerdatabase -A oxadminmaster -P admin_master_password --name oxglobal_slave --hostname slave_host --dbuser openexchange --dbpasswd db_password --master false --maxunit 0 --masterid=8		$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P admin_master_password --name oxglobal_slave --hostname slave_host --dbuser openexchange --dbpasswd db_password --master false --maxunit 0 --masterid=8
	database 9 registered		database 9 registered

Line 31:		Line 31:
	As an example, a hoster is selling his hosted e-mail services under two different brands, called "Clever Hosting" and "Smart Hosting". Each customer that registered an account at "Clever Hosting" now is put into the context group "clever_hosting" by setting the property <tt>com.openexchange.context.group</tt> at any level of the config cascade, e.g. during provisioning when creating the context like:		As an example, a hoster is selling his hosted e-mail services under two different brands, called "Clever Hosting" and "Smart Hosting". Each customer that registered an account at "Clever Hosting" now is put into the context group "clever_hosting" by setting the property <tt>com.openexchange.context.group</tt> at any level of the config cascade, e.g. during provisioning when creating the context like:

	$ ./createcontext [...] --config/com.openexchange.context.group=clever_hosting		$ /opt/open-xchange/sbin/createcontext [...] --config/com.openexchange.context.group=clever_hosting

	Or, if you already tagged your contexts with different taxonomy types (like <tt>clever</tt> and <tt>smart</tt> in our example), the assignment to a context group can also be achieved at "ContextSet" level inside an <tt>.yml</tt>-file of your <tt>contextSets</tt> definitions:		Or, if you already tagged your contexts with different taxonomy types (like <tt>clever</tt> and <tt>smart</tt> in our example), the assignment to a context group can also be achieved at "ContextSet" level inside an <tt>.yml</tt>-file of your <tt>contextSets</tt> definitions:

Choeger at 11:21, 6 August 2015

2015-08-06T11:21:54Z

← Older revision		Revision as of 11:21, 6 August 2015
Line 9:		Line 9:
	== Register databases ==		== Register databases ==

	As a prerequisite, a global database needs to be registered in the Open-Xchange server's configuration database. At the storage layer, global databases are handled just like the ~~oridnary~~ <tt>context</tt> databases storing all the existing groupware data. Therefore, the same underlying technologies can be used for replication like master/slave- or Galera-based setups, as well as registering additional database pools for sharding in very large installations.		As a prerequisite, a global database needs to be registered in the Open-Xchange server's configuration database. At the storage layer, global databases are handled just like the ordinary <tt>context</tt> databases storing all the existing groupware data. Therefore, the same underlying technologies can be used for replication like master/slave- or Galera-based setups, as well as registering additional database pools for sharding in very large installations.

	So, much similar to the groupware databases that store context-internal data, a new global database can be registered using the <tt>registerdatabase</tt> commandline tool. To prevent the registered database being picked up for groupware data, set the <tt>maxunit</tt> argument to <tt>0</tt>:		So, much similar to the groupware databases that store context-internal data, a new global database can be registered using the <tt>registerdatabase</tt> commandline tool. To prevent the registered database being picked up for groupware data, set the <tt>maxunit</tt> argument to <tt>0</tt>:

Choeger at 11:19, 6 August 2015

2015-08-06T11:19:00Z

← Older revision		Revision as of 11:19, 6 August 2015
Line 5:		Line 5:
	__TOC__		__TOC__

	For storing data ~~acrosss~~ context boundaries, a so called "global" database is used by the server. For example, such shared data could be information about guest users or data for registered OAuth applications. This article gives an overview about the basic concepts and how to setup a global database.		For storing data across context boundaries, a so called "global" database is used by the server. For example, such shared data could be information about guest users or data for registered OAuth applications. This article gives an overview about the basic concepts and how to setup a global database.

	== Register databases ==		== Register databases ==

WolfgangRosenauer: /* Register databases */

2015-08-05T09:14:41Z

← Older revision		Revision as of 09:14, 5 August 2015
Line 13:		Line 13:
	So, much similar to the groupware databases that store context-internal data, a new global database can be registered using the <tt>registerdatabase</tt> commandline tool. To prevent the registered database being picked up for groupware data, set the <tt>maxunit</tt> argument to <tt>0</tt>:		So, much similar to the groupware databases that store context-internal data, a new global database can be registered using the <tt>registerdatabase</tt> commandline tool. To prevent the registered database being picked up for groupware data, set the <tt>maxunit</tt> argument to <tt>0</tt>:

	$ ./registerdatabase -A oxadminmaster -P admin_master_password --name oxglobal --hostname localhost --dbuser openexchange --dbpasswd ~~db_passwd~~ --master true --maxunit 0		$ ./registerdatabase -A oxadminmaster -P admin_master_password --name oxglobal --hostname localhost --dbuser openexchange --dbpasswd db_password --master true --maxunit 0
	database 8 registered		database 8 registered

WolfgangRosenauer: /* Register databases */

2015-08-04T15:45:07Z

← Older revision		Revision as of 15:45, 4 August 2015
Line 13:		Line 13:
	So, much similar to the groupware databases that store context-internal data, a new global database can be registered using the <tt>registerdatabase</tt> commandline tool. To prevent the registered database being picked up for groupware data, set the <tt>maxunit</tt> argument to <tt>0</tt>:		So, much similar to the groupware databases that store context-internal data, a new global database can be registered using the <tt>registerdatabase</tt> commandline tool. To prevent the registered database being picked up for groupware data, set the <tt>maxunit</tt> argument to <tt>0</tt>:

	$ ./registerdatabase -A oxadminmaster -P ~~secret~~ --name oxglobal --hostname ~~10.20.30.217~~ --dbuser openexchange --dbpasswd ~~secret~~ --master true --maxunit 0		$ ./registerdatabase -A oxadminmaster -P admin_master_password --name oxglobal --hostname localhost --dbuser openexchange --dbpasswd db_passwd --master true --maxunit 0
	database 8 registered		database 8 registered

Line 20:		Line 20:
	Optionally, in case a database slave should be added, you can register it afterwards by specifying the database identifier as <tt>masterid</tt> like follows:		Optionally, in case a database slave should be added, you can register it afterwards by specifying the database identifier as <tt>masterid</tt> like follows:

	$ ./registerdatabase -A oxadminmaster -P ~~secret~~ --name oxglobal_slave --hostname ~~10.20.30.219~~ --dbuser openexchange --dbpasswd ~~secret~~ --master false --maxunit 0 --masterid=8		$ ./registerdatabase -A oxadminmaster -P admin_master_password --name oxglobal_slave --hostname slave_host --dbuser openexchange --dbpasswd db_password --master false --maxunit 0 --masterid=8
	database 9 registered		database 9 registered

	For smaller or test environments, it's also possible to re-use a previously registered groupware database for cross-context data, i.e. any database marked as <tt>master</tt> by the <tt>listdatabase</tt> ~~utiltiy~~ may be used. Please note that all cross-context data is not accounted when calculating the database weight during context creation.		For smaller or test environments, it's also possible to re-use a previously registered groupware database for cross-context data, i.e. any database marked as <tt>master</tt> by the <tt>listdatabase</tt> utility may be used. Please note that all cross-context data is not accounted when calculating the database weight during context creation.

	== Context Groups ==		== Context Groups ==

Tobias.friedrich at 12:09, 30 June 2015

2015-06-30T12:09:22Z

← Older revision		Revision as of 12:09, 30 June 2015
Line 27:		Line 27:
	== Context Groups ==		== Context Groups ==

	As already mentioned, data inside the global database is shared between and available to all contexts in the installation. For setups serving multiple different "brands" or "domains", this may not be the desired ~~behaviour~~, so that an additional level of data separation is needed for cross-context data. Therefore, one or more contexts can be classified into a specific "group". The association with the group is done by assigning the property "com.openexchange.context.group" to a context via config cascade. A context may only be part of one group, contexts without group association automatically fall into the "default" group.		As already mentioned, data inside the global database is shared between and available to all contexts in the installation. For setups serving multiple different "brands" or "domains", this may not be the desired behavior, so that an additional level of data separation is needed for cross-context data. Therefore, one or more contexts can be classified into a specific "group". The association with the group is done by assigning the property <tt>com.openexchange.context.group</tt> to a context via config cascade. A context may only be part of one group, contexts without group association automatically fall into the "default" group.

	As an example, a hoster is selling his hosted e-mail services under two different brands, called "Clever Hosting" and "Smart Hosting". Each customer that registered an account at "Clever Hosting" now is put into the context group "clever_hosting" by setting the property <tt>com.openexchange.context.group</tt> at any level of the config cascade, e.g. during provisioning when creating the context like:		As an example, a hoster is selling his hosted e-mail services under two different brands, called "Clever Hosting" and "Smart Hosting". Each customer that registered an account at "Clever Hosting" now is put into the context group "clever_hosting" by setting the property <tt>com.openexchange.context.group</tt> at any level of the config cascade, e.g. during provisioning when creating the context like:
Line 50:		Line 50:

	In the global database, the context group identifier serves as differentiating key for various data. For example, data of a guest user that was invited to a share in one context of a group can be used throughout all other contexts of the same group. Or, there may be a different set of registered OAuth applications available for each context group. Having contexts separated into different groups also allows to use different global databases as defined in the additional sections of the configuration file <tt>globaldb.yml</tt>. The next chapter describes the global database configuration file in more detail.		In the global database, the context group identifier serves as differentiating key for various data. For example, data of a guest user that was invited to a share in one context of a group can be used throughout all other contexts of the same group. Or, there may be a different set of registered OAuth applications available for each context group. Having contexts separated into different groups also allows to use different global databases as defined in the additional sections of the configuration file <tt>globaldb.yml</tt>. The next chapter describes the global database configuration file in more detail.


	== Configure databases ==		== Configure databases ==

	Global databases are defined in the configuration file <tt>globaldb.yml</tt>. It mainly serves the purpose to map registered global databases to context groups. In case no advanced context grouping is necessary, e.g. because there's only a single brand in the installation, it's sufficient to supply the identifier of the previously registered master database, see [[Register databases]] above, inside the <tt>default</tt> section of the configuration file. For example, if the identifier of the global database master is <tt>8</tt>, the section would look like:		Global databases are defined in the configuration file <tt>globaldb.yml</tt>. It mainly serves the purpose to map registered global databases to context groups. In case no advanced context grouping is necessary, e.g. because there's only a single brand in the installation, it's sufficient to supply the identifier of the previously registered master database, see [[#Register databases\|Register databases]] above, inside the <tt>default</tt> section of the configuration file. For example, if the identifier of the global database master is <tt>8</tt>, the section would look like:

	<pre>		<pre>
Line 62:		Line 61:
	</pre>		</pre>

	This would lead to all cross-context data being stored at this database, assigning distinguished context groups as described in [[Context Groups]] is not required.		This would lead to all cross-context data being stored at this database, assigning distinguished context groups as described in [[#Context Groups\|Context Groups]] is not required.

	If there are multiple context groups, those can be directed to a specific global database by adding their names to the <tt>groups</tt> property of a configuration section. For example, if the groups <tt>smart_hosting</tt> and <tt>clever_hosting</tt> should use database <tt>8</tt>, too, one could define:		If there are multiple context groups, those can be directed to a specific global database by adding their names to the <tt>groups</tt> property of a configuration section. For example, if the groups <tt>smart_hosting</tt> and <tt>clever_hosting</tt> should use database <tt>8</tt>, too, one could define:
Line 72:		Line 71:
	</pre>		</pre>

	Removing the default group name <tt>default</tt> from the groups list is not recommended, and should only be done if you can ensure that each context of the installation has it's group assignment defined ~~corectly~~ in the property <tt>com.openexchange.context.group</tt>.		Removing the default group name <tt>default</tt> from the groups list is not recommended, and should only be done if you can ensure that each context of the installation has it's group assignment defined correctly in the property <tt>com.openexchange.context.group</tt>.

	Having contexts separated into different groups also allows to use different global databases as defined in the additional sections of the configuration file <tt>globaldb.yml</tt>. Since context groups are bound to a configuration section by specifying the group name in the "groups" array, and each configuration section may target another global database, in theory there could be as much global databases as there are defined context groups. For example, to enforce data from the context groups <tt>smart_hosting</tt> and <tt>clever_hosting</tt> being stored at separate databases, the following configuration sections would route them to the database identifiers <tt>8</tt> and <tt>14</tt> respectively:		Having contexts separated into different groups also allows to use different global databases as defined in the additional sections of the configuration file <tt>globaldb.yml</tt>. Since context groups are bound to a configuration section by specifying the group name in the "groups" array, and each configuration section may target another global database, in theory there could be as much global databases as there are defined context groups. For example, to enforce data from the context groups <tt>smart_hosting</tt> and <tt>clever_hosting</tt> being stored at separate databases, the following configuration sections would route them to the database identifiers <tt>8</tt> and <tt>14</tt> respectively:

Tobias.friedrich: Created page with "
Cross-context database
{{VersionFrom|7.8.0}} TOC For storing data acrosss context boundaries, a so called "global" database is used by the serv..."

2015-06-30T12:01:39Z

Created page with "<div class="title">Cross-context database</div> {{VersionFrom|7.8.0}} __TOC__ For storing data acrosss context boundaries, a so called "global" database is used by the serv..."

New page

<div class="title">Cross-context database</div>

{{VersionFrom|7.8.0}}

__TOC__

For storing data acrosss context boundaries, a so called "global" database is used by the server. For example, such shared data could be information about guest users or data for registered OAuth applications. This article gives an overview about the basic concepts and how to setup a global database.

== Register databases ==

As a prerequisite, a global database needs to be registered in the Open-Xchange server's configuration database. At the storage layer, global databases are handled just like the oridnary <tt>context</tt> databases storing all the existing groupware data. Therefore, the same underlying technologies can be used for replication like master/slave- or Galera-based setups, as well as registering additional database pools for sharding in very large installations.

So, much similar to the groupware databases that store context-internal data, a new global database can be registered using the <tt>registerdatabase</tt> commandline tool. To prevent the registered database being picked up for groupware data, set the <tt>maxunit</tt> argument to <tt>0</tt>:

$ ./registerdatabase -A oxadminmaster -P secret --name oxglobal --hostname 10.20.30.217 --dbuser openexchange --dbpasswd secret --master true --maxunit 0
database 8 registered

Remember the returned database identifier, <tt>8</tt> in the above example, we'll need it at a later stage.

Optionally, in case a database slave should be added, you can register it afterwards by specifying the database identifier as <tt>masterid</tt> like follows:

$ ./registerdatabase -A oxadminmaster -P secret --name oxglobal_slave --hostname 10.20.30.219 --dbuser openexchange --dbpasswd secret --master false --maxunit 0 --masterid=8
database 9 registered

For smaller or test environments, it's also possible to re-use a previously registered groupware database for cross-context data, i.e. any database marked as <tt>master</tt> by the <tt>listdatabase</tt> utiltiy may be used. Please note that all cross-context data is not accounted when calculating the database weight during context creation.

== Context Groups ==

As already mentioned, data inside the global database is shared between and available to all contexts in the installation. For setups serving multiple different "brands" or "domains", this may not be the desired behaviour, so that an additional level of data separation is needed for cross-context data. Therefore, one or more contexts can be classified into a specific "group". The association with the group is done by assigning the property "com.openexchange.context.group" to a context via config cascade. A context may only be part of one group, contexts without group association automatically fall into the "default" group.

As an example, a hoster is selling his hosted e-mail services under two different brands, called "Clever Hosting" and "Smart Hosting". Each customer that registered an account at "Clever Hosting" now is put into the context group "clever_hosting" by setting the property <tt>com.openexchange.context.group</tt> at any level of the config cascade, e.g. during provisioning when creating the context like:

$ ./createcontext [...] --config/com.openexchange.context.group=clever_hosting

Or, if you already tagged your contexts with different taxonomy types (like <tt>clever</tt> and <tt>smart</tt> in our example), the assignment to a context group can also be achieved at "ContextSet" level inside an <tt>.yml</tt>-file of your <tt>contextSets</tt> definitions:

<pre>
clever_group:
withTags: clever
com.openexchange.context.group: clever_hosting
ui/product/name: "Clever Hosting"
[...]

smart_group:
withTags: smart
com.openexchange.context.group: smart_hosting
ui/product/name: "Smart Hosting"
[...]
</pre>

In the global database, the context group identifier serves as differentiating key for various data. For example, data of a guest user that was invited to a share in one context of a group can be used throughout all other contexts of the same group. Or, there may be a different set of registered OAuth applications available for each context group. Having contexts separated into different groups also allows to use different global databases as defined in the additional sections of the configuration file <tt>globaldb.yml</tt>. The next chapter describes the global database configuration file in more detail.

== Configure databases ==

Global databases are defined in the configuration file <tt>globaldb.yml</tt>. It mainly serves the purpose to map registered global databases to context groups. In case no advanced context grouping is necessary, e.g. because there's only a single brand in the installation, it's sufficient to supply the identifier of the previously registered master database, see [[Register databases]] above, inside the <tt>default</tt> section of the configuration file. For example, if the identifier of the global database master is <tt>8</tt>, the section would look like:

<pre>
default:
groups: [default]
id: 8
</pre>

This would lead to all cross-context data being stored at this database, assigning distinguished context groups as described in [[Context Groups]] is not required.

If there are multiple context groups, those can be directed to a specific global database by adding their names to the <tt>groups</tt> property of a configuration section. For example, if the groups <tt>smart_hosting</tt> and <tt>clever_hosting</tt> should use database <tt>8</tt>, too, one could define:

<pre>
default:
groups: [default,smart_hosting,clever_hosting]
id: 8
</pre>

Removing the default group name <tt>default</tt> from the groups list is not recommended, and should only be done if you can ensure that each context of the installation has it's group assignment defined corectly in the property <tt>com.openexchange.context.group</tt>.

Having contexts separated into different groups also allows to use different global databases as defined in the additional sections of the configuration file <tt>globaldb.yml</tt>. Since context groups are bound to a configuration section by specifying the group name in the "groups" array, and each configuration section may target another global database, in theory there could be as much global databases as there are defined context groups. For example, to enforce data from the context groups <tt>smart_hosting</tt> and <tt>clever_hosting</tt> being stored at separate databases, the following configuration sections would route them to the database identifiers <tt>8</tt> and <tt>14</tt> respectively:

<pre>
clever:
groups: [clever_hosting]
id: 8

smart:
groups: [smart_hosting]
id: 14
</pre>

== Reload global db configuration ==

After updating the globaldb.yml you have to reload the server configuration by using /opt/open-xchange/sbin/reloadconfiguration command line tool.

[[Category: AppSuite]]
[[Category: Administrator]]
[[Category: Database]]

AppSuite:CrossContextDatabase - Revision history

Choeger at 07:54, 5 November 2021

Tobias.friedrich at 11:45, 12 April 2019

WolfgangRosenauer: /* Context Groups */

Choeger at 11:17, 30 August 2018

Choeger at 11:21, 6 August 2015

Choeger at 11:19, 6 August 2015

WolfgangRosenauer: /* Register databases */

WolfgangRosenauer: /* Register databases */

Tobias.friedrich at 12:09, 30 June 2015

Tobias.friedrich: Created page with "Cross-context database {{VersionFrom|7.8.0}} __TOC__ For storing data acrosss context boundaries, a so called "global" database is used by the serv..."

Tobias.friedrich: Created page with "
Cross-context database
{{VersionFrom|7.8.0}} TOC For storing data acrosss context boundaries, a so called "global" database is used by the serv..."