Open-Xchange - User contributions [en]

AppSuite:DocumentConverterUpdate782

2016-09-08T12:28:21Z

Usman.ahmad:

{{Version|7.8.2}}

== Update Documentconverter from earlier versions to 7.8.2 ==

For a successful update to 7.8.2 some manual adjustments are necessary on the middleware node(s) as well as on the documentconverter node(s) after the package upgrade. For a single node deployment both sections have to be adhered to.

Further details are available from the [[AppSuite:DocumentConverter_Installation_Guide|Installation Guide]].

=== OX Documentconverter Service ===

After an upgrade the new package '''<tt>open-xchange-documentconverter-server</tt>''' replaces '''<tt>open-xchange-documentconverter-webservice</tt>'''. If <tt>open-xchange-documentconverter-server</tt> is not automatically installed (e.g. in a single node deployment) it has to be be added manually.

Changes to the configuration file documentconverter.properties need to be applied to the new one. For versions up to (including) 7.8.1 it was located at
<pre>
/opt/open-xchange/etc/documentconverter.properties
</pre>
Starting with 7.8.2 it's new home is
/opt/open-xchange/documentconverter/etc/documentconverter.properties

Note: If the file is moved from the old to the new location with all items the path settings in
'com.openexchange.documentconverter.blacklistFile' and 'com.openexchange.documentconverter.whitelistFile' have to be changed.

Futhermore logging needs to be configured separately from the middleware setting. A logback.xml file dedicated to the document converter process can be found at
<pre>
/opt/open-xchange/documentconverter/etc/logback.xml
</pre>

Most notable changes are the listening ports (http 8008, https 8011 and JMX 9998) which have to be different from those reserved for the middleware. Apache and monitoring configurations have to be adapted accordingly.



'''Note:''' Don't forget to enable / (re)start open-xchange-documentconverter-server.service in addition to the OX App Suite middleware.

=== OX App Suite Middleware (aka Backend or Documentconverter Client) ===

The property pointing to the documentconverter service has to be adjusted. It is now mandatory to set this entry – not only in the remote documentconverter setup but also if the documentconverter runs locally.
The property used changed from
<pre>
/opt/open-xchange/etc/documentconverter.properties:
com.openexchange.documentconverter.RemoteBaseUrl=
</pre>
to
<pre>
/opt/open-xchange/etc/documentconverter-client.properties: com.openexchange.documentconverter.client.remoteDocumentConverterUrl=
</pre>

For a single-node deployment this reads (in one line)

com.openexchange.documentconverter.client.remoteDocumentConverterUrl = http://localhost:8008/documentconverterws

Note:
If the logging configuration has been changed for documentconverter entries the logger needs a small change. The new class is name="com.openexchange.documentconverter"

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

OXReportClient

2016-01-07T13:43:31Z

Usman.ahmad:

== Introduction ==

* For customers who are using '''OX App Suite''' please [http://oxpedia.org/wiki/index.php?title=AppSuite:OXReportClient click here]

Beginning with the release of Open-Xchange Server version 6.18, '''generating a report every month'''
is mandatory in order to have access to the maintenance updates available in the updates directory
on software.open-xchange.com.

'''You have been blocked already?'''

'''Don't panic''', you can still access http://software.open-xchange.com/OX6/stable, because that
is open for everyone.
So install the Report Client from stable instead of updates and once you're done, update to the latest version.

The Open-Xchange Report Client extension of the Open-Xchange Server enables you to generate and send usage reports of your environment to Open-Xchange. The report will contain information of how many contexts and users have been created in the given Open-Xchange environment. This article will guide you through the installation of the Open-Xchange Report Client. It describes the setup of the software extension itself, and which additional configurations need to be done to execute this extension.

You will find further information at the Open-Xchange Frequent Asked Questions (FAQ)
* [http://sdb.open-xchange.com/faq/70 English]
* [http://sdb.open-xchange.com/category/1/71 German]

{{InstallPlugin|pluginname=open-xchange-report-client|sopath=6.22/updates/backend|version=v6.22.x}}

== Configuration ==

A requirement to execute the Open-Xchange Report Client is to have your Open-Xchange license key stored in one specific file on your Open-Xchange installation. The latest version of our [[Main_Page#Installation_based_on_packages | installation guide]] documentation will automatically enable you to store your license key on disk by using a new oxinstaller command.

If you want to use the report client on an already installed environment you need to store your license key manually on disk. To do so create and edit the following file on your Open-Xchange server:

$ vim /opt/open-xchange/etc/common/licensekeys.properties

or on 6.22 or newer

$ vim /opt/open-xchange/etc/licensekeys.properties

com.openexchange.licensekey.1=PUT_YOUR_OPEN-XCHANGE_LICENSE_KEY_HERE

If you are behind a firewall and the report client needs to be configured using a HTTP proxy, please edit file:

$ vim /opt/open-xchange/etc/groupware/reportclient.properties

or on 6.22 or newer

$ vim /opt/open-xchange/etc/reportclient.properties

After editing this file accordingly to your proxy needs, try to start the report client again.

== Using the Report tool ==

Now as the package has been correctly installed and you provided your license key in the according properties file your are ready to launch the report client to generate a report. By default (if no option is given) the report client will display and send the generated report to an Open-Xchange service on activation.open-xchange.com. Note that only data that is displayed in the console will be transfered to Open-Xchange

'''activation.open-xchange.com:443'''

=== Report kinds ===

In general there are two kinds of reports. Since 7.8.0 the default report has got the appsuite style format. If you would like to generate and display/save/send the formerly used style you have to add the option "-o" to every known parameter combination.

=== Display data usage report ===

$ /opt/open-xchange/sbin/report -d

If you want to know which data would be transfered, execute the report client with the option "-d" (display_only). If this option is given to the report client no data will be send:

=== Send data usage report ===

$ /opt/open-xchange/sbin/report -s

If you don't want to have the report displayed in the console (which might be the case for automated executions of the report client) execute the report client with the option -s (send_only). Now no report will be displayed after the report has been sent to activation.open-xchange.com.

=== Available options ===

$ /opt/open-xchange/sbin/report -h

lists all available options:

Usage: report
-h,--help Prints a help text
--environment Show info about commandline environment
--nonl Remove all newlines (\n) from output
--responsetimeout <responsetimeout> response timeout in seconds for reading response from
the backend (default 0s; infinite)
-H,--host <host> specifies the host
-T,--timeout <timeout> timeout (in s) to conntect to the backend (default 15s)
-J,--jmxauthuser <jmxauthuser> jmx username (when jmx authentication enabled)
-P,--jmxauthpassword <jmxauthpassword> jmx password (when jmx authentication enabled)
-s,--sendonly Send report without displaying it (Disables default)
-d,--displayonly Display report without sending it (Disables default)
-c,--csv Show output as CSV
-a,--advancedreport Run an advanced report
-f,--savereport Save the report as JSON String instead of sending it
-b,--showaccesscombination <showaccesscombination> Show access combination for bitmask
-e,--run-appsuite-report Schedule an appsuite style report
-t,--report-type <report-type> The type of the report to run
--inspect-appsuite-reports Prints information about currently running reports
--cancel-appsuite-reports Cancels pending reports
-g,--get-appsuite-report Retrieve the report that was generated
-x,--run-and-deliver-report Create a new report and send it immediately
-o,--run-and-deliver-old-report Run old report type. Used to have a backward compatibility.

=== Explanation of the appsuite report console output ===

<pre>
$ /opt/open-xchange/sbin/report -d
Starting the Open-Xchange report client. Note that the report generation may take a little while.

f5f511d663ff462f8f963dfa41bd8cd2: 0/5 (0,00 %)
UUID: f5f511d663ff462f8f963dfa41bd8cd2
Type: default
Total time: 389 milliseconds
Avg. time per context: 77 milliseconds
Report was finished: Wed Jul 08 13:42:25 CEST 2015

------ report -------
{
"macdetail" : {
"capabilitySets" : [ {
"total" : 2,
"capabilities" : [ "auto_publish_attachments", "autologin", "caldav", "carddav", "drive", "infostore", "mailfilter", "oauth", "oauth-grants", "pop3", "printing", "publish_mail_attachments", "rss", "search", "twitter", "xing", "xingjson" ],
"quota" : 1073741824,
"admin" : 0,
"disabled" : 0
}, {
"total" : 11,
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "filestore", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],
"quota" : 1073741824,
"admin" : 3,
"disabled" : 0
}, {
"total" : 6,
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],
"quota" : 1073741824,
"admin" : 2,
"disabled" : 0
} ]
},
"total" : {
"guests" : 22,
"links" : 10,
"contexts" : 5,
"users" : 19,
"report-format" : "appsuite-short"
},
"clientlogincountyear" : {
"appsuite" : "7",
"olox2" : "0",
"caldav" : "0",
"usm-eas" : "0",
"mobileapp" : "0",
"ox6" : "9",
"carddav" : "1"
},
"clientlogincount" : {
"appsuite" : "4",
"olox2" : "0",
"caldav" : "0",
"usm-eas" : "0",
"mobileapp" : "0",
"ox6" : "2",
"carddav" : "1"
},
"uuid" : "f5f511d663ff462f8f963dfa41bd8cd2",
"reportType" : "default",
"timestamps" : {
"start" : 1436355744714,
"stop" : 1436355745103
},
"version" : {
"version" : "7.8.0-Rev0",
"buildDate" : "develop"
},
"configs" : {
"com.openexchange.mail.adminMailLoginEnabled" : "true"
}
}
------ end -------
</pre>

'''macdetail:'''
: detailed information about existing module access combinations and its usage
'''total:'''
: accumulated user, guest, link (anonymous share) and context count
'''clientlogincountyear:'''
: number of client logins for the last year
'''clientlogincount:'''
: number of client logins for the last month
'''uuid:'''
: a unique id for the report
'''reportType:'''
: given name for that report (normally 'default')
'''timestamps:'''
: timestamps of the start and end time of the report
'''versions:'''
: version and build date of the server
'''configs:'''
: server configuration (currently only for setting 'com.openexchange.mail.adminMailLoginEnabled')

=== Explanation of the old console output ===

$ /opt/open-xchange/sbin/report -o -d
Starting the Open-Xchange report client. Note that the report generation may take a little while.

module version
admin 6.20.5 Rev1
groupware 6.20.5 Rev1

'''contexts users guests links'''
5 19 22 10

'''mac count adm disabled'''
268435455 6 1 0
237044501 48 0 0
5 2 2 0

'''key value'''
com.openexchange.mail.adminMailLoginEnabled true

'''usmeas olox2 mobileapp carddav caldav'''
1 0 0 0 0

'''usmeasyear olox2year mobileappyear carddavyear caldavyear'''
4 12 7 11 10

'''contexts:'''
:total number of contexts
'''users:'''
:total number of users
'''guests:'''
:total number of guests
'''linkss:'''
:total number of links shared to anonymous users
'''mac:'''
:decimal value of the module access. For conversion decimal to human readable permission please use <tt>report -b</tt> as described below
'''count:'''
:amount of users with this module access
'''adm:'''
:amount of admin users with this specific module access
'''disabled:'''
:amount of users that are disabled
'''key:'''
:key of the configuration property
'''value:'''
:value of the configuration property

The last rows show the amount of users that did login to Open-Xchange within the ''last 30 days'' and ''the last year'' using the specified OXtender/service.

If you want to know the access permissions of a specific <tt>mac</tt>, run e.g.

$ /opt/open-xchange/sbin/report -b 237044501

'''usmeas:'''
:using mobile phone via active sync (OXtender for Business Mobility) within the last 30 days
'''olox2:'''
:using OXtender 2 for Microsoft Outlook within the last 30 days
'''mobileapp:'''
:using Open-Xchange Mobile Web Interface within the last 30 days
'''carddav/caldav:'''
:using the CalDAV/CardDAV feature within the last 30 days
'''usmeasyear:'''
:using mobile phone via active sync (OXtender for Business Mobility) within the last year
'''olox2:'''
:using OXtender 2 for Microsoft Outlook within the last year
'''mobileapp:'''
:using Open-Xchange Mobile Web Interface within the last year
'''carddav/caldav:'''
:using the CalDAV/CardDAV feature within the last year

'''Example:''' a value of 7 below <tt>olox2</tt> means, that within the last 30 days, 7 different users used the OXtender 2 for Microsoft Outlook to connect to Open-Xchange.

== Automatic reports ==

Creating a cron entry which will automatically execute the report client once a week saves a lot of work. To create this cron entry execute:

$ vim /etc/cron.d/open-xchange_report

0 3 * * 7 open-xchange /opt/open-xchange/sbin/report -s -x 1> /dev/null 2>&1

== What will be reported using the send method? ==

The report client will display and / or transfer the following information:

# Version number of the Open-Xchange server package
# Version number of the Open-Xchange admin package
# Total user count
# Total context count
# Detailed context information: context age, creation date or date of creation, user count, context id, capability sets
# Detailed user information (per context): User access combination flags (which modules have been activated for the users)

[[Category: OX6]]

OXReportClient

2016-01-07T13:40:34Z

Usman.ahmad:

== Introduction ==

* For customers who are using OX App Suite please [http://oxpedia.org/wiki/index.php?title=AppSuite:OXReportClient click here]

Beginning with the release of Open-Xchange Server version 6.18, '''generating a report every month'''
is mandatory in order to have access to the maintenance updates available in the updates directory
on software.open-xchange.com.

'''You have been blocked already?'''

'''Don't panic''', you can still access http://software.open-xchange.com/OX6/stable, because that
is open for everyone.
So install the Report Client from stable instead of updates and once you're done, update to the latest version.

The Open-Xchange Report Client extension of the Open-Xchange Server enables you to generate and send usage reports of your environment to Open-Xchange. The report will contain information of how many contexts and users have been created in the given Open-Xchange environment. This article will guide you through the installation of the Open-Xchange Report Client. It describes the setup of the software extension itself, and which additional configurations need to be done to execute this extension.

You will find further information at the Open-Xchange Frequent Asked Questions (FAQ)
* [http://sdb.open-xchange.com/faq/70 English]
* [http://sdb.open-xchange.com/category/1/71 German]

{{InstallPlugin|pluginname=open-xchange-report-client|sopath=updates}}

{{InstallPlugin|pluginname=open-xchange-report-client|sopath=6.22/updates/backend|version=v6.22.x}}

== Configuration ==

A requirement to execute the Open-Xchange Report Client is to have your Open-Xchange license key stored in one specific file on your Open-Xchange installation. The latest version of our [[Main_Page#Installation_based_on_packages | installation guide]] documentation will automatically enable you to store your license key on disk by using a new oxinstaller command.

If you want to use the report client on an already installed environment you need to store your license key manually on disk. To do so create and edit the following file on your Open-Xchange server:

$ vim /opt/open-xchange/etc/common/licensekeys.properties

or on 6.22 or newer

$ vim /opt/open-xchange/etc/licensekeys.properties

com.openexchange.licensekey.1=PUT_YOUR_OPEN-XCHANGE_LICENSE_KEY_HERE

If you are behind a firewall and the report client needs to be configured using a HTTP proxy, please edit file:

$ vim /opt/open-xchange/etc/groupware/reportclient.properties

or on 6.22 or newer

$ vim /opt/open-xchange/etc/reportclient.properties

After editing this file accordingly to your proxy needs, try to start the report client again.

== Using the Report tool ==

Now as the package has been correctly installed and you provided your license key in the according properties file your are ready to launch the report client to generate a report. By default (if no option is given) the report client will display and send the generated report to an Open-Xchange service on activation.open-xchange.com. Note that only data that is displayed in the console will be transfered to Open-Xchange

'''activation.open-xchange.com:443'''

=== Report kinds ===

In general there are two kinds of reports. Since 7.8.0 the default report has got the appsuite style format. If you would like to generate and display/save/send the formerly used style you have to add the option "-o" to every known parameter combination.

=== Display data usage report ===

$ /opt/open-xchange/sbin/report -d

If you want to know which data would be transfered, execute the report client with the option "-d" (display_only). If this option is given to the report client no data will be send:

=== Send data usage report ===

$ /opt/open-xchange/sbin/report -s

If you don't want to have the report displayed in the console (which might be the case for automated executions of the report client) execute the report client with the option -s (send_only). Now no report will be displayed after the report has been sent to activation.open-xchange.com.

=== Available options ===

$ /opt/open-xchange/sbin/report -h

lists all available options:

Usage: report
-h,--help Prints a help text
--environment Show info about commandline environment
--nonl Remove all newlines (\n) from output
--responsetimeout <responsetimeout> response timeout in seconds for reading response from
the backend (default 0s; infinite)
-H,--host <host> specifies the host
-T,--timeout <timeout> timeout (in s) to conntect to the backend (default 15s)
-J,--jmxauthuser <jmxauthuser> jmx username (when jmx authentication enabled)
-P,--jmxauthpassword <jmxauthpassword> jmx password (when jmx authentication enabled)
-s,--sendonly Send report without displaying it (Disables default)
-d,--displayonly Display report without sending it (Disables default)
-c,--csv Show output as CSV
-a,--advancedreport Run an advanced report
-f,--savereport Save the report as JSON String instead of sending it
-b,--showaccesscombination <showaccesscombination> Show access combination for bitmask
-e,--run-appsuite-report Schedule an appsuite style report
-t,--report-type <report-type> The type of the report to run
--inspect-appsuite-reports Prints information about currently running reports
--cancel-appsuite-reports Cancels pending reports
-g,--get-appsuite-report Retrieve the report that was generated
-x,--run-and-deliver-report Create a new report and send it immediately
-o,--run-and-deliver-old-report Run old report type. Used to have a backward compatibility.

=== Explanation of the appsuite report console output ===

<pre>
$ /opt/open-xchange/sbin/report -d
Starting the Open-Xchange report client. Note that the report generation may take a little while.

f5f511d663ff462f8f963dfa41bd8cd2: 0/5 (0,00 %)
UUID: f5f511d663ff462f8f963dfa41bd8cd2
Type: default
Total time: 389 milliseconds
Avg. time per context: 77 milliseconds
Report was finished: Wed Jul 08 13:42:25 CEST 2015

------ report -------
{
"macdetail" : {
"capabilitySets" : [ {
"total" : 2,
"capabilities" : [ "auto_publish_attachments", "autologin", "caldav", "carddav", "drive", "infostore", "mailfilter", "oauth", "oauth-grants", "pop3", "printing", "publish_mail_attachments", "rss", "search", "twitter", "xing", "xingjson" ],
"quota" : 1073741824,
"admin" : 0,
"disabled" : 0
}, {
"total" : 11,
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "filestore", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],
"quota" : 1073741824,
"admin" : 3,
"disabled" : 0
}, {
"total" : 6,
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],
"quota" : 1073741824,
"admin" : 2,
"disabled" : 0
} ]
},
"total" : {
"guests" : 22,
"links" : 10,
"contexts" : 5,
"users" : 19,
"report-format" : "appsuite-short"
},
"clientlogincountyear" : {
"appsuite" : "7",
"olox2" : "0",
"caldav" : "0",
"usm-eas" : "0",
"mobileapp" : "0",
"ox6" : "9",
"carddav" : "1"
},
"clientlogincount" : {
"appsuite" : "4",
"olox2" : "0",
"caldav" : "0",
"usm-eas" : "0",
"mobileapp" : "0",
"ox6" : "2",
"carddav" : "1"
},
"uuid" : "f5f511d663ff462f8f963dfa41bd8cd2",
"reportType" : "default",
"timestamps" : {
"start" : 1436355744714,
"stop" : 1436355745103
},
"version" : {
"version" : "7.8.0-Rev0",
"buildDate" : "develop"
},
"configs" : {
"com.openexchange.mail.adminMailLoginEnabled" : "true"
}
}
------ end -------
</pre>

'''macdetail:'''
: detailed information about existing module access combinations and its usage
'''total:'''
: accumulated user, guest, link (anonymous share) and context count
'''clientlogincountyear:'''
: number of client logins for the last year
'''clientlogincount:'''
: number of client logins for the last month
'''uuid:'''
: a unique id for the report
'''reportType:'''
: given name for that report (normally 'default')
'''timestamps:'''
: timestamps of the start and end time of the report
'''versions:'''
: version and build date of the server
'''configs:'''
: server configuration (currently only for setting 'com.openexchange.mail.adminMailLoginEnabled')

=== Explanation of the old console output ===

$ /opt/open-xchange/sbin/report -o -d
Starting the Open-Xchange report client. Note that the report generation may take a little while.

module version
admin 6.20.5 Rev1
groupware 6.20.5 Rev1

'''contexts users guests links'''
5 19 22 10

'''mac count adm disabled'''
268435455 6 1 0
237044501 48 0 0
5 2 2 0

'''key value'''
com.openexchange.mail.adminMailLoginEnabled true

'''usmeas olox2 mobileapp carddav caldav'''
1 0 0 0 0

'''usmeasyear olox2year mobileappyear carddavyear caldavyear'''
4 12 7 11 10

'''contexts:'''
:total number of contexts
'''users:'''
:total number of users
'''guests:'''
:total number of guests
'''linkss:'''
:total number of links shared to anonymous users
'''mac:'''
:decimal value of the module access. For conversion decimal to human readable permission please use <tt>report -b</tt> as described below
'''count:'''
:amount of users with this module access
'''adm:'''
:amount of admin users with this specific module access
'''disabled:'''
:amount of users that are disabled
'''key:'''
:key of the configuration property
'''value:'''
:value of the configuration property

The last rows show the amount of users that did login to Open-Xchange within the ''last 30 days'' and ''the last year'' using the specified OXtender/service.

If you want to know the access permissions of a specific <tt>mac</tt>, run e.g.

$ /opt/open-xchange/sbin/report -b 237044501

'''usmeas:'''
:using mobile phone via active sync (OXtender for Business Mobility) within the last 30 days
'''olox2:'''
:using OXtender 2 for Microsoft Outlook within the last 30 days
'''mobileapp:'''
:using Open-Xchange Mobile Web Interface within the last 30 days
'''carddav/caldav:'''
:using the CalDAV/CardDAV feature within the last 30 days
'''usmeasyear:'''
:using mobile phone via active sync (OXtender for Business Mobility) within the last year
'''olox2:'''
:using OXtender 2 for Microsoft Outlook within the last year
'''mobileapp:'''
:using Open-Xchange Mobile Web Interface within the last year
'''carddav/caldav:'''
:using the CalDAV/CardDAV feature within the last year

'''Example:''' a value of 7 below <tt>olox2</tt> means, that within the last 30 days, 7 different users used the OXtender 2 for Microsoft Outlook to connect to Open-Xchange.

== Automatic reports ==

Creating a cron entry which will automatically execute the report client once a week saves a lot of work. To create this cron entry execute:

$ vim /etc/cron.d/open-xchange_report

0 3 * * 7 open-xchange /opt/open-xchange/sbin/report -s -x 1> /dev/null 2>&1

== What will be reported using the send method? ==

The report client will display and / or transfer the following information:

# Version number of the Open-Xchange server package
# Version number of the Open-Xchange admin package
# Total user count
# Total context count
# Detailed context information: context age, creation date or date of creation, user count, context id, capability sets
# Detailed user information (per context): User access combination flags (which modules have been activated for the users)

[[Category: OX6]]

OXReportClient

2016-01-07T13:39:30Z

Usman.ahmad:

AppSuite:GettingStarted 7.6.0

2015-12-08T14:47:50Z

Usman.ahmad:

<div class="title">Getting Started</div>

<div style="float:right; padding: 10px;">[[File:OX_AppSuite_UI_Development_Workflow.png]]</div>

__TOC__

Hello and welcome to the world of OX App Suite development. This document is designed to get you started with developing your first app for OX App Suite as quickly and simply as possible. However, along the way we will also tempt you to learn more by linking to some more in-depth documentation about the various topics we cover.

<div style="clear: both"></div>

== Installing the Development Tools ==

First, you need to install some tools which are necessary for UI development.

TL;DR version:

$ npm install -g grunt-cli bower yo generator-ox-ui-module

Or if needed, there is a complete article about setting up an environment for [[AppSuite:GettingStartedWithGrunt#Node | grunt]].

== Create a Workspace ==

All your app development can take place inside one working directory. The examples will assume you have created a directory named <tt>myapp</tt> inside your home directory:

$ mkdir ~/myapp
$ cd ~/myapp

It doesn't need to be in your home directory, and the actual name should reflect the name of your app. The main point is that all commands will be executed in this directory and all paths will be relative to this directory from now on.

Now, you can generate a grunt configuration using:

$ yo ox-ui-module

The source code of your app will reside in the subfolder named <tt>apps</tt>. To avoid name collisions please pick a unique subfolder inside that. The easiest and recommended way is to use a domain name that you own. Typically, the domain elements are reversed, like in Java. <tt>example.com</tt> becomes <tt>com.example</tt>:

$ mkdir -p apps/com.example

== Writing an App ==

As an example, let's create the smallest possible app and test it. It requires only two files: <tt>apps/com.example/register.js</tt> for the source code of the app:

<pre class="language-javascript">
define('com.example/register', function () {
'use strict';
alert('Hello, World!');
});
</pre>

and <tt>apps/com.example/manifest.json</tt> for the [[AppSuite:UI_manifests_explained | manifest]] which tells the UI that your app exists and what to do with it:

<pre class="language-javascript">{ "namespace": "core" }</pre>

== Building an App ==

The source code of your app can't be used by OX App Suite as it. It first has to be processed by the [[AppSuite:UI_build_system | build system]]. This step will check the source code for syntax errors, compress it, and depending on the structure of your code, many other things. The processed code is then written to a directory named <tt>build</tt> by default. Start the build with this command:

$ grunt

If your editor supports it, you can configure it to call the build system after every file save. Take care to call it from the top directory of your app's workspace, not from the directory of the saved file.

== Testing an App ==

The freshly built code can now be tested. Instead of uploading your code to an OX App Suite server, you can use the [[AppSuite:Appserver|appserver]] proxy to inject your code into the UI code of any existing OX App Suite installation. For example, to start <tt>appserver</tt> using [https://www.ox.io/ www.ox.io] as the server, you will need a local configuration pointing to that server. You can register for a free user account on [https://www.ox.io/ www.ox.io].

You can generate it with this command:

$ grunt show-config:local --output grunt/local.conf.json

To use the remote www.ox.io AppSuite server, open up the file <tt>grunt/local.conf.json</tt> in your editor and add <tt><nowiki>"https://www.ox.io/appsuite/"</nowiki></tt> to the <tt>server</tt> setting of the appserver section. Also make sure that the <tt>protocol</tt> setting is set to <tt>https</tt>. Else you will get https redirect errors in your browser.

INFO: If you are using a locally installed AppSuite server (in a VM or similar in your local network), just modify the server + protocol accordingly.

Then start the development server:

$ grunt dev

This command will serve your app from the local directory <tt>build</tt>, and get everything else from the URL specified in the <tt>server</tt> setting.

Once appserver is running, you can access OX App Suite by opening your browser using this address:

https://localhost:8337/appsuite

After logging in, the app should be loaded and display the <tt>alert</tt> message.

=== Development cycle ===

Once you are sure that your setup works, you can extend the example and write the actual code for your app. The <tt>dev</tt> task will detect any changes and rebuild your app and even reload all browsers connected to
<tt>https://localhost:8337/appsuite</tt>.

While developing always keep in mind, that there is an [[AppSuite:Debugging_the_UI | article about debugging the user interface]] which helps you avoid and fix typical errors.

== Packaging ==

Together with our ox-ui-module generator (from version 0.8.0), we provide you with generators for packaging information.

To enable some grunt tasks to help you, you can optionally install (with npm install) <tt>grunt-contrib-compress</tt> and <tt>grunt-exec</tt>. You will need those to run the grunt tasks described below.

=== Generating a source tarball ===

There is a grunt tasks to create source packages. You can use it to create a tar.gz file containing all sources needed to build the project. This source package should contain all dependencies that are installed during <tt>bower install</tt> and <tt>npm install</tt> (basically containing your <tt>bower_components</tt> and <tt>node_modules</tt> directories). To generate this file, run:

$ grunt dist:source --include-dependencies

This file (can be found in the <tt>dist/</tt> directory) together with the distribution specific packaging information will be needed to build the package.

=== RPM packages ===

In order to generate a spec file for your project, run:

$ yo ox-ui-module:rpm-pkg

Will generate a spec file, with some default values read from your <tt>package.json</tt> file. So you might want to make this file as complete as possible. However, yeoman will ask you about the information missing.

''Please remember, that the generated spec file is only a scaffold for a real one. It will work for very simple cases, but as soon as your package gets more complicated, you will have to adjust it to your needs.''

Once you have the spec file in your project, you can use

$ grunt rpm-build --include-dependencies # or rpm-build if you are on shared-grunt-config-0.6.0

=== DEB packages ===

Creating packages for the Debian distribution works similar to rpm packages. Just run:

$ yo ox-ui-module:deb-pkg

This will generate a debian directory containing all needed files. Some default values will be read from your <tt>package.json</tt> file. So you might want to make this file as complete as possible. However, yeoman will ask you about the information missing.

''Please remember, that the generated spec file is only a scaffold for a real one. It will work for very simple cases, but as soon as your package gets more complicated, you will have to adjust it to your needs.''

Once you have a debian/ directory for your project, you can go on. Now you can run:

$ grunt dpkg-buildpackage --include-dependencies

== i18n ==

To use the proven way to translate your AppSuite application, you should now check out the [[AppSuite:I18n | documentation]] about all [[AppSuite:I18n | i18n]] tasks. Please browse to the [[AppSuite:I18n | i18n]] page.

== Further Reading ==
* Congratulations you have just built your first app for OX App Suite, but please keep in mind that there are [[AppSuite:Developing for the UI#What_can_i_build.3F | quite a few options]] for developing for OX App Suite.
* In case you want to upgrade your existing app for OX App Suite, read [[Appsuite:Upgrade_app_using_yo | the upgrade guide]].
* More information on the build system can be found on github:
** [https://github.com/Open-Xchange-Frontend/shared-grunt-config See all available grunt tasks]
** [https://github.com/Open-Xchange-Frontend/generator-ox-ui-module Documentation of all generator tasks]
* If you're stuck somewhere, the article about [[AppSuite:Debugging_the_UI | debugging the UI]] might help you.
* You can read this to get a better overview of [[AppSuite:Developing for the UI | developing the user inferface]].

[[Category: OX7]]
[[Category: AppSuite]]

Template:OXLoadBalancingClustering Database

2015-08-12T14:18:39Z

Usman.ahmad: /* RHEL 6 systems */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release
yum install socat

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux/SLES Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default_storage_engine=InnoDB
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
# Note that xtraback-v2 is the latest version and is the new default,
# while xtrabackup will also work but will be soon deprecated.
wsrep_sst_method=xtrabackup-v2
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user (we will use the same username and password as we defined in the previous section when setting up wsrep.cnf file) for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-08-12T14:18:16Z

Usman.ahmad: /* RHEL 6 systems */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release
yum install socat

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-56 Percona-XtraDB-Cluster-client-56
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux/SLES Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default_storage_engine=InnoDB
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
# Note that xtraback-v2 is the latest version and is the new default,
# while xtrabackup will also work but will be soon deprecated.
wsrep_sst_method=xtrabackup-v2
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user (we will use the same username and password as we defined in the previous section when setting up wsrep.cnf file) for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

User:Usman.ahmad

2015-08-12T14:14:20Z

Usman.ahmad: Undo revision 20208 by Usman.ahmad (talk)

test

User:Usman.ahmad

2015-08-12T14:13:38Z

Usman.ahmad:

test

test2

ewerw3
r

User:Usman.ahmad

2015-08-12T14:13:27Z

Usman.ahmad: Created page with "test"

test

Template:OXLoadBalancingClustering Database

2015-08-12T09:04:16Z

Usman.ahmad: /* RHEL 6 systems */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6 and CentOS 7.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release
yum install socat

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/redhat/0.1-3/percona-release-0.1-3.noarch.rpm
yum localinstall percona-release-0.1-3.noarch.rpm

For those who are using CentOS 7, the localinstall option is not longer available. Therefore do the following:

yum install http://www.percona.com/downloads/percona-release/redhat/0.1-3/percona-release-0.1-3.noarch.rpm

Then run the following commands regardless of the O.S. you are using.

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-56 Percona-XtraDB-Cluster-client-56
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux/SLES Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default_storage_engine=InnoDB
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
# Note that xtraback-v2 is the latest version and is the new default,
# while xtrabackup will also work but will be soon deprecated.
wsrep_sst_method=xtrabackup-v2
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user (we will use the same username and password as we defined in the previous section when setting up wsrep.cnf file) for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-08-12T09:03:12Z

Usman.ahmad: /* RHEL 6 systems */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6 and CentOS 7.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release
yum install socat

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/redhat/0.1-3/percona-release-0.1-3.noarch.rpm
yum localinstall percona-release-0.1-3.noarch.rpm

For those who are using CentOS 7, the localinstall option is not longer available. Therefore do the following:

yum install http://www.percona.com/downloads/percona-release/redhat/0.1-3/percona-release-0.1-3.noarch.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-56 Percona-XtraDB-Cluster-client-56
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux/SLES Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default_storage_engine=InnoDB
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
# Note that xtraback-v2 is the latest version and is the new default,
# while xtrabackup will also work but will be soon deprecated.
wsrep_sst_method=xtrabackup-v2
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user (we will use the same username and password as we defined in the previous section when setting up wsrep.cnf file) for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-08-12T09:02:05Z

Usman.ahmad: /* RHEL 6 systems */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6 and CentOS 7.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release
yum install socat

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/redhat/0.1-3/percona-release-0.1-3.noarch.rpm
yum localinstall percona-release-0.1-3.noarch.rpm

For those who are using CentOS 7, the localinstall option is not longer available. Therefore do the following:

yum install http://www.percona.com/downloads/percona-release/redhat/0.1-3/percona-release-0.1-3.noarch.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-56 Percona-XtraDB-Cluster-client-56
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux/SLES Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default_storage_engine=InnoDB
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
# Note that xtraback-v2 is the latest version and is the new default,
# while xtrabackup will also work but will be soon deprecated.
wsrep_sst_method=xtrabackup-v2
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user (we will use the same username and password as we defined in the previous section when setting up wsrep.cnf file) for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-08-12T09:01:40Z

Usman.ahmad: /* RHEL 6 systems */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6 and CentOS 7.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release
yum install socat

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/redhat/0.1-3/percona-release-0.1-3.noarch.rpm
yum localinstall percona-release-0.1-3.noarch.rpm

For those who are using CentOS 7, the localinstall option is not longer available. Therefore do the following:

yum install http://www.percona.com/downloads/percona-release/redhat/0.1-3/percona-release-0.1-3.noarch.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-56 Percona-XtraDB-Cluster-client-56
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux/SLES Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default_storage_engine=InnoDB
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
# Note that xtraback-v2 is the latest version and is the new default,
# while xtrabackup will also work but will be soon deprecated.
wsrep_sst_method=xtrabackup-v2
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user (we will use the same username and password as we defined in the previous section when setting up wsrep.cnf file) for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-08-12T08:43:28Z

Usman.ahmad: /* RHEL 6 systems */

Template:OXLoadBalancingClustering Database

2015-07-20T08:23:45Z

Usman.ahmad: /* Configuration */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux/SLES Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default_storage_engine=InnoDB
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
# Note that xtraback-v2 is the latest version and is the new default,
# while xtrabackup will also work but will be soon deprecated.
wsrep_sst_method=xtrabackup-v2
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user (we will use the same username and password as we defined in the previous section when setting up wsrep.cnf file) for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-06-25T12:53:00Z

Usman.ahmad:

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux/SLES Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default_storage_engine=InnoDB
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user (we will use the same username and password as we defined in the previous section when setting up wsrep.cnf file) for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-06-25T09:28:21Z

Usman.ahmad: /* Installation */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Pre-requisite for RPM based distributions ===

For RPM-based distributions, such as (RHEL, CentOS, Suse) if you have an existing MySQL or related database server and Postfix installed on your system, you need to remove Postfix before you can install Galera Cluster.

When you install Galera Cluster over an existing MySQL installation, yum removes the existing database server package and replaces it with a new one that was built using the wsrep API patch. However, Postfix registers the database server package as a dependency. Meaning that, if you try to install the mysql-wsrep-server package from Codership without removing Postfix, yum fails since Postfix’s dependency on MySQL-server blocks the installation.

To remove Postfix, run the following command:

yum remove postfix

This removes Postfix from your system. If you still want to use Postfix, you can reinstall it after you finish installing Galera Cluster.

yum install postfix

Postfix now uses Galera Cluster as its database server backend.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux/SLES Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default_storage_engine=InnoDB
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user (we will use the same username and password as we defined in the previous section when setting up wsrep.cnf file) for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

My.cnf

2015-04-13T09:28:31Z

Usman.ahmad:

== Introduction ==

This page lists some parameters (MySQL 5.1) which might be worth to adjust on a MySQL instance running the Open-Xchange databases.

This is NOT a reference configuration but shows some possible settings. Please check the MySQL documentation for your version to understand the settings and test local changes carefully.

=== Configuration items ===

* You should adjust the <code>innodb_buffer_pool_size</code> parameter for better memory usage. This is where all the memory of large DB machines should go. For example, on a 32 GB RAM machine, this can go up to 24 GB.

* On bigger installations you should use <code>innodb_file_per_table = 1</code>, which is creating single files instead of one big blob. If you change this parameter after the database initialization you have to recreate (like dump/drop and re-import) the tables.

* Some benchmarks indicate that actually switching off the query cache helps performance. You may want to experiment with this. To switch it off, use <code>query_cache_size=0</code>, <code>query_cache_type=0</code>.

* It can help to put different parts of the mysql datadir (iblog, ibdata) on different filesystems / storage devices. This depends on your infrastructure. Settings herefore are <code>datadir</code>, <code>innodb_data_home_dir</code>, <code>innodb_log_group_home_dir</code>.

* If your storage is fast, thus it can handle a lot of IOPS, you may want to adjust the <code>innodb_io_capacity</code> setting, which defines a limit for the IOPS MySQL will create. The default is 200, which is sensible for single spindle disks. But if you have storage appliances with a lot of fast SAS drives, or even SSDs, this limit can be increased greatly.

=== Sample my.cnf file ===

This file does not contain all the configuration items discussed in the previous section. Use this as a starting point and adjust it, particularly considering the configuration items discussed in the previous section.

#
[client]
port = 3306
socket = /var/run/mysqld/mysqld.sock

[mysqld]
socket = /var/run/mysqld/mysqld.sock
port = 3306
user = mysql
# applies only when running as root
#memlock = 1

table_open_cache = 3072
table_definition_cache = 4096
max_heap_table_size = 64M
tmp_table_size = 64M
max_connections = 505
max_user_connections = 500
max_allowed_packet = 16M
thread_cache_size = 32
query_cache_size = 64M

# InnoDB
default_table_type = InnoDB

# 80% of ram that is dedicated for the database (this needs to be adjusted to your system)
innodb_buffer_pool_size = 14G
# number of CPU cores dedicated to the MySQL InnoDB backend
innodb_buffer_pool_instances = 16

innodb_data_file_path = ibdata1:128M:autoextend
innodb_file_per_table = 1
innodb_log_file_size = 512M
innodb_log_files_in_group = 2

# MyISAM
myisam_recover = backup,force

# Logging
log_warnings = 2
log_error = /var/log/mysql/error.log

slow_query_log = 1
slow_query_log_file = /var/log/mysql/mysql-slow.log
long_query_time = 1
log_queries_not_using_indexes = 0
min_examined_row_limit = 20

# Binary Log / Replication
server_id = 1
log-bin = mysql-bin
binlog_cache_size = 1M
sync_binlog = 8
binlog_format = row
expire_logs_days = 7
max_binlog_size = 128M
relay-log = /var/log/mysql/slave-relay.log
relay-log-index = /var/log/mysql/slave-relay-log.index

[mysqldump]
quick
single-transaction
max_allowed_packet = 16M

[mysql]
no_auto_rehash

[myisamchk]
key_buffer = 512M
sort_buffer_size = 512M
read_buffer = 8M
write_buffer = 8M

[mysqld_safe]
open-files-limit = 8192
log-error = /var/log/mysql/error.log

=== Note for MySQL version 5.5 or higher ===

A small change for the above sample configuration file needed when using MySQL ver. 5.5.x or higher, e.g. used by Percona XtraDB Cluster / Galera.

Replace:

default_table_type = InnoDB

With

default_storage_engine = InnoDB

Template:OXLoadBalancingClustering Database

2015-04-10T14:43:45Z

Usman.ahmad: /* my.cnf configuration file */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux/SLES Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default-storage-engine=innodb
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user (we will use the same username and password as we defined in the previous section when setting up wsrep.cnf file) for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-04-10T14:39:46Z

Usman.ahmad: /* Cluster startup */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default-storage-engine=innodb
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user (we will use the same username and password as we defined in the previous section when setting up wsrep.cnf file) for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-04-10T14:39:32Z

Usman.ahmad: /* Cluster startup */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default-storage-engine=innodb
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user (we will use the same username and password as we defined in the previous section when setting up wsrep.cnf file)for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-04-10T14:32:29Z

Usman.ahmad: /* RHEL 6 systems */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

Once this is all done, don't forget to run the update command to get the latest Percona packages.

yum update

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default-storage-engine=innodb
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-04-10T14:27:44Z

Usman.ahmad: /* wsrep.cnf configuration file */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''''/etc/mysql/conf.d/wsrep.cnf''''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default-storage-engine=innodb
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-04-10T14:27:17Z

Usman.ahmad: /* wsrep.cnf configuration file */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample '''/etc/mysql/conf.d/wsrep.cnf''' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default-storage-engine=innodb
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-04-10T14:26:53Z

Usman.ahmad: /* my.cnf configuration file */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''!includedir /etc/mysql/conf.d''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

'''Caveat''': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample ''/etc/mysql/conf.d/wsrep.cnf'' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default-storage-engine=innodb
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-04-10T14:26:19Z

Usman.ahmad: /* my.cnf configuration file */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like '''''!includedir /etc/mysql/conf.d''''', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

''Caveat'': we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample ''/etc/mysql/conf.d/wsrep.cnf'' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default-storage-engine=innodb
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-04-10T14:25:15Z

Usman.ahmad: /* my.cnf configuration file */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a '''my.cnf''' configuration file. Usually MySQL expects this file to be located at '''''/etc/mysql/my.cnf'''''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Default location for my.cnf file based on different Linux Distros.

* If you are using Debian Linux file is located at /etc/mysql/my.cnf location
* If you are using Red Hat Linux/Centos Linux file is located at /etc/my.cnf location

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like ''!includedir /etc/mysql/conf.d'', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

Caveat: we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample ''/etc/mysql/conf.d/wsrep.cnf'' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default-storage-engine=innodb
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-04-10T14:20:56Z

Usman.ahmad: /* RHEL 6 systems */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on '''''socat''''' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a ''my.cnf'' configuration file. Usually MySQL expects this file to be located at ''/etc/mysql/my.cnf''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like ''!includedir /etc/mysql/conf.d'', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

Caveat: we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample ''/etc/mysql/conf.d/wsrep.cnf'' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default-storage-engine=innodb
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-04-10T14:20:25Z

Usman.ahmad: /* RHEL 6 systems */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on ''socat'' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

yum install epel-release

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a ''my.cnf'' configuration file. Usually MySQL expects this file to be located at ''/etc/mysql/my.cnf''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like ''!includedir /etc/mysql/conf.d'', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

Caveat: we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample ''/etc/mysql/conf.d/wsrep.cnf'' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default-storage-engine=innodb
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

Template:OXLoadBalancingClustering Database

2015-04-10T14:18:31Z

Usman.ahmad: /* RHEL 6 systems */

== Overview ==

You can choose between Galera or two-sided Master/Slave ("Master/Master") replication.

== Galera database setup ==

OX only supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been adjusted to work with Wheezy, but works similar with Squeeze, only the repo paths need adjustments.

To install the software, we first need to configure the repository and its build key, update our sources lists and install the packages:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A
gpg -a --export CD2EFD2A | apt-key add -

cat >/etc/apt/sources.list.d/percona.list <<EOF
deb http://repo.percona.com/apt wheezy main
deb-src http://repo.percona.com/apt wheezy main
EOF

apt-get update
apt-get install percona-xtradb-cluster-client-5.5 percona-xtradb-cluster-server-5.5 percona-xtrabackup

==== RHEL 6 systems ====

Should also apply to CentOS 6.

First, disable '''''selinux, iptables, ip6tables'''''. (Galera does not run with selinux. Using iptables and ip6tables should work if you configure it correctly, but documentation thereof is out of scope of this document.) Reboot.

Percona XtraDB Cluster relies on ''socat'' which is not shipped by RHEL. We need to install from a different source. The ''epel'' repository can be used for that.

The installation command itself needs to be a composite ''remove'', ''install'' command since yum is not clever enough to resolve the conflicts itself, so we need to tell it how.

wget http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
yum localinstall percona-release-0.0-1.x86_64.rpm

yum shell
remove mysql-libs
install Percona-XtraDB-Cluster-server-55 Percona-XtraDB-Cluster-client-55
run
quit

=== Configuration ===

==== ''my.cnf'' configuration file ====

Galera needs also a ''my.cnf'' configuration file. Usually MySQL expects this file to be located at ''/etc/mysql/my.cnf''. But the Percona packages don't ship any; on purpose: https://bugs.launchpad.net/percona-server/+bug/673844

Thus, you need to obtain / install / create one on your own. Make sure it has no settings which are forbidden for Galera. This includes the ''query_cache'' (it must not be enabled with Galera) and probably other settings which would contradict the settings explained in the next section.

Make sure you apply standard tunings for your memory size, number of allowed connections, and stuff.

We assume in the following that the ''my.cnf'' file has a directive like ''!includedir /etc/mysql/conf.d'', such that you can put additional config files ending with ''.cnf'' there.

A sample ''my.cnf'' file serving as a starting point is provided here: [[My.cnf]]. Make sure you read the whole article and adjust that file to suit your needs before actually using it.

Caveat: we found out that Galera performs suboptimal when using ''innodb_flush_log_at_trx_commit=1''. We leave up to you to assess whether this is a no-go for your environment or not. For Galera reasonable values for this parameter are ''innodb_flush_log_at_trx_commit=2'' or ''...=0''. Make sure to read the documentataion of this parameter and that you understand its implication before using it.

Furthermore, you need to set the "datadir" configurable in the ''my.cnf'' file, even if you are on the default and do not want to change it. Some SST methods depend the setting being explicitly present in the configuration file.

==== ''wsrep.cnf'' configuration file ====

The Galera configuration then happens in a section called "wsrep", "write set replication", which is the internal name for the replication mechanism Galera is based on. A sample ''/etc/mysql/conf.d/wsrep.cnf'' file looks like:

[mysqld]
# the following lines are required for galera:
binlog_format=ROW
default-storage-engine=innodb
innodb_autoinc_lock_mode=2
innodb_locks_unsafe_for_binlog=1
query_cache_size=0
query_cache_type=0
bind-address=0.0.0.0
wsrep_provider=/usr/lib64/libgalera_smm.so
# NOTE: on Wheezy, use this path:
# wsrep_provider=/usr/lib/libgalera_smm.so
# the following lines need to be adjusted to your environment ... CHANGE THE PASSWORD! :-)
wsrep_cluster_name="my_wsrep_cluster"
wsrep_cluster_address="gcomm://<GALERA_NODE1_IP>,<GALERA_NODE2_IP>,<GALERA_NODE3_IP>"
wsrep_sst_method=xtrabackup
wsrep_sst_auth=wsrep:5ojijmedUg8
# It is recommended to run Galera in synchronous mode, which makes it possible
# to disable the OX builtin database replication monitor.
# Default is semi-synchronous mode. To enable synchronous mode, use
wsrep_causal_reads=1

When you adjusted those files, make sure they are identical on all nodes.

The replication user will be created later when the DB is running on the first node.

=== Cluster startup ===

Whenever not all nodes of a Galera cluster are running (like before starting the cluster for the very first time), the first Galera node needs to get started with the ''wsrep_cluster_address'' parameter overridden to the value "gcomm://" in order to denote that the node shall not try to join an existing cluster (which would inevitably fail now, because no other cluster nodes are running yet), but to bootstrap the cluster instead. This override can most conveniently done on the command line, instead of editing to wsrep.cnf file to and fro.

So, for the first node, the startup command is

mysqld_safe --wsrep_cluster_address=gcomm:// &

You should then verify the Galera module is loaded properly using

mysql -e "show status like 'wsrep%';"

You should verify some settings like

| wsrep_local_state_comment | Synced |
| wsrep_cluster_size | 1 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_provider_name | Galera |
| wsrep_provider_vendor | Codership Oy <info@codership.com> |
| wsrep_provider_version | 2.8(r162) |
| wsrep_ready | ON |

Now you need to create the database user for the replication on this first node:

# create wsrep user: in mysql shell:
CREATE USER 'wsrep'@'localhost' IDENTIFIED BY '5ojijmedUg8';
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'wsrep'@'localhost';
FLUSH PRIVILEGES;

The Galera peers can then be started on the nodes 2 and 3 using

mysqld_safe &

Since the standard service startup scripts cannot account for this special treatment, we recomment not to use them.

You can check the status of the Galera cluster using

mysql -e "show status like 'wsrep%';"

The output is lengthy. The most relevant fields are given as follows:

+----------------------------+----------------------------------------------------------------------+
| Variable_name | Value |
+----------------------------+----------------------------------------------------------------------+
| wsrep_local_state_comment | Synced |
| wsrep_incoming_addresses | <GALERA_NODE1_IP>:3306,<GALERA_NODE2_IP>:3306,<GALERA_NODE3_IP>:3306 |
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_connected | ON |
| wsrep_ready | ON |
+----------------------------+----------------------------------------------------------------------+

==== Troubleshooting ====

The logs are helpful. Always.

Common mistakes are listed below.

If the Galera module does not get loaded at all:
* Configuration settings in ''my.cnf'' which are incompatible to Galera
* Wrong path of the shared object providing the Galera plugin in wsrep.cnf (wsrep_provider)

If the first node starts, but the second / third nodes can not be added to the cluster:
* User for the replication not created correctly on the first Galera node

=== Notes about configuring OX for use with Galera ===

==== Write requests ====

Open-Xchange supports Galera as database backend only in the configuration where all writes are directed to one Galera node. For availability, it makes sense to configure a floating IP as write IP for OX, which can be transferred from one Galera to another Galera node if needed. We recommend putting the control of such a floating IP under the control of some HA cluster software like pacemaker/corosync.

==== Read requests ====

You can chose between using a load balancer, using a floating IP for the read requests, or use the write requests floating IP.

* Load balancer based setup: Read requests get distributed aribtrarily between the Galera nodes. You require a load balancer for this. See next section. Then, in this configuration, you have two alternatives:
** The Galera option wsrep_causal_reads=1 option enables you to configure OX with its replication monitor disabled (com.openexchange.database.replicationMonitor=false in configdb.properties).
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This setup however seems to be inferior from the performance point of view.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. Since read requests do not seem to be performance-limiting, we expect to perform this option on par with the loadbalancer option.
* Use the floating IP for the writes also for the reads: In this scenario, you direct all database queries only to one Galera node, and the other two nodes are only getting queries in case of a failure of that node. In this case, you can even use wsrep_causal_reads=0 wile still having OX builtin replication monitor switched off.

=== Loadbalancer options ===

While the JDBC driver has some round-robin load balancing capabilities built-in, we don't recommend it for production use since it lacks possibilities to check the Galera nodes health states.

For most productions setup customers use enterprise-grade loadbalancing appliances. Those should get configured to check node availability not only on the TCP level, but to query the Galera sync status periodically. For an example of such an health check, see the our documentation for setting up a software loadbalancer using keepalived (next paragraph).

It is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|here]]. This implements the round-robin part for the read requests. For the single-node write behavior, we recommend to use a floating IP then.

In case where the Keepalived based approach is not feasible due to its requirements on the infrastructure, it is also possible to use a HAproxy based solution where HAproxy processes run on each of the OX nodes, configured for one round-robin and one active/passive instance. OX is then connecting to the local HAproxy instances. It is vital to configure HAproxy timeouts different from the defaults, otherwise HAproxy will kill active DB connections, causing errors. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Master database setup ==
This section describes the setup process "Master/Master replication" for new Open-Xchange database cluster. During configuration and initialization, other database operations must be prohibited.

The Master/Master replication is a vice versa setup of Master/Slave configurations. This means each server is afterwards the slave of the other.

Server IPs in the example are 1.1.1.1 and 9.9.9.9

Startup both database machines and install the mysql server packages
$ apt-get install mysql-server

During the installation, a dialog will show up to set a password for the MySQL 'root' user.

Open the MySQL configuration file on both servers:
$ vim /etc/mysql/my.cnf

Modify or enable the following configuration options in the mysqld-section, use 1 as ${unique Number} on the server 1.1.1.1 and 2 for 9.9.9.9:
bind-address = 0.0.0.0
server-id = ${unique Number}
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = statement
max_allowed_packet = 16M

* ''bindaddress'' specifies the network address where MySQL is listening for network connections. Since the MySQL slave and both Open-Xchange Servers are dedicated machines it is required to have the master accessible through the network.
* ''server-id'' is just a unique number within a environment with multiple MySQL servers. It needs to be unique for each server in a replication cluster.
* ''log-bin'' enables the MySQL binary log which is required for Master/Master replication. In general every statement triggered at the database is stored there to get distributed through the database cluster.

To apply the configuration changes, restart the MySQL servers.
$ /etc/init.d/mysql restart

Then login to MySQL with the credentials given at the MySQL installation process
$ mysql -u root -p
Enter password:

=== First Master configuration ===
Choose one server to start with as the first Master (here we use 1.1.1.1).

Create a MySQL user with rights "REPLICATION". This account is used by the MySQL slave to fetch database updates. In this example, the username is "replication":

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'9.9.9.9' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and note the log Position and File name:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000001 | 1111 | | |
+------------------+----------+--------------+------------------+

=== First Slave configuration ===

On 9.9.9.9, set the MySQL system user as owner of the binary log that has just been copied to the slave.
$ chown mysql:adm /var/log/mysql/*

Configure MySQL on 9.9.9.9 to use 1.1.1.1 as Master Server. (Use the actual log File name and Position which you just obtained with the command SHOW MASTER STATUS on 1.1.1.1. as explained above.)
mysql> CHANGE MASTER TO MASTER_HOST='1.1.1.1', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=1111;

Start the MySQL slave replication
mysql> START SLAVE;

And check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

=== Second Master configuration ===

This means, the first Master/Slave Replication is working and the "reverse" replication needs to be prepared. Please now create the replication user on 9.9.9.9:

mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'1.1.1.1' IDENTIFIED BY 'secret';

Verify that the MySQL daemon writes a binary log and remember the log Position:
mysql> SHOW MASTER STATUS;
+------------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000009 | 9999| | |
+------------------+----------+--------------+------------------+

=== Second Slave configuration ===

1.1.1.1 is now the slave in this context and 9.9.9.9 is the master. Log in to 1.1.1.1

Configure MySQL on 1.1.1.1 to use 9.9.9.9 as Master Server. Use the remembered log and file position from 1.1.1.1.
mysql> CHANGE MASTER TO MASTER_HOST='9.9.9.9', MASTER_USER='replication', MASTER_PASSWORD='secret', MASTER_LOG_FILE='mysql-bin.000009', MASTER_LOG_POS=9999;

start the MySQL slave replication
mysql> START SLAVE;

and check the status
mysql> SHOW SLAVE STATUS\G;

"Slave_IO_Running" and "Slave_SQL_Running" should be set to "yes". Furthermore "Read_Master_Log_Pos" should be counting and "Seconds_Behind_Master" should be approaching the 0 mark.

Also check the syslog if the replication has been sucessfully started
$ tail -fn20 /var/log/syslog
Jul 26 19:03:45 dbslave mysqld[4718]: 090726 19:03:45 [Note] Slave I/O thread: connected to master 'replication@1.1.1.17:3306', replication started in log 'mysql-bin.000001' at position 10000

=== Testing Master/Master ===

On 1.1.1.1, create a new database in MySQL:
mysql> CREATE DATABASE foo;

Verify the database to als be available on 9.9.9.9 afterwards:
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| foo |
| mysql |
+--------------------+

Delete the new database on 9.9.9.9:
mysql> DROP DATABASE foo;

Check if the database has also been removed on 1.1.1.1
mysql> SHOW DATABASES;
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
+--------------------+

== Creating Open-Xchange user ==

Now setup access for the Open-Xchange Server database user 'openexchange' to configdb and the oxdb for both groupware server addresses. These databases do not exist yet, but will be created during the Open-Xchange Server installation.

Note: The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'secret';
mysql> GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'secret';

AppSuite:OX System Requirements

2015-04-10T14:14:10Z

Usman.ahmad: /* Installation-, Hardware-, Software-Requirements */

= OX App Suite Requirements - Open-Xchange supported components overview =

The following table provides an overview about the supported components at the OX User Front-End, Connector for Microsoft Outlook and Connector for Business Mobility. This overview makes no claim to be complete.

Open-Xchange Server 6 overview tables about the supported components at the OX User Front-End, Connector for Microsoft Outlook and Connector for Business Mobility are available at [[OX_System_Requirements|OX 6 Requirements - Open-Xchange supported components overview]]

Information about Maintenance expiries of components, versions and browser support, can be found in the [[AppSuite:Versioning_and_Numbering#Maintenance_expires|Maintenance Expires Table]]

== Installation-, Hardware-, Software-Requirements ==

Please note: Installation and administration of the OX App Suite requires basic knowledge of E-Mail systems under Linux, Apache and MySQL as well as experience in the command line administration of Linux systems.

'''OX App Suite:'''
* Memory 8 GB - 12 GB <br> '''Please Note: If you want to install OX in a VM memory needs to be allocated exclusively to that installation (and not shared with other VM's). This also applies to the database and other related systems or components.'''
* Disk 500 MB plus User Data
* Supported Platform Architecture: 64 bit Operation Systems (x84_64)
* Supported IMAP Server: Cyrus or Courier or Dovecot or UW IMAP (To some extent)

== Desktop Browser (Minimum display resolution: 1024 x 768)==

{|border="2" rules="all" align="left">
|'''Browser'''
|'''OX App Suite User Front-End'''
|-
| 
| 
|-
|Microsoft Internet Explorer 10/11
|v7.6.1; v7.6.2
|-
|Mozilla Firefox (latest & previous version)
|v7.6.1; v7.6.2
|-
|Google Chrome (latest & previous version)
|v7.6.1; v7.6.2
|-
|Apple Safari (latest version & previous version. Mac OS X only)
|v7.6.1; v7.6.2
|-
|}

== Mobile Device Support==

{|border="2" rules="all" align="left">
|'''Mobile Device'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|iPhone on iOS 7 / iOS 8
|Safari
|v7.6.1; v7.6.2
|3G connections (512/256kBit/s, 350ms latency)
|-
|Smartphone on Android 4.1 or later
|Chrome (latest & previous version)
|v7.6.1; v7.6.2
|3G connections (512/256kBit/s, 350ms latency)
|}

== Tablet Support==

{|border="2" rules="all" align="left">
|'''Tablet'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|Apple iPad (all devices) on iOS 7 / iOS 8
|Safari
|v7.6.1; v7.6.2
|3G connections (512/256kBit/s, 350ms latency)
|-
|Tablets on Android 4.1 or later
|Chrome (latest & previous version)
|v7.6.1; v7.6.2
|3G connections (512/256kBit/s, 350ms latency)
|}

== MS Windows / MS Outlook® / OX Notifier / OX Updater ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|[http://oxpedia.org/wiki/index.php?title=AppSuite:Connector_for_Microsoft_Outlook '''Connector 2 for Microsoft Outlook''']
|[http://oxpedia.org/wiki/index.php?title=Open-Xchange_Installation_Guide_for_OX_Notifier '''OX Notifier v1.0.0''']
|'''OX Updater'''
|-
| 
| 
| 
| 
|-
|OX App Suite
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Client PC operating system
|Latest versions of Windows 7, latest versions of Windows 8 (no support of Mac OS X clients with emulators and Windows RT)
|Latest Versions of Windows 7 (each with 32 + 64 bit) (no support of Mac OS X clients with emulators), latest versions of Windows 8 (no support of start screen tiles)
|Latest Versions of Windows 7 (each with 32 + 64 bit) (no support of Mac OS X clients with emulators), latest versions of Windows 8 (no support of start screen tiles)
|-
|Supported Outlook versions
|Latest Versions of Microsoft Outlook 2007, Outlook 2010, Outlook 2013 (no support of "Office 2010 Click-to-Run", "Office Home and Business 2010 Testversion")
| 
| 
|-
|}

== Calendar/Contact synchronization Apple Mac OS X ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|Mac OS X 10.9 (Mavericks)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Mac OS X 10.10 (Yosemite)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Calendar/Contact synchronization Apple iOS ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|Apple iOS 7
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Apple iOS 8
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Mobility Solution - Supported- Platforms, Features and Devices ==

{|border="2" rules="all" align="left">
|'''Feature/Technology/Device'''
|[http://oxpedia.org/wiki/index.php?title=OXtender_for_Business_Mobility '''OXtender for Business Mobility'''] (availalble for App Suite, OXHE, OXSE)
|[http://oxpedia.org/wiki/index.php?title=OX_Mobile_Web_Interface '''Open-Xchange Mobile Web Interface'''] (availalble for AppSuite, OXHE, OXSE)<br>The web interface is optimized for a display size of 320 x 480 pixels. Smaller resolutions may result displaying issues of some UI elements.
|-
| 
| 
| 
|-
|Exchange Active Sync 2.5
|[[File:check.gif]]
|[[File:cross.gif]]
|-
|Exchange Active Sync 12.1
|[[File:check.gif]]
|[[File:cross.gif]]
|-
| 
| 
| 
|-
|Access and creation of emails
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Personal PIM folder
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Public and Shared PIM folder
|[[File:cross.gif]]
|[[File:cross.gif]]
|-
|Global address book
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Push E-Mail
|[[File:check.gif]]
|[[File:cross.gif]]
|-
| 
| 
| 
|-
|Windows Phone 7, Windows Phone 8 (latest & previous minor versions)
|[[File:check.gif]]
|[[File:cross.gif]]
|-
|iPhone iOS 7, iOS 8 (latest & previous minor versions)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|HTC Devices
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Android 2.3 or later
|[[File:check.gif]]
|[[File:check.gif]]
|-

|}

== OX Drive for Clients ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform'''
|'''Tested Devices'''
|-
| 
| 
| 
|-
|OX App Suite
|OX App Suite v7.6.1; v7.6.2
| 
|-
|Supported Platforms
|Debian GNU/Linux 6.0 (Squeeze), Debian GNU/Linux 7.0 (Wheezy), SUSE Linux Enterprise Server 11, RedHat Enterprise Linux 6, CentOS 6<br>Univention Corporate Server (planned for Q4)
| 
|-
|OX Drive for Windows
|Latest Versions of Windows 7, Windows 8 (no support of Mac OS X clients with emulators and Windows RT)
| 
|-
|OX Drive for Mac OS
|Mac OS X 10.9 (Mavericks), Mac OS X 10.10 (Yosemite)
| 
|-
|OX Drive for iOS
|Apple Apple iOS 7, Apple iOS 8
|Apple iPhone 5, Apple iPhone 5s
|-
|OX Drive for Android
|Smartphone on Android 4.1 or later with Chrome (latest & previous version), Tablets on Android 4.1 or later with Chrome (latest & previous version)
|Samsung Galaxy S3 mini, Samsung Galaxy S4, Nexus 4
|-
|}

== OX Guard ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.6.1; v7.6.2
|-
|Desktop Browser (Minimum display resolution: 1024 x 768)
|Microsoft Internet Explorer 10/11<br>Mozilla Firefox (latest & previous version)<br>Google Chrome (latest & previous version)<br>Apple Safari (latest version & previous version. Mac OS X only)
|-
|Mobile Device and Tablet Support
|Apple iPhone on iOS 7 / iOS 8: Safari (latest version & previous version)<br>Smartphone on Android 4.1 or later: Chrome (latest & previous version)<br>Apple iPad (all devices) on iOS 7 / iOS 8: Safari Safari (latest version & previous version)<br>Tablets on Android 4.1 or later: Chrome (latest & previous version)
|-
|Server Platforms
|Suse Linux Enterprise Server (SLES 11)<br>Red Hat Enterprise Linux 6 (RHEL6)<br>Debian 7<br>CentOS 6<br>Univention Corporate Server
|-
|}

== OX Messenger ==

=== Desktop Browser Support (Chat 1-1 & Group) ===

{|border="2" rules="all" align="left">
|'''Chat 1-1 & Group'''
|Microsoft IE 10
|Microsoft IE 11
|Google Chrome (latest & previous version)
|Mozilla Firefox (latest & previous version)
|Apple Safari (latest version & previous version. Mac OS X only)
|PSTN
|-
| 
| 
| 
| 
| 
| 
| 
|-
|Microsoft IE 10
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Microsoft IE 11
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Google Chrome (latest & previous version)
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Mozilla Firefox (latest & previous version)
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Apple Safari (latest version & previous version. Mac OS X only)
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

=== Desktop Browser Support (Audio/Video) ===

{|border="2" rules="all" align="left">
|'''Audio 1-1'''
|Microsoft IE 10
|Microsoft IE 11
|Google Chrome (latest & previous version)
|Mozilla Firefox (latest & previous version)
|Apple Safari (latest version & previous version. Mac OS X only)
|PSTN
|-
| 
| 
| 
| 
| 
| 
| 
|-
|Microsoft IE 10
|[[File:cross.gif]]
|[[File:cross.gif]]
|[[File:cross.gif]]
|[[File:cross.gif]]
|[[File:cross.gif]]
|[[File:cross.gif]]
|-
|Microsoft IE 11
|[[File:cross.gif]]
|[[File:check.gif]](but stream ID's aren't correct (FMS!))
|[[File:check.gif]](but stream ID's aren't correct (FMS!))
|[[File:check.gif]](but stream ID's aren't correct (FMS!))
|[[File:check.gif]](but stream ID's aren't correct (FMS!))
|[[File:check.gif]]
|-
|Google Chrome (latest & previous version)
|[[File:cross.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Mozilla Firefox (latest & previous version)
|[[File:cross.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Apple Safari (latest version & previous version. Mac OS X only)
|[[File:cross.gif]]
|[[File:check.gif]](but stream ID's aren't correct (FMS!))
|[[File:check.gif]](but stream ID's aren't correct (FMS!))
|[[File:check.gif]](but stream ID's aren't correct (FMS!))
|[[File:check.gif]](but stream ID's aren't correct (FMS!))
|[[File:check.gif]]
|-
|}

<br>

{|border="2" rules="all" align="left">
|'''Video 1-1'''
|Microsoft IE 10
|Microsoft IE 11
|Google Chrome (latest & previous version)
|Mozilla Firefox (latest & previous version)
|Apple Safari (latest version & previous version. Mac OS X only)
|-
| 
| 
| 
| 
| 
| 
|-
|Microsoft IE 10
|[[File:cross.gif]]
|[[File:cross.gif]]
|[[File:cross.gif]]
|[[File:cross.gif]]
|[[File:cross.gif]]
|-
|Microsoft IE 11
|[[File:cross.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Google Chrome (latest & previous version)
|[[File:cross.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Mozilla Firefox (latest & previous version)
|[[File:cross.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Apple Safari (latest version & previous version. Mac OS X only)
|[[File:cross.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

=== Additional Requirements ===

* XMPP Server
* OS: Debian “Wheezy” 7.3
* JVM: Oracle JVM
* JBoss AS
* Mobiscents (JAIN SLEE)
* DB: MYSQL

== Server Platforms ==

{|border="2" rules="all" align="left">
|'''Platforms'''
|'''OX App Suite'''
|'''Supported Java Versions'''
|'''Supported MySQL Versions'''
|-
| 
| 
| 
| 
|-
|Suse Linux Enterprise Server (SLES 11)
|[[File:check.gif]]
|IBM Java 7
|MySQL 5.5.x (for SP3)
|-
|Red Hat Enterprise Linux 6 (RHEL6)
|[[File:check.gif]]
|OpenJDK 7
|MySQL v5.1.x
|-
|Debian 6
|[[File:check.gif]]
|SUN Java 6, OpenJDK 6 or Oracle Java 7
|MySQL v5.1.x
|-
|Debian 7
|[[File:check.gif]]
|OpenJDK 7 or Oracle Java 7
|MySQL v5.5.x
|-
|CentOS 6
|[[File:check.gif]]
|OpenJDK 7
|MySQL v5.1.x
|-
|Univention Corporate Server 3.x, 4.x
|[[File:check.gif]]
|OpenJDK 1.6
|MySQL v5.1.x
|-
|}

'''Please Note: To gain higher availability a setup based on Percona XtraDB 5.5 is supported like described in this article: [http://oxpedia.org/wiki/index.php?title=OXLoadBalancingClustering_Database Galera database setup]

[[Category: OX7]]
[[Category: AppSuite]]

Spamassassin

2014-08-25T15:10:19Z

Usman.ahmad: /* SpamAssassin */

= Introduction =

This OXpedia article describes, how to connect the [http://spamassassin.apache.org/ SpamAssassin] system with Open-Xchange.
It allows accessing your SpamAssassin settings from within Open-Xchange and use the spam- and ham
Learning mechanisms of SpamAssassin directly from within the Open-Xchange UI.

= Prerequisites =

== Sieve ==

You will need to install and configure the [http://sieve.info/ SIEVE] Mail filter program on your mail server. Since we will '''not''' cover the installation part of Sieve in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

== SpamAssassin ==

You will also need to install and configure the [http://spamassassin.apache.org/ SpamAssassin]. Since we will '''not''' cover the installation part of SpamAssassin in this article, therefore we will only tell the important configuration settings needed for SpamAssassin to get integrated with Open-Xchange.

= Installation =

We will need to install the following two packages on the Open-Xchange server.

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|sopath=6.22/backend|version=v6.22.x}}

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Configuration =

== For Sieve ==

As we have now already installed the needed package '''open-xchange-mailfilter'''. Now we need to configure the setting the configuration file so that Open-Xchange can be integrated with Sieve.

Open the following file in your Linux editor.
<pre>
$ /opt/open-xchange/etc/mailfilter.properties
</pre>

Edit the following lines

<pre>
SIEVE_SERVER=localhost //your sieve server name, localhost is default for single machine

SIEVE_PORT=4190 //this port should be same as the one you define during the installation of Sieve.
</pre>

Save the changes and reboot Open-Xchange service.

<pre>
$ /etc/init.d/open-xchange restart
</pre>

Verify that the mailfilter bundle has started properly and should be ACTIVE.
<pre>
$ listbundles | grep filter

bundlename: com.openexchange.mail.filter status: ACTIVE
</pre>

== For SpamAssassin ==

Open the following file in Linux editor
<pre>
$ /opt/open-xchange/etc/imap.properties
</pre>

Edit the following parameter to:

<pre>
com.openexchange.imap.spamHandler=SpamAssassin
</pre>

Once done then reboot the OX Service
<pre>
$ /etc/init.d/open-xchange restart
</pre>

Make sure that SpamAssassin port is also open Port 783 (by default). Also verify that spam bundles loaded successfully.

<pre>
$ /opt/open-xchange/sbin/listbundles | grep spam
bundlename: com.openexchange.spamhandler.spamassassin status: ACTIVE
</pre>

Finally, we will need to enable the GUI Capabilities for SPAM. To do this we have to run the following command for e.g.

<pre>
$ changeuser -A oxadmin -P admin_password -c contextID -u username --gui_spam_filter_capabilities_enabled true
</pre>

[[Category: Administrator]]

[[Category: OX6]]
[[Category: AppSuite]]

[[Category: Spamhandling]]

= Basic Troubleshooting =

1. Make sure that you configure your Firewall to allow ports e.g. '''Port 4190''' for Sieve and '''Port 783''' for SpamAssassin in your Server environment.

2. Check '''/var/log/maillog''' for any issues as well. Also can turn the mail Debug logging for Dovecot e.g.

<pre>
$ vi /etc/dovecot/conf.d/10-logging.conf
</pre>
and change the config parameter

<pre>
$ mail_debug = yes
</pre>

3. For SpamAssassin, you can also check the Open-Xchange Server logs to make sure that the settings are loaded correctly.

Spamassassin

2014-08-22T14:31:47Z

Usman.ahmad: /* Troubleshooting */

= Introduction =

This OXpedia article describes, how to connect the [http://spamassassin.apache.org/ SpamAssassin] system with Open-Xchange.
It allows accessing your SpamAssassin settings from within Open-Xchange and use the spam- and ham
Learning mechanisms of SpamAssassin directly from within the Open-Xchange UI.

= Prerequisites =

== Sieve ==

You will need to install and configure the [http://sieve.info/ SIEVE] Mail filter program on your mail server. Since we will '''not''' cover the installation part of Sieve in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

== SpamAssassin ==

You will also need to install and configure the [http://spamassassin.apache.org/ SpamAssassin]. Since we will '''not''' cover the installation part of SpamAssassin in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

= Installation =

We will need to install the following two packages on the Open-Xchange server.

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|sopath=6.22/backend|version=v6.22.x}}

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Configuration =

== For Sieve ==

As we have now already installed the needed package '''open-xchange-mailfilter'''. Now we need to configure the setting the configuration file so that Open-Xchange can be integrated with Sieve.

Open the following file in your Linux editor.
<pre>
$ /opt/open-xchange/etc/mailfilter.properties
</pre>

Edit the following lines

<pre>
SIEVE_SERVER=localhost //your sieve server name, localhost is default for single machine

SIEVE_PORT=4190 //this port should be same as the one you define during the installation of Sieve.
</pre>

Save the changes and reboot Open-Xchange service.

<pre>
$ /etc/init.d/open-xchange restart
</pre>

Verify that the mailfilter bundle has started properly and should be ACTIVE.
<pre>
$ listbundles | grep filter

bundlename: com.openexchange.mail.filter status: ACTIVE
</pre>

== For SpamAssassin ==

Open the following file in Linux editor
<pre>
$ /opt/open-xchange/etc/imap.properties
</pre>

Edit the following parameter to:

<pre>
com.openexchange.imap.spamHandler=SpamAssassin
</pre>

Once done then reboot the OX Service
<pre>
$ /etc/init.d/open-xchange restart
</pre>

Make sure that SpamAssassin port is also open Port 783 (by default). Also verify that spam bundles loaded successfully.

<pre>
$ /opt/open-xchange/sbin/listbundles | grep spam
bundlename: com.openexchange.spamhandler.spamassassin status: ACTIVE
</pre>

Finally, we will need to enable the GUI Capabilities for SPAM. To do this we have to run the following command for e.g.

<pre>
$ changeuser -A oxadmin -P admin_password -c contextID -u username --gui_spam_filter_capabilities_enabled true
</pre>

[[Category: Administrator]]

[[Category: OX6]]
[[Category: AppSuite]]

[[Category: Spamhandling]]

= Basic Troubleshooting =

1. Make sure that you configure your Firewall to allow ports e.g. '''Port 4190''' for Sieve and '''Port 783''' for SpamAssassin in your Server environment.

2. Check '''/var/log/maillog''' for any issues as well. Also can turn the mail Debug logging for Dovecot e.g.

<pre>
$ vi /etc/dovecot/conf.d/10-logging.conf
</pre>
and change the config parameter

<pre>
$ mail_debug = yes
</pre>

3. For SpamAssassin, you can also check the Open-Xchange Server logs to make sure that the settings are loaded correctly.

Spamassassin

2014-08-22T14:31:26Z

Usman.ahmad: /* Troubleshooting */

= Introduction =

This OXpedia article describes, how to connect the [http://spamassassin.apache.org/ SpamAssassin] system with Open-Xchange.
It allows accessing your SpamAssassin settings from within Open-Xchange and use the spam- and ham
Learning mechanisms of SpamAssassin directly from within the Open-Xchange UI.

= Prerequisites =

== Sieve ==

You will need to install and configure the [http://sieve.info/ SIEVE] Mail filter program on your mail server. Since we will '''not''' cover the installation part of Sieve in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

== SpamAssassin ==

You will also need to install and configure the [http://spamassassin.apache.org/ SpamAssassin]. Since we will '''not''' cover the installation part of SpamAssassin in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

= Installation =

We will need to install the following two packages on the Open-Xchange server.

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|sopath=6.22/backend|version=v6.22.x}}

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Configuration =

== For Sieve ==

As we have now already installed the needed package '''open-xchange-mailfilter'''. Now we need to configure the setting the configuration file so that Open-Xchange can be integrated with Sieve.

Open the following file in your Linux editor.
<pre>
$ /opt/open-xchange/etc/mailfilter.properties
</pre>

Edit the following lines

<pre>
SIEVE_SERVER=localhost //your sieve server name, localhost is default for single machine

SIEVE_PORT=4190 //this port should be same as the one you define during the installation of Sieve.
</pre>

Save the changes and reboot Open-Xchange service.

<pre>
$ /etc/init.d/open-xchange restart
</pre>

Verify that the mailfilter bundle has started properly and should be ACTIVE.
<pre>
$ listbundles | grep filter

bundlename: com.openexchange.mail.filter status: ACTIVE
</pre>

== For SpamAssassin ==

Open the following file in Linux editor
<pre>
$ /opt/open-xchange/etc/imap.properties
</pre>

Edit the following parameter to:

<pre>
com.openexchange.imap.spamHandler=SpamAssassin
</pre>

Once done then reboot the OX Service
<pre>
$ /etc/init.d/open-xchange restart
</pre>

Make sure that SpamAssassin port is also open Port 783 (by default). Also verify that spam bundles loaded successfully.

<pre>
$ /opt/open-xchange/sbin/listbundles | grep spam
bundlename: com.openexchange.spamhandler.spamassassin status: ACTIVE
</pre>

Finally, we will need to enable the GUI Capabilities for SPAM. To do this we have to run the following command for e.g.

<pre>
$ changeuser -A oxadmin -P admin_password -c contextID -u username --gui_spam_filter_capabilities_enabled true
</pre>

[[Category: Administrator]]

[[Category: OX6]]
[[Category: AppSuite]]

[[Category: Spamhandling]]

= Troubleshooting =

1. Make sure that you configure your Firewall to allow ports e.g. '''Port 4190''' for Sieve and '''Port 783''' for SpamAssassin in your Server environment.

2. Check '''/var/log/maillog''' for any issues as well. Also can turn the mail Debug logging for Dovecot e.g.

<pre>
$ vi /etc/dovecot/conf.d/10-logging.conf
</pre>
and change the config parameter

<pre>
$ mail_debug = yes
</pre>

3. For SpamAssassin, you can also check the Open-Xchange Server logs to make sure that the settings are loaded correctly.

Spamassassin

2014-08-22T14:30:32Z

Usman.ahmad:

= Introduction =

This OXpedia article describes, how to connect the [http://spamassassin.apache.org/ SpamAssassin] system with Open-Xchange.
It allows accessing your SpamAssassin settings from within Open-Xchange and use the spam- and ham
Learning mechanisms of SpamAssassin directly from within the Open-Xchange UI.

= Prerequisites =

== Sieve ==

You will need to install and configure the [http://sieve.info/ SIEVE] Mail filter program on your mail server. Since we will '''not''' cover the installation part of Sieve in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

== SpamAssassin ==

You will also need to install and configure the [http://spamassassin.apache.org/ SpamAssassin]. Since we will '''not''' cover the installation part of SpamAssassin in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

= Installation =

We will need to install the following two packages on the Open-Xchange server.

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|sopath=6.22/backend|version=v6.22.x}}

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Configuration =

== For Sieve ==

As we have now already installed the needed package '''open-xchange-mailfilter'''. Now we need to configure the setting the configuration file so that Open-Xchange can be integrated with Sieve.

Open the following file in your Linux editor.
<pre>
$ /opt/open-xchange/etc/mailfilter.properties
</pre>

Edit the following lines

<pre>
SIEVE_SERVER=localhost //your sieve server name, localhost is default for single machine

SIEVE_PORT=4190 //this port should be same as the one you define during the installation of Sieve.
</pre>

Save the changes and reboot Open-Xchange service.

<pre>
$ /etc/init.d/open-xchange restart
</pre>

Verify that the mailfilter bundle has started properly and should be ACTIVE.
<pre>
$ listbundles | grep filter

bundlename: com.openexchange.mail.filter status: ACTIVE
</pre>

== For SpamAssassin ==

Open the following file in Linux editor
<pre>
$ /opt/open-xchange/etc/imap.properties
</pre>

Edit the following parameter to:

<pre>
com.openexchange.imap.spamHandler=SpamAssassin
</pre>

Once done then reboot the OX Service
<pre>
$ /etc/init.d/open-xchange restart
</pre>

Make sure that SpamAssassin port is also open Port 783 (by default). Also verify that spam bundles loaded successfully.

<pre>
$ /opt/open-xchange/sbin/listbundles | grep spam
bundlename: com.openexchange.spamhandler.spamassassin status: ACTIVE
</pre>

Finally, we will need to enable the GUI Capabilities for SPAM. To do this we have to run the following command for e.g.

<pre>
$ changeuser -A oxadmin -P admin_password -c contextID -u username --gui_spam_filter_capabilities_enabled true
</pre>

[[Category: Administrator]]

[[Category: OX6]]
[[Category: AppSuite]]

[[Category: Spamhandling]]

= Troubleshooting =

1. Make sure that you configure your Firewall to allow ports e.g. Port 4190 for Sieve and Port 783 for SpamAssassin in your Server environment.

2. Check /var/log/maillog for any issues as well. Also can turn the mail Debug logging for Dovecot e.g.

<pre>
$ vi /etc/dovecot/conf.d/10-logging.conf
</pre>
and change the config parameter

<pre>
$ mail_debug = yes
</pre>

3. For SpamAssassin, you can also check the Open-Xchange Server logs to make sure that the settings are loaded correctly.

Spamassassin

2014-08-22T14:22:52Z

Usman.ahmad: /* For SpamAssassin */

= Introduction =

This OXpedia article describes, how to connect the [http://spamassassin.apache.org/ SpamAssassin] system with Open-Xchange.
It allows accessing your SpamAssassin settings from within Open-Xchange and use the spam- and ham
Learning mechanisms of SpamAssassin directly from within the Open-Xchange UI.

= Prerequisites =

== Sieve ==

You will need to install and configure the [http://sieve.info/ SIEVE] Mail filter program on your mail server. Since we will '''not''' cover the installation part of Sieve in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

== SpamAssassin ==

You will also need to install and configure the [http://spamassassin.apache.org/ SpamAssassin]. Since we will '''not''' cover the installation part of SpamAssassin in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

= Installation =

We will need to install the following two packages on the Open-Xchange server.

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|sopath=6.22/backend|version=v6.22.x}}

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Configuration =

== For Sieve ==

As we have now already installed the needed package '''open-xchange-mailfilter'''. Now we need to configure the setting the configuration file so that Open-Xchange can be integrated with Sieve.

Open the following file in your Linux editor.
<pre>
$ /opt/open-xchange/etc/mailfilter.properties
</pre>

Edit the following lines

<pre>
SIEVE_SERVER=localhost //your sieve server name, localhost is default for single machine

SIEVE_PORT=4190 //this port should be same as the one you define during the installation of Sieve.
</pre>

Save the changes and reboot Open-Xchange service.

<pre>
$ /etc/init.d/open-xchange restart
</pre>

Verify that the mailfilter bundle has started properly and should be ACTIVE.
<pre>
$ listbundles | grep filter

bundlename: com.openexchange.mail.filter status: ACTIVE
</pre>

== For SpamAssassin ==

Open the following file in Linux editor
<pre>
$ /opt/open-xchange/etc/imap.properties
</pre>

Edit the following parameter to:

<pre>
com.openexchange.imap.spamHandler=SpamAssassin
</pre>

Once done then reboot the OX Service
<pre>
$ /etc/init.d/open-xchange restart
</pre>

Make sure that SpamAssassin port is also open Port 783 (by default). Also verify that spam bundles loaded successfully.

<pre>
$ /opt/open-xchange/sbin/listbundles | grep spam
bundlename: com.openexchange.spamhandler.spamassassin status: ACTIVE
</pre>

Finally, we will need to enable the GUI Capabilities for SPAM. To do this we have to run the following command for e.g.

<pre>
$ changeuser -A oxadmin -P admin_password -c contextID -u username --gui_spam_filter_capabilities_enabled true
</pre>

[[Category: Administrator]]

[[Category: OX6]]
[[Category: AppSuite]]

[[Category: Spamhandling]]

Spamassassin

2014-08-21T13:42:43Z

Usman.ahmad:

= Introduction =

This OXpedia article describes, how to connect the [http://spamassassin.apache.org/ SpamAssassin] system with Open-Xchange.
It allows accessing your SpamAssassin settings from within Open-Xchange and use the spam- and ham
Learning mechanisms of SpamAssassin directly from within the Open-Xchange UI.

= Prerequisites =

== Sieve ==

You will need to install and configure the [http://sieve.info/ SIEVE] Mail filter program on your mail server. Since we will '''not''' cover the installation part of Sieve in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

== SpamAssassin ==

You will also need to install and configure the [http://spamassassin.apache.org/ SpamAssassin]. Since we will '''not''' cover the installation part of SpamAssassin in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

= Installation =

We will need to install the following two packages on the Open-Xchange server.

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|sopath=6.22/backend|version=v6.22.x}}

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Configuration =

== For Sieve ==

As we have now already installed the needed package '''open-xchange-mailfilter'''. Now we need to configure the setting the configuration file so that Open-Xchange can be integrated with Sieve.

Open the following file in your Linux editor.
<pre>
$ /opt/open-xchange/etc/mailfilter.properties
</pre>

Edit the following lines

<pre>
SIEVE_SERVER=localhost //your sieve server name, localhost is default for single machine

SIEVE_PORT=4190 //this port should be same as the one you define during the installation of Sieve.
</pre>

Save the changes and reboot Open-Xchange service.

<pre>
$ /etc/init.d/open-xchange restart
</pre>

Verify that the mailfilter bundle has started properly and should be ACTIVE.
<pre>
$ listbundles | grep filter

bundlename: com.openexchange.mail.filter status: ACTIVE
</pre>

== For SpamAssassin ==

Open the following file in Linux editor
<pre>
$ /opt/open-xchange/etc/imap.properties
</pre>

Edit the following parameter to:

<pre>
com.openexchange.imap.spamHandler=SpamAssassin
</pre>

Once done then reboot the OX Service
<pre>
$ /etc/init.d/open-xchange restart
</pre>

Make sure that SpamAssassin port is also open Port 783 (by default). Also verify that spam bundles loaded successfully.

<pre>
$ /opt/open-xchange/sbin/listbundles | grep spam
bundlename: com.openexchange.spamhandler.spamassassin status: ACTIVE
</pre>

Finally, we will need to enable the GUI Capabilities for SPAM. To do this we have to run the following command for e.g.

<pre>
$ changeuser -A oxadmin -P admin_password -c 1 -u username --gui_spam_filter_capabilities_enabled true
</pre>

[[Category: Administrator]]

[[Category: OX6]]
[[Category: AppSuite]]

[[Category: Spamhandling]]

Spamassassin

2014-08-21T13:15:11Z

Usman.ahmad: Created page with "= Introduction = This OXpedia article describes, how to connect the [http://spamassassin.apache.org/ SpamAssassin] system with Open-Xchange. It allows accessing your SpamAssa..."

= Introduction =

This OXpedia article describes, how to connect the [http://spamassassin.apache.org/ SpamAssassin] system with Open-Xchange.
It allows accessing your SpamAssassin settings from within Open-Xchange and use the spam- and ham
Learning mechanisms of SpamAssassin directly from within the Open-Xchange UI.

= Prerequisites =

== Sieve ==

You will need to install and configure the [http://sieve.info/ SIEVE] Mail filter program on your mail server. Since we will '''not''' cover the installation part of Sieve in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

== SpamAssassin ==

You will also need to install and configure the [http://spamassassin.apache.org/ SpamAssassin]. Since we will '''not''' cover the installation part of SpamAssassin in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.

= Installation =

We will need to install the following two packages on the Open-Xchange server.

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|sopath=6.22/backend|version=v6.22.x}}

{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Configuration =

== For Sieve ==

As we have now already installed the needed package '''open-xchange-mailfilter'''. Now we need to configure the setting the configuration file so that Open-Xchange can be integrated with Sieve.

Open the following file in your Linux editor.
<pre>
$ /opt/open-xchange/etc/mailfilter.properties
</pre>

Edit the following lines

<pre>
SIEVE_SERVER=localhost //your sieve server name, localhost is default for single machine

SIEVE_PORT=4190 //this port should be same as the one you define during the installation of Sieve.
</pre>

Save the changes and reboot Open-Xchange service.

<pre>
$ /etc/init.d/open-xchange restart
</pre>

Verify that the mailfilter bundle has started properly and should be ACTIVE.
<pre>
$ listbundles | grep filter

bundlename: com.openexchange.mail.filter status: ACTIVE
</pre>

== For SpamAssassin ==

Open the following file in Linux editor
<pre>
$ /opt/open-xchange/etc/imap.properties
</pre>

Edit the following parameter to:

<pre>
com.openexchange.imap.spamHandler=SpamAssassin
</pre>

Once done then reboot the OX Service
<pre>
$ /etc/init.d/open-xchange restart
</pre>

Make sure that SpamAssassin port is also open Port 783 (by default). Also verify that spam bundles loaded successfully.

<pre>
$ /opt/open-xchange/sbin/listbundles | grep spam
bundlename: com.openexchange.spamhandler.spamassassin status: ACTIVE
</pre>

Finally, we will need to enable the GUI Capabilities for SPAM. To do this we have to run the following command for e.g.

<pre>
$ changeuser -A oxadmin -P admin_password -c 1 -u username --gui_spam_filter_capabilities_enabled true
</pre>

AppSuite:Debugging the UI

2014-08-01T14:50:34Z

Usman.ahmad: /* Finding the version */

<div class="title">Debugging the UI</div>
'''Synopsis:''' A collection of hints to debug during UI development. See also [[AppSuite:UI FAQ]]. Sister page: [[AppSuite:Debugging_the_server|Debugging the server]].

__TOC__

== What capabilities are available? ==
<pre class="language-javascript">
_(ox.serverConfig.capabilities).pluck("id").sort();
</pre>
== Is a specific capability set? ==
<pre class="language-javascript">
require(['io.ox/core/capabilities'], function (cap) {
console.log(cap.has('certain_cap'));
});
</pre>

== Which files failed to load? ==
<pre class="language-javascript">
requirejs.s.contexts._.registry
</pre>

== What portal widgets are available? ==
<pre class="language-javascript">
require(['io.ox/portal/widgets'], function (widgets) {
console.log(widgets.getAvailablePlugins().sort());
});
</pre>

== Check settings ==
<pre class="language-javascript">
// check core settings
require('settings!io.ox/core').get();
// check mail settings
require('settings!io.ox/mail').get();
</pre>

== Clear all persistent caches ==
Please mind that this does not clear the regular browser cache! It clears localStorage, IndexedDB, and WebSQL.
<pre class="language-javascript">
ox.cache.clear();
</pre>

== Clear all portal widgets ==
Sometimes you manage to build a portal widgets that messes up all kinds of things when a user adds it. This is a rather blunt way of solving the problem:

<pre class="language-javascript">
require(['settings!io.ox/portal'], function(settings) {
settings.set('widgets/user', '').save();
});
</pre>

== Debug relogin ==
<pre class="language-javascript">
ox.autoLogoutRestartDebug();
</pre>

== Enable/disable capability via URL hash ==
Just add the parameter "cap" to URL hash. A leading minus disables a capability. Multiple capabilities separated by comma. Example:
<pre language="none">
...&cap=emoji,-calendar
</pre>

== Changes do not apply while developing ==
You did changes in your code and they don't simply don't apply?
There are several possibilites, you should check in order to find a solution.

* Reload AppSuite with cleared Browser Cache. Using Firefox on Linux-Distributions you can simply press <tt>Ctrl+F5</tt>. Please check the documentation of your Browser for Shortcuts and how to clear the cache.
* Disable Source Caching. Therefor add the parameter <tt>"debug-js=true"</tt> to URL hash. Example:
<pre language="none">...&debug-js=true</pre>

== Debug a specific folder ==
If you want to get details of a specific folder, just inspect it via dev tools and look for data-obj-id="...". Copy the id and run the following in console:
<pre class="language-javascript">
void require('io.ox/core/api/folder').get({ folder: 'default0/INBOX' }).always(_.inspect);
</pre>

== Finding the version ==
If you want to know the backend and frontend versions with revision numbers, specifically when you simply cannot find it from the WebUI's About button as some customer hides it, then you can use the following command:
<pre class="language-javascript">
"Server version: " + ox.serverConfig.serverVersion + ", UI version: " + ox.version
</pre>

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Developer]]

AppSuite:Debugging the UI

2014-07-31T09:38:35Z

Usman.ahmad:

<div class="title">Debugging the UI</div>
'''Synopsis:''' A collection of hints to debug during UI development. See also [[AppSuite:UI FAQ]]. Sister page: [[AppSuite:Debugging_the_server|Debugging the server]].

__TOC__

== What capabilities are available? ==
<pre class="language-javascript">
_(ox.serverConfig.capabilities).pluck("id").sort();
</pre>
== Is a specific capability set? ==
<pre class="language-javascript">
require(['io.ox/core/capabilities'], function (cap) {
console.log(cap.has('certain_cap'));
});
</pre>

== Which files failed to load? ==
<pre class="language-javascript">
requirejs.s.contexts._.registry
</pre>

== What portal widgets are available? ==
<pre class="language-javascript">
require(['io.ox/portal/widgets'], function (widgets) {
console.log(widgets.getAvailablePlugins().sort());
});
</pre>

== Check settings ==
<pre class="language-javascript">
// check core settings
require('settings!io.ox/core').get();
// check mail settings
require('settings!io.ox/mail').get();
</pre>

== Clear all persistent caches ==
Please mind that this does not clear the regular browser cache! It clears localStorage, IndexedDB, and WebSQL.
<pre class="language-javascript">
ox.cache.clear();
</pre>

== Clear all portal widgets ==
Sometimes you manage to build a portal widgets that messes up all kinds of things when a user adds it. This is a rather blunt way of solving the problem:

<pre class="language-javascript">
require(['settings!io.ox/portal'], function(settings) {
settings.set('widgets/user', '').save();
});
</pre>

== Debug relogin ==
<pre class="language-javascript">
ox.autoLogoutRestartDebug();
</pre>

== Enable/disable capability via URL hash ==
Just add the parameter "cap" to URL hash. A leading minus disables a capability. Multiple capabilities separated by comma. Example:
<pre language="none">
...&cap=emoji,-calendar
</pre>

== Changes do not apply while developing ==
You did changes in your code and they don't simply don't apply?
There are several possibilites, you should check in order to find a solution.

* Reload AppSuite with cleared Browser Cache. Using Firefox on Linux-Distributions you can simply press <tt>Ctrl+F5</tt>. Please check the documentation of your Browser for Shortcuts and how to clear the cache.
* Disable Source Caching. Therefor add the parameter <tt>"debug-js=true"</tt> to URL hash. Example:
<pre language="none">...&debug-js=true</pre>

== Debug a specific folder ==
If you want to get details of a specific folder, just inspect it via dev tools and look for data-obj-id="...". Copy the id and run the following in console:
<pre class="language-javascript">
void require('io.ox/core/api/folder').get({ folder: 'default0/INBOX' }).always(_.inspect);
</pre>

== Finding the version ==
If you want to the backend and the frontend version with revision numbers, specifically when you simply cannot find it from the WebUI's About button as some customer hides it, then you can use the following command:
<pre class="language-javascript">
"Server version: " + ox.serverConfig.serverVersion + ", UI version: " + ox.version
</pre>

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Developer]]

ChangePasswordExternal

2014-04-29T07:32:45Z

Usman.ahmad: /* Example */

== Introduction ==

The package <tt>open-xchange-passwordchange-script</tt> allows you to run a command to change a password in an external subsystem like e.g. LDAP.

== Installation ==

{{InstallPlugin|pluginname=open-xchange-passwordchange-script|sopath=stable}}

== Example ==

In <tt>/opt/open-xchange/etc/change_pwd_script.properties</tt> add this line:

com.openexchange.passwordchange.script.shellscript=/bin/pwchange.pl

=== Example Script 1 ===

This example script calls <tt>saslpasswd</tt> to change the password in the sasldb:

#! /usr/bin/perl -w -T
#
# perlsec(1) for security related perl programming
#
use Getopt::Long;
use strict;

my $user;
my $pw;
my $result;
my $cid;
my $oldpassword;
my $userid;

open(LOG, '>>/var/log/pw.log');

sub log_error {
my $errorstring=$_[0];
print LOG "Error: $errorstring\n";
die "$errorstring";
}
# secure env
$ENV{'PATH'} = "";
$ENV{'ENV'} = "";

$result = GetOptions ("username=s" => \$user,
"cid" => \$cid,
"userid" => \$userid,
"oldpassword" => \$oldpassword,
"newpassword=s" => \$pw);

$user || &log_error("missing parameter username");
print LOG "changing password for user $user\n";
$pw || &log_error("missing parameter newpassword");

my $usersav = $user;

# add a taint check
if ($user =~ /^([-\@\w.]+)$/) {
$user = $1; # $data now untainted
} else {
&log_error("Bad data in '$user'");
}

die "Can't fork: $!" unless defined(my $pid = open(KID, "|-"));
if ($pid) { # parent
print KID $pw;
close KID;
} else {
exec '/usr/bin/sudo', '/usr/sbin/saslpasswd2', '-p', "$user"
or &log_error("can't exec myprog: $!");
}
close(LOG);

=== Example Script 2 ===

The following script uses ldappasswd to change the password in an LDAP server.

#!/bin/bash
ldappasswd -h my_ldap_server -D "uid=$4,ou=people,dc=example,dc=com" -w $8 \
-s ${10} "uid=$4,ou=people,dc=example,dc=com"

=== Example Script 3 ===

The following script uses open-xchange-passwordchange-script data to change the password within LDAP

#!/usr/bin/perl -w
# Begin LDAP Stuff
use Net::LDAP;
use Net::LDAP::Extension::SetPassword;
my $cid = $ARGV[1];
my $userid = $ARGV[5];
my $oldpw = $ARGV[7];
my $hostname= 'localhost';
my $rootdn= 'cn=Administrator,dc=example,dc=com';
my $userbind= 'ou=People,dc=example,dc=com';
my $adminpasswd='system';
my $name= $ARGV[3];
my $newpasswd= $ARGV[9];
my $ldap = Net::LDAP->new("$hostname")
or die "Host not found: $!";

open(LOG, '>>/var/log/open-xchange/pw.log');

sub log_error {
my $errorstring=$_[0];
print LOG "Error: $errorstring\n";
die "$errorstring";
}

$name || &log_error("missing parameter username");
print LOG "changing password for $ARGV[2]: $name with $ARGV[0]: $cid and $ARGV[4]: $userid\n";
$newpasswd || &log_error("missing parameter newpassword");

$ldap->bind( "$rootdn", password => "$adminpasswd" );

my $mesg = $ldap->set_password(
newpasswd => "$newpasswd",
user => "uid=$name,$userbind"
);

die "error: ", $mesg->code(), ": ", $mesg->error() if ( $mesg->code() );
close(LOG);

AppSuite:Connector for Business Mobility Installation Guide

2014-03-12T08:52:04Z

Usman.ahmad: /* Requirements */

= Open-Xchange Connector for Business Mobility =

== Components ==

With the Connector for Business Mobility, Open-Xchange also introduces the Universal Synchronization Module (USM). This module provides a framework for synchronization protocols such as Microsoft Exchange ActiveSync (EAS) or other services building on this foundation. USM acts as a layer between the Open-Xchange HTTP API and the synchronization protocol. It handles synchronization specific tasks like conflict management.
The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.

=== Component Overview ===
USM, EAS and OX work together as components. This is a general outline about how these components interact.

When the device initiates a synchronization through ActiveSync, it contacts the webserver using the URL /Microsoft-Server-ActiveSync via HTTP/s. This URL is forwarded to the Open-Xchange application server where the corresponding servlet is offered by the EAS component. The EAS component then uses USM to initiate a connection to the OX HTTP API and exchanges groupware data. In all cases, USM works as an client to the Open-Xchange HTTP API. It also uses some database tables which are accessed through the Open-Xchange SQL interface to store metadata like synchronization status. The same component stack is used to transport groupware data back to the device.

=== Requirements ===

Since the Connector for Business Mobility is a server plug-in based on the OSGi Framework it can be added to an existing Open-Xchange installation very easily. '''OX App Suite v7.0 or later is required to operate this extension.''' The Connector for Business Mobility uses the resources and services offered by the Open-Xchange server, no additional software or configuration is required.

* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_6.0 | Debian 6.0 (Squeeze)]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES11 | SLES11]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6 | RHEL6]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_CentOS_6 | CentOS 6]]

'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article [[AppSuite:UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.

== Installation ==

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|usm|mobilityconnector}}

$ yum install open-xchange-meta-mobility

=== Debian GNU/Linux 6.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianSqueeze|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|usm|mobilityconnector}}

$ apt-get update
$ apt-get install open-xchange-meta-mobility

=== SUSE Linux Enterprise Server 11 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|usm|mobilityconnector}}

$ zypper ref
$ zypper install open-xchange-meta-mobility

Now the Open-Xchange service needs to be restarted:

/etc/init.d/open-xchange restart

On the first login after the restart, all required database tables will be created.

== Download and Installation OX Server Edition / App Suite for UCS ==

If you have purchased the OX Server Edition / App Suite for UCS, the Connector is part of the offering. Installation of the Connector with the following steps:

* The new license is already registered at the LDB after purchase
* Click on "Online Updates" at the Univention Management Console
* The Connector for Business Mobility is available at the "Open-Xchange Components"

== Configuration ==

=== Mail Push ===

In order to get mail push, either install and configure the package open-xchange-push-malpoll, which is not recommended on large deployments or if you're using cyrus-imap, read the [[MailNotify Bundle‎‎]] instructions on how to set up real mail push with cyrus.

=== Open-Xchange configuration ===
The configuration for USM and the EAS protocol can be found in these two configuration files:
/opt/open-xchange/etc/usm.properties
/opt/open-xchange/etc/eas.properties

Make sure that the Open-Xchange Server URL is set properly in usm.properties. This needs to be the machine which provides the web interface. Usually, this is localhost, as the webserver and Open-Xchange run on the same machine.
com.openexchange.usm.ox.url=http://localhost/ajax/

in case webserver and Open-Xchange aren't running on the same machine:
com.openexchange.usm.ox.url=http://$FQDN/ajax/
(Where $FQDN is the fully qualified domain name of your frontend system)

On clustered setups, adjust the file
/opt/open-xchange/etc/groupware/noipcheck.cnf
to include the range of IP addresses of the servers on which USM is running.

Documentation about the configuration parameters can be found inside the configuration files. If you change any attribute at the configuration files, the Open-Xchange groupware service needs to be restarted.

=== Apache Configuration ===
Mobile devices supporting ActiveSync use a special URL to communicate with an ActiveSync enabled Open-Xchange Server. This URL needs to be forwarded to the Open-Xchange ActiveSync servlet. The required configuration options are already part of the default Open-Xchange installation instructions.

The example assumes that Open-Xchange Server is running on the same machine like the webserver. Please refer the Open-Xchange administration documentation for more information about Apache configuration. Please restart apache after performing the configuration change.
/etc/init.d/apache2 restart

=== Enabling ActiveSync for user accounts ===
In order to use synchronization through ActiveSync, this feature needs to be activated for user accounts. You can either activate it for specific users or a whole context.

Activating ActiveSync for specific users:
/opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --access-usm on --access-active-sync on

Activating ActiveSync for a whole context:
/opt/open-xchange/sbin/changecontext -c 1 -A oxadminmaster -P admin_master_password --access-usm on --access-active-sync on

== Log files and issue tracking ==
When facing problems with synchronization, there are several ways to get more information than provided via device or platform specific error codes.

=== Open-Xchange Server logfile ===
By default, the log output is non verbose. Only severe errors will be logged. To enable a more detailed log output, the logging mechanism needs to be configured. This depends on the used mechanism.

=== Commons Logging ===
This is the default logging mechanism. If the Open-Xchange Server log output is written to ''var/log/open-xchange/open-xchange.log'' it's an indicator that this mechanism is in use. To make the log output more verbose, add the following parameter:

vim /opt/open-xchange/etc/file-logging.properties
[...]
com.openexchange.usm.level=FINE

This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.

=== Log4j ===
If the package ''open-xchange-log4j'' is installed, Open-Xchange Server will log via a UDP network socket. In most cases a syslog daemon is listening to this socket and will write the log data to a platform specif file like ''/var/log/syslog''. To make the log output more verbose, add the following parameter:

vim /opt/open-xchange/etc/log4j.xml
[...]
<category name="com.openexchange.usm">
<level value="DEBUG"/>
<appender-ref ref="SERVER_LOG"/>
</category>

Please note that the XML syntax must be correct. This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.

=== EAS debug logfile ===
While the generic Open-Xchange Server log file will keep track on errors reported by the software components, the EAS debug log file will print all data transfered to the device as XML. Please note: this log file may contain confidential data about the users personal groupware objects. Make sure that no unauthorized access to those log files is possible in order to maintain privacy. Change the configuration file accordingly and set a output path which can only accessed by authorized persons.

vim /opt/open-xchange/etc/eas.properties
[...]
com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log

This will enable a XML based debug log for all EAS connections, after restarting Open-Xchange Server.

=== Network traffic ===
When using unencrypted connections between the device and USM and USM and Open-Xchange Server (not recommended), it's possible to analyze the network traffic with tools like ngrep or wireshark. When using encrypted data connections using SSL, the transfered data can be decrypted using the corresponding private key. Please note that there are two network streams, one from the device to USM (external) and one from USM to OX (internal).

== Bug-Reporting ==
Please report bugs via the Open-Xchange Bugzilla:

[https://bugs.open-xchange.com/ Direct link to Open-Xchange Bugzilla]

* Product: Connector for Business Mobility

= Client configuration =

Information about the client configuration for the different devices is available at the [http://software.open-xchange.com/products/appsuite/doc/mobilityconnector/ User Guides].

= Known Issues =

* The Exchange Active Sync protocol does not support the synchronization of client email drafts-folder to the server. Synchronization from server drafts-folder to the client will work.

[[Category: AppSuite]]

AppSuite:Connector for Business Mobility Installation Guide

2014-03-12T08:46:19Z

Usman.ahmad: /* Commons Logging */

= Open-Xchange Connector for Business Mobility =

== Components ==

With the Connector for Business Mobility, Open-Xchange also introduces the Universal Synchronization Module (USM). This module provides a framework for synchronization protocols such as Microsoft Exchange ActiveSync (EAS) or other services building on this foundation. USM acts as a layer between the Open-Xchange HTTP API and the synchronization protocol. It handles synchronization specific tasks like conflict management.
The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.

=== Component Overview ===
USM, EAS and OX work together as components. This is a general outline about how these components interact.

When the device initiates a synchronization through ActiveSync, it contacts the webserver using the URL /Microsoft-Server-ActiveSync via HTTP/s. This URL is forwarded to the Open-Xchange application server where the corresponding servlet is offered by the EAS component. The EAS component then uses USM to initiate a connection to the OX HTTP API and exchanges groupware data. In all cases, USM works as an client to the Open-Xchange HTTP API. It also uses some database tables which are accessed through the Open-Xchange SQL interface to store metadata like synchronization status. The same component stack is used to transport groupware data back to the device.

=== Requirements ===

Since the Connector for Business Mobility is a server plug-in based on the OSGi Framework it can be added to an existing Open-Xchange installation very easily. '''OX App Suite v7.0 or later is required to operate this extension.''' The Connector for Business Mobility uses the resources and services offered by the Open-Xchange server, no additional software or configuration is required.

* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_6.0 | Debian 6.0 (Squeeze)]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES11 | SLES11]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6 | RHEL6]]

'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article [[AppSuite:UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.

== Installation ==

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|usm|mobilityconnector}}

$ yum install open-xchange-meta-mobility

=== Debian GNU/Linux 6.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianSqueeze|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|usm|mobilityconnector}}

$ apt-get update
$ apt-get install open-xchange-meta-mobility

=== SUSE Linux Enterprise Server 11 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|usm|mobilityconnector}}

$ zypper ref
$ zypper install open-xchange-meta-mobility

Now the Open-Xchange service needs to be restarted:

/etc/init.d/open-xchange restart

On the first login after the restart, all required database tables will be created.

== Download and Installation OX Server Edition / App Suite for UCS ==

If you have purchased the OX Server Edition / App Suite for UCS, the Connector is part of the offering. Installation of the Connector with the following steps:

* The new license is already registered at the LDB after purchase
* Click on "Online Updates" at the Univention Management Console
* The Connector for Business Mobility is available at the "Open-Xchange Components"

== Configuration ==

=== Mail Push ===

In order to get mail push, either install and configure the package open-xchange-push-malpoll, which is not recommended on large deployments or if you're using cyrus-imap, read the [[MailNotify Bundle‎‎]] instructions on how to set up real mail push with cyrus.

=== Open-Xchange configuration ===
The configuration for USM and the EAS protocol can be found in these two configuration files:
/opt/open-xchange/etc/usm.properties
/opt/open-xchange/etc/eas.properties

Make sure that the Open-Xchange Server URL is set properly in usm.properties. This needs to be the machine which provides the web interface. Usually, this is localhost, as the webserver and Open-Xchange run on the same machine.
com.openexchange.usm.ox.url=http://localhost/ajax/

in case webserver and Open-Xchange aren't running on the same machine:
com.openexchange.usm.ox.url=http://$FQDN/ajax/
(Where $FQDN is the fully qualified domain name of your frontend system)

On clustered setups, adjust the file
/opt/open-xchange/etc/groupware/noipcheck.cnf
to include the range of IP addresses of the servers on which USM is running.

Documentation about the configuration parameters can be found inside the configuration files. If you change any attribute at the configuration files, the Open-Xchange groupware service needs to be restarted.

=== Apache Configuration ===
Mobile devices supporting ActiveSync use a special URL to communicate with an ActiveSync enabled Open-Xchange Server. This URL needs to be forwarded to the Open-Xchange ActiveSync servlet. The required configuration options are already part of the default Open-Xchange installation instructions.

The example assumes that Open-Xchange Server is running on the same machine like the webserver. Please refer the Open-Xchange administration documentation for more information about Apache configuration. Please restart apache after performing the configuration change.
/etc/init.d/apache2 restart

=== Enabling ActiveSync for user accounts ===
In order to use synchronization through ActiveSync, this feature needs to be activated for user accounts. You can either activate it for specific users or a whole context.

Activating ActiveSync for specific users:
/opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --access-usm on --access-active-sync on

Activating ActiveSync for a whole context:
/opt/open-xchange/sbin/changecontext -c 1 -A oxadminmaster -P admin_master_password --access-usm on --access-active-sync on

== Log files and issue tracking ==
When facing problems with synchronization, there are several ways to get more information than provided via device or platform specific error codes.

=== Open-Xchange Server logfile ===
By default, the log output is non verbose. Only severe errors will be logged. To enable a more detailed log output, the logging mechanism needs to be configured. This depends on the used mechanism.

=== Commons Logging ===
This is the default logging mechanism. If the Open-Xchange Server log output is written to ''var/log/open-xchange/open-xchange.log'' it's an indicator that this mechanism is in use. To make the log output more verbose, add the following parameter:

vim /opt/open-xchange/etc/file-logging.properties
[...]
com.openexchange.usm.level=FINE

This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.

=== Log4j ===
If the package ''open-xchange-log4j'' is installed, Open-Xchange Server will log via a UDP network socket. In most cases a syslog daemon is listening to this socket and will write the log data to a platform specif file like ''/var/log/syslog''. To make the log output more verbose, add the following parameter:

vim /opt/open-xchange/etc/log4j.xml
[...]
<category name="com.openexchange.usm">
<level value="DEBUG"/>
<appender-ref ref="SERVER_LOG"/>
</category>

Please note that the XML syntax must be correct. This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.

=== EAS debug logfile ===
While the generic Open-Xchange Server log file will keep track on errors reported by the software components, the EAS debug log file will print all data transfered to the device as XML. Please note: this log file may contain confidential data about the users personal groupware objects. Make sure that no unauthorized access to those log files is possible in order to maintain privacy. Change the configuration file accordingly and set a output path which can only accessed by authorized persons.

vim /opt/open-xchange/etc/eas.properties
[...]
com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log

This will enable a XML based debug log for all EAS connections, after restarting Open-Xchange Server.

=== Network traffic ===
When using unencrypted connections between the device and USM and USM and Open-Xchange Server (not recommended), it's possible to analyze the network traffic with tools like ngrep or wireshark. When using encrypted data connections using SSL, the transfered data can be decrypted using the corresponding private key. Please note that there are two network streams, one from the device to USM (external) and one from USM to OX (internal).

== Bug-Reporting ==
Please report bugs via the Open-Xchange Bugzilla:

[https://bugs.open-xchange.com/ Direct link to Open-Xchange Bugzilla]

* Product: Connector for Business Mobility

= Client configuration =

Information about the client configuration for the different devices is available at the [http://software.open-xchange.com/products/appsuite/doc/mobilityconnector/ User Guides].

= Known Issues =

* The Exchange Active Sync protocol does not support the synchronization of client email drafts-folder to the server. Synchronization from server drafts-folder to the client will work.

[[Category: AppSuite]]

AppSuite:Connector for Business Mobility Installation Guide

2014-03-12T08:46:07Z

Usman.ahmad: /* Log4j */

= Open-Xchange Connector for Business Mobility =

== Components ==

With the Connector for Business Mobility, Open-Xchange also introduces the Universal Synchronization Module (USM). This module provides a framework for synchronization protocols such as Microsoft Exchange ActiveSync (EAS) or other services building on this foundation. USM acts as a layer between the Open-Xchange HTTP API and the synchronization protocol. It handles synchronization specific tasks like conflict management.
The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.

=== Component Overview ===
USM, EAS and OX work together as components. This is a general outline about how these components interact.

When the device initiates a synchronization through ActiveSync, it contacts the webserver using the URL /Microsoft-Server-ActiveSync via HTTP/s. This URL is forwarded to the Open-Xchange application server where the corresponding servlet is offered by the EAS component. The EAS component then uses USM to initiate a connection to the OX HTTP API and exchanges groupware data. In all cases, USM works as an client to the Open-Xchange HTTP API. It also uses some database tables which are accessed through the Open-Xchange SQL interface to store metadata like synchronization status. The same component stack is used to transport groupware data back to the device.

=== Requirements ===

Since the Connector for Business Mobility is a server plug-in based on the OSGi Framework it can be added to an existing Open-Xchange installation very easily. '''OX App Suite v7.0 or later is required to operate this extension.''' The Connector for Business Mobility uses the resources and services offered by the Open-Xchange server, no additional software or configuration is required.

* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_6.0 | Debian 6.0 (Squeeze)]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES11 | SLES11]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6 | RHEL6]]

'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article [[AppSuite:UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.

== Installation ==

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|usm|mobilityconnector}}

$ yum install open-xchange-meta-mobility

=== Debian GNU/Linux 6.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianSqueeze|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|usm|mobilityconnector}}

$ apt-get update
$ apt-get install open-xchange-meta-mobility

=== SUSE Linux Enterprise Server 11 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|usm|mobilityconnector}}

$ zypper ref
$ zypper install open-xchange-meta-mobility

Now the Open-Xchange service needs to be restarted:

/etc/init.d/open-xchange restart

On the first login after the restart, all required database tables will be created.

== Download and Installation OX Server Edition / App Suite for UCS ==

If you have purchased the OX Server Edition / App Suite for UCS, the Connector is part of the offering. Installation of the Connector with the following steps:

* The new license is already registered at the LDB after purchase
* Click on "Online Updates" at the Univention Management Console
* The Connector for Business Mobility is available at the "Open-Xchange Components"

== Configuration ==

=== Mail Push ===

In order to get mail push, either install and configure the package open-xchange-push-malpoll, which is not recommended on large deployments or if you're using cyrus-imap, read the [[MailNotify Bundle‎‎]] instructions on how to set up real mail push with cyrus.

=== Open-Xchange configuration ===
The configuration for USM and the EAS protocol can be found in these two configuration files:
/opt/open-xchange/etc/usm.properties
/opt/open-xchange/etc/eas.properties

Make sure that the Open-Xchange Server URL is set properly in usm.properties. This needs to be the machine which provides the web interface. Usually, this is localhost, as the webserver and Open-Xchange run on the same machine.
com.openexchange.usm.ox.url=http://localhost/ajax/

in case webserver and Open-Xchange aren't running on the same machine:
com.openexchange.usm.ox.url=http://$FQDN/ajax/
(Where $FQDN is the fully qualified domain name of your frontend system)

On clustered setups, adjust the file
/opt/open-xchange/etc/groupware/noipcheck.cnf
to include the range of IP addresses of the servers on which USM is running.

Documentation about the configuration parameters can be found inside the configuration files. If you change any attribute at the configuration files, the Open-Xchange groupware service needs to be restarted.

=== Apache Configuration ===
Mobile devices supporting ActiveSync use a special URL to communicate with an ActiveSync enabled Open-Xchange Server. This URL needs to be forwarded to the Open-Xchange ActiveSync servlet. The required configuration options are already part of the default Open-Xchange installation instructions.

The example assumes that Open-Xchange Server is running on the same machine like the webserver. Please refer the Open-Xchange administration documentation for more information about Apache configuration. Please restart apache after performing the configuration change.
/etc/init.d/apache2 restart

=== Enabling ActiveSync for user accounts ===
In order to use synchronization through ActiveSync, this feature needs to be activated for user accounts. You can either activate it for specific users or a whole context.

Activating ActiveSync for specific users:
/opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --access-usm on --access-active-sync on

Activating ActiveSync for a whole context:
/opt/open-xchange/sbin/changecontext -c 1 -A oxadminmaster -P admin_master_password --access-usm on --access-active-sync on

== Log files and issue tracking ==
When facing problems with synchronization, there are several ways to get more information than provided via device or platform specific error codes.

=== Open-Xchange Server logfile ===
By default, the log output is non verbose. Only severe errors will be logged. To enable a more detailed log output, the logging mechanism needs to be configured. This depends on the used mechanism.

=== Commons Logging ===
This is the default logging mechanism. If the Open-Xchange Server log output is written to ''var/log/open-xchange/open-xchange.log'' it's an indicator that this mechanism is in use. To make the log output more verbose, add the following parameter:

vim /opt/open-xchange/etc/groupware/file-logging.properties
[...]
com.openexchange.usm.level=FINE

This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.

=== Log4j ===
If the package ''open-xchange-log4j'' is installed, Open-Xchange Server will log via a UDP network socket. In most cases a syslog daemon is listening to this socket and will write the log data to a platform specif file like ''/var/log/syslog''. To make the log output more verbose, add the following parameter:

vim /opt/open-xchange/etc/log4j.xml
[...]
<category name="com.openexchange.usm">
<level value="DEBUG"/>
<appender-ref ref="SERVER_LOG"/>
</category>

Please note that the XML syntax must be correct. This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.

=== EAS debug logfile ===
While the generic Open-Xchange Server log file will keep track on errors reported by the software components, the EAS debug log file will print all data transfered to the device as XML. Please note: this log file may contain confidential data about the users personal groupware objects. Make sure that no unauthorized access to those log files is possible in order to maintain privacy. Change the configuration file accordingly and set a output path which can only accessed by authorized persons.

vim /opt/open-xchange/etc/eas.properties
[...]
com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log

This will enable a XML based debug log for all EAS connections, after restarting Open-Xchange Server.

=== Network traffic ===
When using unencrypted connections between the device and USM and USM and Open-Xchange Server (not recommended), it's possible to analyze the network traffic with tools like ngrep or wireshark. When using encrypted data connections using SSL, the transfered data can be decrypted using the corresponding private key. Please note that there are two network streams, one from the device to USM (external) and one from USM to OX (internal).

== Bug-Reporting ==
Please report bugs via the Open-Xchange Bugzilla:

[https://bugs.open-xchange.com/ Direct link to Open-Xchange Bugzilla]

* Product: Connector for Business Mobility

= Client configuration =

Information about the client configuration for the different devices is available at the [http://software.open-xchange.com/products/appsuite/doc/mobilityconnector/ User Guides].

= Known Issues =

* The Exchange Active Sync protocol does not support the synchronization of client email drafts-folder to the server. Synchronization from server drafts-folder to the client will work.

[[Category: AppSuite]]

AppSuite:Connector for Business Mobility Installation Guide

2014-03-12T08:45:51Z

Usman.ahmad: /* EAS debug logfile */

= Open-Xchange Connector for Business Mobility =

== Components ==

With the Connector for Business Mobility, Open-Xchange also introduces the Universal Synchronization Module (USM). This module provides a framework for synchronization protocols such as Microsoft Exchange ActiveSync (EAS) or other services building on this foundation. USM acts as a layer between the Open-Xchange HTTP API and the synchronization protocol. It handles synchronization specific tasks like conflict management.
The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.

=== Component Overview ===
USM, EAS and OX work together as components. This is a general outline about how these components interact.

When the device initiates a synchronization through ActiveSync, it contacts the webserver using the URL /Microsoft-Server-ActiveSync via HTTP/s. This URL is forwarded to the Open-Xchange application server where the corresponding servlet is offered by the EAS component. The EAS component then uses USM to initiate a connection to the OX HTTP API and exchanges groupware data. In all cases, USM works as an client to the Open-Xchange HTTP API. It also uses some database tables which are accessed through the Open-Xchange SQL interface to store metadata like synchronization status. The same component stack is used to transport groupware data back to the device.

=== Requirements ===

Since the Connector for Business Mobility is a server plug-in based on the OSGi Framework it can be added to an existing Open-Xchange installation very easily. '''OX App Suite v7.0 or later is required to operate this extension.''' The Connector for Business Mobility uses the resources and services offered by the Open-Xchange server, no additional software or configuration is required.

* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_6.0 | Debian 6.0 (Squeeze)]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES11 | SLES11]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6 | RHEL6]]

'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article [[AppSuite:UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.

== Installation ==

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|usm|mobilityconnector}}

$ yum install open-xchange-meta-mobility

=== Debian GNU/Linux 6.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianSqueeze|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|usm|mobilityconnector}}

$ apt-get update
$ apt-get install open-xchange-meta-mobility

=== SUSE Linux Enterprise Server 11 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|usm|mobilityconnector}}

$ zypper ref
$ zypper install open-xchange-meta-mobility

Now the Open-Xchange service needs to be restarted:

/etc/init.d/open-xchange restart

On the first login after the restart, all required database tables will be created.

== Download and Installation OX Server Edition / App Suite for UCS ==

If you have purchased the OX Server Edition / App Suite for UCS, the Connector is part of the offering. Installation of the Connector with the following steps:

* The new license is already registered at the LDB after purchase
* Click on "Online Updates" at the Univention Management Console
* The Connector for Business Mobility is available at the "Open-Xchange Components"

== Configuration ==

=== Mail Push ===

In order to get mail push, either install and configure the package open-xchange-push-malpoll, which is not recommended on large deployments or if you're using cyrus-imap, read the [[MailNotify Bundle‎‎]] instructions on how to set up real mail push with cyrus.

=== Open-Xchange configuration ===
The configuration for USM and the EAS protocol can be found in these two configuration files:
/opt/open-xchange/etc/usm.properties
/opt/open-xchange/etc/eas.properties

Make sure that the Open-Xchange Server URL is set properly in usm.properties. This needs to be the machine which provides the web interface. Usually, this is localhost, as the webserver and Open-Xchange run on the same machine.
com.openexchange.usm.ox.url=http://localhost/ajax/

in case webserver and Open-Xchange aren't running on the same machine:
com.openexchange.usm.ox.url=http://$FQDN/ajax/
(Where $FQDN is the fully qualified domain name of your frontend system)

On clustered setups, adjust the file
/opt/open-xchange/etc/groupware/noipcheck.cnf
to include the range of IP addresses of the servers on which USM is running.

Documentation about the configuration parameters can be found inside the configuration files. If you change any attribute at the configuration files, the Open-Xchange groupware service needs to be restarted.

=== Apache Configuration ===
Mobile devices supporting ActiveSync use a special URL to communicate with an ActiveSync enabled Open-Xchange Server. This URL needs to be forwarded to the Open-Xchange ActiveSync servlet. The required configuration options are already part of the default Open-Xchange installation instructions.

The example assumes that Open-Xchange Server is running on the same machine like the webserver. Please refer the Open-Xchange administration documentation for more information about Apache configuration. Please restart apache after performing the configuration change.
/etc/init.d/apache2 restart

=== Enabling ActiveSync for user accounts ===
In order to use synchronization through ActiveSync, this feature needs to be activated for user accounts. You can either activate it for specific users or a whole context.

Activating ActiveSync for specific users:
/opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --access-usm on --access-active-sync on

Activating ActiveSync for a whole context:
/opt/open-xchange/sbin/changecontext -c 1 -A oxadminmaster -P admin_master_password --access-usm on --access-active-sync on

== Log files and issue tracking ==
When facing problems with synchronization, there are several ways to get more information than provided via device or platform specific error codes.

=== Open-Xchange Server logfile ===
By default, the log output is non verbose. Only severe errors will be logged. To enable a more detailed log output, the logging mechanism needs to be configured. This depends on the used mechanism.

=== Commons Logging ===
This is the default logging mechanism. If the Open-Xchange Server log output is written to ''var/log/open-xchange/open-xchange.log'' it's an indicator that this mechanism is in use. To make the log output more verbose, add the following parameter:

vim /opt/open-xchange/etc/groupware/file-logging.properties
[...]
com.openexchange.usm.level=FINE

This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.

=== Log4j ===
If the package ''open-xchange-log4j'' is installed, Open-Xchange Server will log via a UDP network socket. In most cases a syslog daemon is listening to this socket and will write the log data to a platform specif file like ''/var/log/syslog''. To make the log output more verbose, add the following parameter:

vim /opt/open-xchange/etc/groupware/log4j.xml
[...]
<category name="com.openexchange.usm">
<level value="DEBUG"/>
<appender-ref ref="SERVER_LOG"/>
</category>

Please note that the XML syntax must be correct. This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.

=== EAS debug logfile ===
While the generic Open-Xchange Server log file will keep track on errors reported by the software components, the EAS debug log file will print all data transfered to the device as XML. Please note: this log file may contain confidential data about the users personal groupware objects. Make sure that no unauthorized access to those log files is possible in order to maintain privacy. Change the configuration file accordingly and set a output path which can only accessed by authorized persons.

vim /opt/open-xchange/etc/eas.properties
[...]
com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log

This will enable a XML based debug log for all EAS connections, after restarting Open-Xchange Server.

=== Network traffic ===
When using unencrypted connections between the device and USM and USM and Open-Xchange Server (not recommended), it's possible to analyze the network traffic with tools like ngrep or wireshark. When using encrypted data connections using SSL, the transfered data can be decrypted using the corresponding private key. Please note that there are two network streams, one from the device to USM (external) and one from USM to OX (internal).

== Bug-Reporting ==
Please report bugs via the Open-Xchange Bugzilla:

[https://bugs.open-xchange.com/ Direct link to Open-Xchange Bugzilla]

* Product: Connector for Business Mobility

= Client configuration =

Information about the client configuration for the different devices is available at the [http://software.open-xchange.com/products/appsuite/doc/mobilityconnector/ User Guides].

= Known Issues =

* The Exchange Active Sync protocol does not support the synchronization of client email drafts-folder to the server. Synchronization from server drafts-folder to the client will work.

[[Category: AppSuite]]

OX6:Open-Xchange Installation Guide for CentOS 6 622

2014-02-24T14:50:28Z

Usman.ahmad: /* MySQL */

= Open-Xchange Server 6 (v6.22) on CentOS6 Linux =

{{QuickInstIntro|release=6}}

'''Important: This installation guide will only work for v6.22. If you want to install v6.20 please use the [http://oxpedia.org/wiki/index.php?title=Open-Xchange_Installation_Guide_for_CentOS_6 installation guide for earlier versions].'''

= Requirements =

* Plain installed CentOS6 with latest updates
* A configured internet connection
* httpd - Apache web server

{{AddReposRHEL|rhelname=RHEL6|release=6.22}}

= Updating repositories and installing packages =

Reload the package index. This will download the package descriptions available at the software repositories:

$ yum update

The following command starts the download and installation process of all required package for Open-Xchange deployment:

{{OXPackageInstallation|installer=yum|mysql=mysql-server|javavendor=sun|release=6.22}}

{{OXConfiguration|mysqlstart=/etc/init.d/mysqld start}}

{{oxinstaller|connector=http}}

After initializing the configuration, start the Open-Xchange service by executing:

$ /etc/init.d/open-xchange start

{{OXRegister}}

= Configure services =
Now as the Open-Xchange Server has been set up and the database is running, we have to configure the Apache webserver and the mod_proxy_ajp module to access the groupware frontend. To gain better GUI performance, the usage of ''mod_expires'' and ''mod_deflate'' is strongly recommended. Those modules will limit the amount of client requests and compress the delivered content. The default installation of the Apache webserver on CentOS provides a welcome screen which is not necessary for server operation, it can be removed by deleting the corresponding configuration file:

$ rm /etc/httpd/conf.d/welcome.conf

{{Template:ApacheOXConf|connector=http|connectorConf=/etc/httpd/conf.d/proxy_http.conf|apacheconf= /etc/httpd/conf.d/ox.conf|docroot=/var/www/html|release=6.22|loadmodule=LoadModule proxy_http_module modules/mod_proxy_http.so|easProxyName=eas_oxcluster}}

After the configuration is done, restart the Apache webserver

$ /etc/init.d/httpd restart

= Adding services to runlevels =

The new services are now installed and configured, but to make them start up on a server boot, they need to be added to some runlevels:

$ chkconfig --level 345 mysqld on
$ chkconfig --level 345 httpd on
$ chkconfig --level 345 open-xchange on

= Creating contexts and users =
Now as the whole setup is complete and you already should get a login screen when accessing the server with a webbrowser, we have to setup a context and a default user as the last step of this tutorial.

The mapping ''defaultcontext'' will allow you to set this context as the default one of the entire system so that users which will be created within this context can login into Open-Xchange Server without specifying their domain at the login screen. Only one context can be specified as ''defaultcontext''. The ''oxadmin'' user that will be created by this command is the default admin of the created context. This account will gather additional functions that are also described in the administration manual. The ''context id'' parameter must to be unique and numeric, otherwise the server will complain when you try to create a context. New contexts must be created by the ''oxadminmaster'' user, user accounts inside a context are created with the credentials of the contexts ''oxadmin'' account. The ''access-combination-name'' property defines the set of available modules and functions for users of the context.

$ /opt/open-xchange/sbin/createcontext -A oxadminmaster -P admin_master_password -c 1 \
-u oxadmin -d "Context Admin" -g Admin -s User -p secret -L defaultcontext \
-e oxadmin@example.com -q 1024 --access-combination-name=all

Create a user for testing purposes:

$ /opt/open-xchange/sbin/createuser -c 1 -A oxadmin -P secret -u testuser \
-d "Test User" -g Test -s User -p secret -e testuser@example.com \
--imaplogin testuser --imapserver 127.0.0.1 --smtpserver 127.0.0.1

Now connect to the server with a webbrowser and login using the credentials testuser / secret.

= Log files and issue tracking =

Whenever unexpected or erroneous behavior takes place, it will be logged depending on the configured loglevel. All logfiles are stored at the operating systems default location. Events triggered by the Open-Xchange Groupware services are logged to a rotating file ''open-xchange.log'', events triggered by the Open-Xchange Administration service are logged to ''open-xchange-admin.log''. Those files are the very first place to monitor.

$ tail -f -n200 /var/log/open-xchange/open-xchange.log.0

= Performance & Tuning Tips =
Depending on your setup and the user accounts, it´s often helpful to know, how to get a better performance from the complete system. This section will try to assist you, how to tune the components within an OX setup, before you need to install a second server, add more RAM, add new CPU to existing servers.

== MySQL ==
Since OX itself used very specific features from MySQL like InnoDB instead of MyISAM as DB Engine, it´s often needed, how to increase performance of the OX databases. In general, you should always monitor your MySQL system via tools like "munin", to see when your system reaches it´s limits. Once, you recognized, the system responds more and more slowly, you start to read and research on the internet how to change your mysql configuration, specially, the my.cnf file. But due to the fact, that nearly every system is different in regards of hardware etc. you cannot just copy&paste existing configurations. At this point, a tool called "mysqltuner.pl" can help you. MySQLTuner is a script written in Perl that will assist you with your MySQL configuration and make recommendations for increased performance and stability. Within seconds, it will display statistics about your MySQL installation and the areas where it can be improved. To work with this tool, you need unrestricted read access to the MySQL server (OS root access is recommended). Just download and execute as shown below, and modify your existing my.cnf configuration file.

IMPORTANT INFO: The MySQL system must run for several days, to gather statistics and informations about queries etc. from OX. After these days, you should execute mysqltuner.pl script. It does not work if you run it directly after installing an OX/MySQL setup. You can force traffic to OX while writing automatic testcases or jmeter plans.

As already said, this is just ONE way to analyze MySQL systems. You can also check MYSQL.com for a consultant service or similar.

$ wget https://raw.github.com/major/MySQLTuner-perl/master/mysqltuner.pl

Make the PERL script executable:

<pre>
$ chmod +x mysqltuner.pl
</pre>

Execute the PERL script:

<pre>
$ ./mysqltuner.pl
</pre>

If prompted, enter your MySQL credentials and read carefully through the complete output of the script. Now you have very good informations, how to change your mysql system.

[[Category: OX6]]

AppSuite:Syslog Configuration

2013-02-15T15:30:34Z

Usman.ahmad: /* SUSE Linux Enterprise Server 11 */

=Open-Xchange Syslog Configuration=

==Abstract==
Open-Xchange provides OSGi packages (''open-xchange-log4j'' and ''open-xchange-commons-logging-log4j'') to enable remote logging via syslog. This is useful for distributed setups or if a logging strategy is already present at the environments the servers are running. If you choose syslog to be the logging mechanism, the syslog service needs some configuration to accept remote logging, even if the service is running on localhost.

The syslog remote logging will open port 514/udp, so don't forget to firewall it properly if it's a security risk for you. The default logging facility of Open-Xchange is defined at the ''/opt/open-xchange/{groupware,admindaemon}/etc/log4j.xml'' file. For more granular log filtering this facility can be changed. Please refer to the syslog and syslog-ng documentation for further information.

{{InstallPlugin|pluginname=open-xchange-log4j|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

== Configuration ==
Please note, there are numerous syslog daemons available and the configuration may also differ between Linux distributions. To make open-xchange-log4j running in collaboration with the syslog
daemon of your choice, you have to enable logging via UDP protocol and listening port 514. Please
read for details the documentation of your running syslog service.
=== For RHEL and CentOS ===
Here are the documentation steps for the popular rsyslod service.
The parameter configuration is now completely done at a configuration file at ''/etc/rsyslog.conf''

# provides UDP syslog reception
$ModLoad imudp
$UDPServerRun 514

Then restart the rsyslog service to enable remote logging.
$ /etc/init.d/rsyslog restart

By default, all Open-Xchange log messages are put to ''/var/log/syslog''.

===For SUSE Linux Enterprise Server 11 ===
SLES11 comes up with syslog-ng, modify the configuration at ''/etc/syslog-ng/syslog-ng.conf'':

source src {
#
# include internal syslog-ng messages
# note: the internal() soure is required!
#
internal();

#
# the default log socket for local logging:
#
unix-dgram("/dev/log");

#
# uncomment to process log messages from network:
#
udp(ip("0.0.0.0") port(514));
};

Uncomment the last statement of the src definition and restart the syslog service to enable logging.
$ /etc/init.d/syslog restart

By default, all Open-Xchange log messages are put to ''/var/log/messages''.

[[Category: OX6]]

AppSuite:Syslog Configuration

2013-02-15T15:29:10Z

Usman.ahmad: /* rsyslod */

=Open-Xchange Syslog Configuration=

==Abstract==
Open-Xchange provides OSGi packages (''open-xchange-log4j'' and ''open-xchange-commons-logging-log4j'') to enable remote logging via syslog. This is useful for distributed setups or if a logging strategy is already present at the environments the servers are running. If you choose syslog to be the logging mechanism, the syslog service needs some configuration to accept remote logging, even if the service is running on localhost.

The syslog remote logging will open port 514/udp, so don't forget to firewall it properly if it's a security risk for you. The default logging facility of Open-Xchange is defined at the ''/opt/open-xchange/{groupware,admindaemon}/etc/log4j.xml'' file. For more granular log filtering this facility can be changed. Please refer to the syslog and syslog-ng documentation for further information.

{{InstallPlugin|pluginname=open-xchange-log4j|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

== Configuration ==
Please note, there are numerous syslog daemons available and the configuration may also differ between Linux distributions. To make open-xchange-log4j running in collaboration with the syslog
daemon of your choice, you have to enable logging via UDP protocol and listening port 514. Please
read for details the documentation of your running syslog service.
=== For RHEL and CentOS ===
Here are the documentation steps for the popular rsyslod service.
The parameter configuration is now completely done at a configuration file at ''/etc/rsyslog.conf''

# provides UDP syslog reception
$ModLoad imudp
$UDPServerRun 514

Then restart the rsyslog service to enable remote logging.
$ /etc/init.d/rsyslog restart

By default, all Open-Xchange log messages are put to ''/var/log/syslog''.

===SUSE Linux Enterprise Server 11 ===
SLES11 comes with syslog-ng, modify the configuration at ''/etc/syslog-ng/syslog-ng.conf'':

source src {
#
# include internal syslog-ng messages
# note: the internal() soure is required!
#
internal();

#
# the default log socket for local logging:
#
unix-dgram("/dev/log");

#
# uncomment to process log messages from network:
#
udp(ip("0.0.0.0") port(514));
};

Uncomment the last statement of the src definition and restart the syslog service to enable logging.
$ /etc/init.d/syslog restart

By default, all Open-Xchange log messages are put to ''/var/log/messages''.

[[Category: OX6]]

AppSuite:Syslog Configuration

2013-02-15T15:25:21Z

Usman.ahmad: /* rsyslod */

=Open-Xchange Syslog Configuration=

==Abstract==
Open-Xchange provides OSGi packages (''open-xchange-log4j'' and ''open-xchange-commons-logging-log4j'') to enable remote logging via syslog. This is useful for distributed setups or if a logging strategy is already present at the environments the servers are running. If you choose syslog to be the logging mechanism, the syslog service needs some configuration to accept remote logging, even if the service is running on localhost.

The syslog remote logging will open port 514/udp, so don't forget to firewall it properly if it's a security risk for you. The default logging facility of Open-Xchange is defined at the ''/opt/open-xchange/{groupware,admindaemon}/etc/log4j.xml'' file. For more granular log filtering this facility can be changed. Please refer to the syslog and syslog-ng documentation for further information.

{{InstallPlugin|pluginname=open-xchange-log4j|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

== Configuration ==
Please note, there are numerous syslog daemons available and the configuration may also differ between Linux distributions. To make open-xchange-log4j running in collaboration with the syslog
daemon of your choice, you have to enable logging via UDP protocol and listening port 514. Please
read for details the documentation of your running syslog service.
=== rsyslod ===
Here documentation steps for the popular rsyslod.
The parameter configuration is now completely done at a configuration file at ''/etc/rsyslog.conf''

# provides UDP syslog reception
$ModLoad imudp
$UDPServerRun 514

Then restart the rsyslog service to enable remote logging.
$ /etc/init.d/rsyslog restart

By default, all Open-Xchange log messages are put to ''/var/log/syslog''.

===SUSE Linux Enterprise Server 11 ===
SLES11 comes with syslog-ng, modify the configuration at ''/etc/syslog-ng/syslog-ng.conf'':

source src {
#
# include internal syslog-ng messages
# note: the internal() soure is required!
#
internal();

#
# the default log socket for local logging:
#
unix-dgram("/dev/log");

#
# uncomment to process log messages from network:
#
udp(ip("0.0.0.0") port(514));
};

Uncomment the last statement of the src definition and restart the syslog service to enable logging.
$ /etc/init.d/syslog restart

By default, all Open-Xchange log messages are put to ''/var/log/messages''.

[[Category: OX6]]