Open-Xchange - User contributions [en]

AppSuite:Filestorages

2020-08-18T04:57:16Z

Malasa: /* Microsoft Onedrive */ changed azure page link, configuration changed

'''Note:''' you can find updated guides at [https://documentation.open-xchange.com/7.10.2/middleware/3rd_party_integrations.html https://documentation.open-xchange.com/7.10.2/middleware/3rd_party_integrations.html]

This page is only for pre 7.10.2 versions.

= Common preparations =
This page shows how to setup external file stores. For all of these file stores you have to install the package "open-xchange-oauth", which provides the necessary authentication mechanisms.

Moreover your setup is required to be reachable via HTTPS, since the providers expect that a call-back URL to your setup is specified. Such a call-back URL is only accepted if it contains the <source enclose="none" lang="java">"https://"</source> scheme., e.g.:
<syntaxhighlight lang="java">
"https://my.oxsetup.invalid/ajax/defer"
</syntaxhighlight>

== Keep HTTPS protocol ==
[[Appsuite:Grizzly#Cluster_setup]] shows that HTTPS communication is terminated by the Apache balancer in front of the Open-Xchange nodes. To let the Open-Xchange application know about the HTTPS protocol that is used to communicate with the Apache server:
* Either set a special header in the SSL virtual hosts configurations in Apache to forward this information. The de facto standard for this is the <source enclose="none" lang="java">"X-Forwarded-Proto"</source> header. See [[Appsuite:Grizzly#X-FORWARDED-PROTO_Header]] for how to setup that header.
* Or force the Open-Xchange application to assume it is reached via SSL through setting property <source enclose="none" lang="properties">"com.openexchange.forceHTTPS=true"</source> in file ''/opt/open-xchange/etc/server.properties''.

== Deferrer URL ==
Open-Xchange application uses the deferrer URL as call-back for some of the providers, which use OAuth v2.0 authentication (such as Google).

If your OX server is reachable only via one host name, you won't have to do anything. If it is reachable by more than one host name, create or open the file ''/opt/openexchange/etc/deferrer.properties'' and set the properties therein as such:
<syntaxhighlight lang="properties">
com.openexchange.http.deferrer.url=https://mymaindomain.invalid
</syntaxhighlight>

= Dropbox =

To setup the Dropbox file store you have to install the package "open-xchange-file-storage-dropbox".

== Registering your app ==
* Log in to your Dropbox account [https://www.dropbox.com/login here], and create your Dropbox app [https://www.dropbox.com/developers/apps/create here]
* There are two options available creating an app, Drops-in App & Dropbox API App. Please select '''Dropbox API''' app and enter the name of your app.
* Go to [https://www.dropbox.com/developers/apps App Console] and select your created app. Select settings tab to view the <source enclose="none" lang="java">APP_KEY</source> (App key) and <source enclose="none" lang="java">SECRET_KEY</source> (App secret) and to configure the redirect URI to your AppSuite platform under the Oauth2 section. All the other fields can keep their default value.
* Please ensure the following conditions are met for the redirect URI:
** The redirect URI uses <source enclose="none" lang="java">"https://"</source> as protocol
** The redirect URI follows the pattern: <source enclose="none" lang="java">"https://" + <host-name> + "/ajax/defer"</source>
** E.g. <source enclose="none" lang="java">"https://myappsuite.mydomain.invalid/ajax/defer"</source>
<br>

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/dropboxoauth.properties'':

* Enable the OAuth connector to Dropbox OAuth
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox=true
</syntaxhighlight>
<br>

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox.apiKey=REPLACE_THIS_WITH_DROPBOX_APP_KEY
com.openexchange.oauth.dropbox.apiSecret=REPLACE_THIS_WITH_DROPBOX_APP_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL. Please ensure the use the same URL as specified in the Dropbox App:
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox.redirectUrl=
</syntaxhighlight>
<br>

* Set the product ID of the registered Dropbox app
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox.productName=
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-dropbox|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Google Drive =

To setup the Google Drive file store you have to install the package "open-xchange-file-storage-googledrive".

== Registering your app ==
* Sign in to [https://console.developers.google.com/ Google Developers Console] using your Google account
* Please follow [https://developers.google.com/identity/sign-in/web/devconsole-project these] instructions to create a new project with a client ID, which is needed to call the sign-in API
* Enable the following APIs for your project
** BigQuery API
** Calendar API
** Contacts API
** Drive API
** Drive SDK
** Gmail API
** Google Cloud SQL
** Google Cloud Storage
** Google Cloud Storage JSON API
* perform [https://support.google.com/webmasters/answer/35179 Google's site verification]
** you can use any method listed by Google in general
** in case our OXaaS offering is used the HTML tag and HTML file methods are not accessible but the DNS based approach is required
* [[AppSuite:GoogleAppVerification|get your app verified by Google]] to avoid awkward warnings

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/googleoauth.properties'':

* Enable the OAuth connector to Google OAuth
<syntaxhighlight lang="properties">
com.openexchange.oauth.google=true
</syntaxhighlight>
<br>

* Set the API key and secret, which is Client ID and Client Secret to call the sign-in API (Select your project, select API manager from upper left burger menu, select credentials in left side bar, select Client ID for Web application)
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.apiKey=REPLACE_THIS_WITH_YOUR_CLIENT_ID
com.openexchange.oauth.google.apiSecret=REPLACE_THIS_WITH_YOUR_CLIENT_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL. Please ensure the following conditions are met:
** The redirect URL specified in the Google App needs to be the same as the one specified by this property.
** The redirect URI uses <source enclose="none" lang="java">"https://"</source> as protocol
** The redirect URI follows the pattern: <source enclose="none" lang="java">"https://" + <host-name> + "/ajax/defer"</source>
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.redirectUrl=
</syntaxhighlight>
E.g. <source enclose="none" lang="java">"https://myappsuite.mydomain.invalid/ajax/defer"</source>
<br>

* Set the product ID of the registered Google app
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.productName=
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-googledrive|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Microsoft Onedrive =
To setup the Microsoft OneDrive file store you have to install the package "open-xchange-file-storage-onedrive".

== Registering your app ==
* register your app on the [https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade Azure App registration] page
* application ID maps to apiKey in OX properties
* create credentials and copy it to apiSecret
* choose "Web" as platform
* enter the redirect URI/URL, see below
* enter profile data for your application

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/microsoftgraphoauth.properties'' (before 7.10.x ''/opt/open-xchange/etc/msliveconntectoauth.properties''):

* Enable the OAuth connector
<syntaxhighlight lang="properties">
com.openexchange.oauth.microsoft.graph=true
</syntaxhighlight>
<br>

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.microsoft.graph.apiKey=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_CLIENT_KEY
com.openexchange.oauth.microsoft.graph.apiSecret=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_CLIENT_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL
<syntaxhighlight lang="properties">
com.openexchange.oauth.microsoft.graph.redirectUrl=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_REDIRECT_URL
</syntaxhighlight>
<br>

Note: the redirect URL must be the same as defined in the azure app registration, it should be https://<REPLACE_WITH_FQDN>/ajax/defer

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-onedrive|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Box.com =
To setup the Box.com file store you have to install the package "open-xchange-file-storage-boxcom".

== Registering your app ==
* Sign in to [https://developers.box.com/ box Developers]
* Select '''Create a Box Application'''
* Select '''Box Content'''
* Hit '''Configure your application'''
* Enter ''redirect_uri''' (the deferrer URL; e.g. <source enclose="none" lang="java">"https://my.oxsetup.invalid/ajax/defer"</source>)
* Enable ''Read and write all files and folders''

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/boxcomoauth.properties'':

* Enable the OAuth connector
<syntaxhighlight lang="properties">
com.openexchange.oauth.boxcom=true
</syntaxhighlight>
<br>

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.boxcom.apiKey=REPLACE_THIS_WITH_YOUR_BOX_CLIENT_KEY
com.openexchange.oauth.boxcom.apiSecret=REPLACE_THIS_WITH_YOUR_BOX_CLIENT_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL
<syntaxhighlight lang="properties">
com.openexchange.oauth.boxcom.redirectUrl=REPLACE_THIS_WITH_YOUR_BOX_REDIRECT_URL
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-boxcom|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

AppSuite:Filestorages

2020-01-30T11:35:56Z

Malasa: link to doc.o.c

'''Note:''' you can find updated guides at [https://documentation.open-xchange.com/7.10.2/middleware/3rd_party_integrations.html https://documentation.open-xchange.com/7.10.2/middleware/3rd_party_integrations.html]

This page is only for pre 7.10.2 versions.

= Common preparations =
This page shows how to setup external file stores. For all of these file stores you have to install the package "open-xchange-oauth", which provides the necessary authentication mechanisms.

Moreover your setup is required to be reachable via HTTPS, since the providers expect that a call-back URL to your setup is specified. Such a call-back URL is only accepted if it contains the <source enclose="none" lang="java">"https://"</source> scheme., e.g.:
<syntaxhighlight lang="java">
"https://my.oxsetup.invalid/ajax/defer"
</syntaxhighlight>

== Keep HTTPS protocol ==
[[Appsuite:Grizzly#Cluster_setup]] shows that HTTPS communication is terminated by the Apache balancer in front of the Open-Xchange nodes. To let the Open-Xchange application know about the HTTPS protocol that is used to communicate with the Apache server:
* Either set a special header in the SSL virtual hosts configurations in Apache to forward this information. The de facto standard for this is the <source enclose="none" lang="java">"X-Forwarded-Proto"</source> header. See [[Appsuite:Grizzly#X-FORWARDED-PROTO_Header]] for how to setup that header.
* Or force the Open-Xchange application to assume it is reached via SSL through setting property <source enclose="none" lang="properties">"com.openexchange.forceHTTPS=true"</source> in file ''/opt/open-xchange/etc/server.properties''.

== Deferrer URL ==
Open-Xchange application uses the deferrer URL as call-back for some of the providers, which use OAuth v2.0 authentication (such as Google).

If your OX server is reachable only via one host name, you won't have to do anything. If it is reachable by more than one host name, create or open the file ''/opt/openexchange/etc/deferrer.properties'' and set the properties therein as such:
<syntaxhighlight lang="properties">
com.openexchange.http.deferrer.url=https://mymaindomain.invalid
</syntaxhighlight>

= Dropbox =

To setup the Dropbox file store you have to install the package "open-xchange-file-storage-dropbox".

== Registering your app ==
* Log in to your Dropbox account [https://www.dropbox.com/login here], and create your Dropbox app [https://www.dropbox.com/developers/apps/create here]
* There are two options available creating an app, Drops-in App & Dropbox API App. Please select '''Dropbox API''' app and enter the name of your app.
* Go to [https://www.dropbox.com/developers/apps App Console] and select your created app. Select settings tab to view the <source enclose="none" lang="java">APP_KEY</source> (App key) and <source enclose="none" lang="java">SECRET_KEY</source> (App secret) and to configure the redirect URI to your AppSuite platform under the Oauth2 section. All the other fields can keep their default value.
* Please ensure the following conditions are met for the redirect URI:
** The redirect URI uses <source enclose="none" lang="java">"https://"</source> as protocol
** The redirect URI follows the pattern: <source enclose="none" lang="java">"https://" + <host-name> + "/ajax/defer"</source>
** E.g. <source enclose="none" lang="java">"https://myappsuite.mydomain.invalid/ajax/defer"</source>
<br>

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/dropboxoauth.properties'':

* Enable the OAuth connector to Dropbox OAuth
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox=true
</syntaxhighlight>
<br>

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox.apiKey=REPLACE_THIS_WITH_DROPBOX_APP_KEY
com.openexchange.oauth.dropbox.apiSecret=REPLACE_THIS_WITH_DROPBOX_APP_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL. Please ensure the use the same URL as specified in the Dropbox App:
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox.redirectUrl=
</syntaxhighlight>
<br>

* Set the product ID of the registered Dropbox app
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox.productName=
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-dropbox|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Google Drive =

To setup the Google Drive file store you have to install the package "open-xchange-file-storage-googledrive".

== Registering your app ==
* Sign in to [https://console.developers.google.com/ Google Developers Console] using your Google account
* Please follow [https://developers.google.com/identity/sign-in/web/devconsole-project these] instructions to create a new project with a client ID, which is needed to call the sign-in API
* Enable the following APIs for your project
** BigQuery API
** Calendar API
** Contacts API
** Drive API
** Drive SDK
** Gmail API
** Google Cloud SQL
** Google Cloud Storage
** Google Cloud Storage JSON API
* perform [https://support.google.com/webmasters/answer/35179 Google's site verification]
** you can use any method listed by Google in general
** in case our OXaaS offering is used the HTML tag and HTML file methods are not accessible but the DNS based approach is required
* [[AppSuite:GoogleAppVerification|get your app verified by Google]] to avoid awkward warnings

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/googleoauth.properties'':

* Enable the OAuth connector to Google OAuth
<syntaxhighlight lang="properties">
com.openexchange.oauth.google=true
</syntaxhighlight>
<br>

* Set the API key and secret, which is Client ID and Client Secret to call the sign-in API (Select your project, select API manager from upper left burger menu, select credentials in left side bar, select Client ID for Web application)
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.apiKey=REPLACE_THIS_WITH_YOUR_CLIENT_ID
com.openexchange.oauth.google.apiSecret=REPLACE_THIS_WITH_YOUR_CLIENT_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL. Please ensure the following conditions are met:
** The redirect URL specified in the Google App needs to be the same as the one specified by this property.
** The redirect URI uses <source enclose="none" lang="java">"https://"</source> as protocol
** The redirect URI follows the pattern: <source enclose="none" lang="java">"https://" + <host-name> + "/ajax/defer"</source>
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.redirectUrl=
</syntaxhighlight>
E.g. <source enclose="none" lang="java">"https://myappsuite.mydomain.invalid/ajax/defer"</source>
<br>

* Set the product ID of the registered Google app
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.productName=
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-googledrive|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Microsoft Onedrive =
To setup the Microsoft OneDrive file store you have to install the package "open-xchange-file-storage-onedrive".

== Registering your app ==
* Please follow [https://msdn.microsoft.com/en-us/library/ff751474.aspx this guide] to create/register your app
* application ID maps to apiKey in OX properties
* create credentials and copy it to apiSecret
* choose "Web" as platform
* enter the redirect URL according to the instruction in msliveconnectoauth.properties
* enter profile data for your application

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/msliveconntectoauth.properties'':

* Enable the OAuth connector
<syntaxhighlight lang="properties">
com.openexchange.oauth.msliveconnect=true
</syntaxhighlight>
<br>

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.msliveconnect.apiKey=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_CLIENT_KEY
com.openexchange.oauth.msliveconnect.apiSecret=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_CLIENT_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL
<syntaxhighlight lang="properties">
com.openexchange.oauth.msliveconnect.redirectUrl=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_REDIRECT_URL
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-onedrive|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Box.com =
To setup the Box.com file store you have to install the package "open-xchange-file-storage-boxcom".

== Registering your app ==
* Sign in to [https://developers.box.com/ box Developers]
* Select '''Create a Box Application'''
* Select '''Box Content'''
* Hit '''Configure your application'''
* Enter ''redirect_uri''' (the deferrer URL; e.g. <source enclose="none" lang="java">"https://my.oxsetup.invalid/ajax/defer"</source>)
* Enable ''Read and write all files and folders''

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/boxcomoauth.properties'':

* Enable the OAuth connector
<syntaxhighlight lang="properties">
com.openexchange.oauth.boxcom=true
</syntaxhighlight>
<br>

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.boxcom.apiKey=REPLACE_THIS_WITH_YOUR_BOX_CLIENT_KEY
com.openexchange.oauth.boxcom.apiSecret=REPLACE_THIS_WITH_YOUR_BOX_CLIENT_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL
<syntaxhighlight lang="properties">
com.openexchange.oauth.boxcom.redirectUrl=REPLACE_THIS_WITH_YOUR_BOX_REDIRECT_URL
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-boxcom|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

Template:OXLoadBalancingClustering Database

2019-10-08T19:01:06Z

Malasa: typo ist

== Overview ==

You can choose between Galera or Master/Slave replication. We like to recommend to use Galera for higher redudancy, easier operations, und synchronous semantics (so you can run OX without our "replication monitor"). For POC or demo setups, a single standalone database setup might be sufficient.

== Standalone database setup ==

=== Preparations ===

Our configuration process includes wiping and reinitializing the datadir. This is usually not a problem in a fresh installation. If you want to upgrade an existing database server, please be prepared to wipe the datadir, i.e. take a <code>mysqldump</code> for later restoration into the properly configured master.

mysqldump --databases configdb oxdb_{5..14} > backup.sql

Be sure to verify the list of databases.

=== Installation ===

Note: the following list is not an exclusive list or authorative statement about supported MySQL flavors / versions. Please consult the official support / system requirements statement.

Please follow the upstream docs for your preferred flavor to get the software installed on your system.

* MariaDB (10.1, 10.2): https://downloads.mariadb.org/
* Oracle MySQL Community Server (5.6, 5.7): https://dev.mysql.com/downloads/mysql/

Make sure to doublecheck the service is not running (or stop it) after installation as we need to perform some reconfigurations.

service mysql stop

=== Configuration ===

MySQL configuration advise is given in our [[My.cnf|MySQL configuration article]]. Please consult that page for configuration information and create configuration files as described there.

Some settings we recommend to change require that the database gets re-initialized. We assume you don't have data there (since we are covering a fresh install) or you have taken a backup for later restore as explained above in the Preparations section.

cd /var/lib/
mv mysql mysql.old.datadir
mkdir mysql
chown mysql.mysql mysql

# mariadb
mysql_install_db
# mariadb 10.2
mysql_install_db --user=mysql
# oracle 5.6
mysql_install_db -u mysql
# oracle 5.7
mysqld --initialize-insecure --user=mysql

(Don't be worried about the <code>insecure</code>, it just means we set the db root pw in the next steps.)

Start the service. The actual command depends on your OS and on the MySQL flavor.

service mysql start

Run <code>mysql_secure_installation</code> for a "secure by default" installation:

mysql_secure_installation

That tool will ask for the current root password (which is empty by default) and subsequently questions like:

Change the root password? [Y/n]
Remove anonymous users? [Y/n]
Disallow root login remotely? [Y/n]
Remove test database and access to it? [Y/n]
Reload privilege tables now? [Y/n]

You should answer all these questions with "yes".

Configure a strong password for the MySQL <code>root</code> user.

The further steps in this guide omit <code>-u -p</code> arguments to the MySQL client. Rather than passing them on the command line [https://dev.mysql.com/doc/refman/5.7/en/password-security-user.html] it is recommended to place the credentials in a file like <code>/root/.my.cnf</code> like

[client]
user=root
password=wip9Phae3Beijeed

Make sure the service is enabled by the OS's init system. The actual command depends on your OS and on the MySQL flavor.

systemctl enable mysql.service

You should now be able to restore your previously taken backup.

# If you took a dump for restore before
mysql < backup.sql

=== Configure OX to use with a standalone database ===

Not much special wisdom here. OX was designed to be used with master/slave databases, and a standalone master works just as well, if we register it as a master, and not registering a slave.

For the ConfigDB, <code>configdb.properties</code> allows configuration of a <code>writeUrl</code> (which is set to the correct values if you use <code>oxinstaller</code> with the correct argument <code>--configdb-writehost</code>).

The single database is then used for reading and writing.

For the individiual UserDBs, use <code>registerdatabase -m true</code>.

== Galera database setup ==

=== Preparations ===

Our configuration process includes wiping and reinitializing the datadir. This is usually not a problem in a fresh installation. If you want to upgrade an existing database to Galera cluster, please be prepared to wipe the datadir, i.e. take a <code>mysqldump</code> for later restoration into the properly configured master.

Depeding on the flavor of the current database, this can be something like

# mariadb or oracle mysql without GTIDs
mysqldump --databases configdb oxdb_{5..14} > backup.sql

# mysql 5.6 with GTIDs... we dont want GTIDs here
mysqldump --databases --set-gtid-purged=OFF configdb oxdb_{5..14} > backup.sql

Be sure to verify the list of databases.

=== Installation ===

Please follow the upstream docs for your preferred flavor to get the software installed on your system.

* Percona XtraDB Cluster (5.6, 5.7): https://www.percona.com/doc/percona-xtradb-cluster/LATEST/install/index.html
* MariaDB Galera Cluster (10.0, 10.1): https://mariadb.com/kb/en/library/getting-started-with-mariadb-galera-cluster/ (Note: with 10.0, socat is required, but not a package dependency, so you need to explicitly install also socat)

Make sure to doublecheck the service is not running (or stop it) after installation as we need to perform some reconfigurations.

service mysql stop

=== Configuration ===

Galera-specific MySQL configuration advise is included in our main [[My.cnf|MySQL configuration article]]. Please consult that page for configuration information.

That page suggests a setup were we add three custom config files to <code>/etc/mysql/ox.conf.d/</code>: <code>ox.cnf</code> for general tuning/sizing, <code>wsrep.cnf</code> for clusterwide galera configuration, and <code>host.cnf</code> for host-specific settings.

Adjust the general settings and tunings in <code>ox.cnf</code> according to your sizing etc.

Adjust <code>wsrep.cnf</code> to reflect local paths, cluster member addresses, etc.

Adjust <code>host.cnf</code> to give node-local IPs, etc.

Version-specific hints:

# percona 5.6: unknown variable 'pxc_strict_mode=ENFORCING' ... unset that one
# mariadb 10.1: add wsrep_on=ON
# mariadb 10.0 and 10.1: set wsrep_node_incoming_address=192.168.1.22:3306 in host.cnf, otherwise the status wsrep_incoming_addresses might not be shown correctly(?!)

Some settings we recommend to change require that the database gets re-initialized. We assume you don't have data there (since we are covering a fresh install) or you have taken a backup for later restore as explained above in the Preparations section.

cd /var/lib/
mv mysql mysql.old.datadir
mkdir mysql
chown mysql.mysql mysql

# mariadb 10.0 and 10.1
mysql_install_db
# mariadb 10.2
mysql_install_db --user=mysql
# percona 5.6
mysqld --user=mysql
# percona 5.7
mysqld --initialize-insecure --user=mysql

(Don't be worried about the <code>insecure</code>, it just means we set the db root pw in the next steps.)

=== Cluster startup ===

Typically on startup a Galera node tries to join a cluster, and if it fails, it will exit. Thus, when no cluster nodes are running, the first cluster node to be started needs to be told to not try to join a cluster, but rather bootstrap a new cluster. The exact arguments vary from version to version and from flavor to flavor.

==== First node ====

So we initialize the cluster bootstrap on the first node:

# percona 5.6, 5.7
service mysql bootstrap-pxc
# mariadb 10.0
service mysql bootstrap
# mariadb 10.1, 10.2
galera_new_cluster

Run <code>mysql_secure_installation</code> for a "secure by default" installation:

mysql_secure_installation

The further steps in this guide omit <code>-u -p</code> arguments to the MySQL client. Rather than passing them on the command line [https://dev.mysql.com/doc/refman/5.7/en/password-security-user.html] it is recommended to place the credentials in a file like <code>/root/.my.cnf</code> like

[client]
user=root
password=wip9Phae3Beijeed

We need a Galera replication user:

CREATE USER 'sstuser'@'localhost' IDENTIFIED BY 'OpIdjijwef0';
-- percona 5.6, mariadb 10.0
GRANT RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'sstuser'@'localhost';
-- percona 5.7, mariadb 10.1, 10.2
GRANT PROCESS, RELOAD, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'sstuser'@'localhost';
FLUSH PRIVILEGES;

(Debian specific note: MariaDB provided startup scripts use the distro's mechanism of verifying startup/shutdown using a system user, so we create that as well:

# mariadb 10.0, 10.1, 10.2
GRANT ALL PRIVILEGES ON *.* TO "debian-sys-maint"@"localhost" IDENTIFIED BY "adBexthTsI5TaEps";

If you do this, yo need to synchronize the <code>/etc/mysql/debian.cnf</code> file from the first node to the other nodes as well.)

==== Other nodes ====

On the other nodes, we only need to restart the service now, to trigger a full state transfer from the first node to the other nodes.

We recommend to do this serially to let one state transfer complete before the second state transfer.

==== First node (continued) ====

Only applicable if you used <code>galera_new_cluster</code> before rather than the service script: In order to get the systemctl status consistent, restart the service on the first node:

# mariadb 10.1, 10.2: restart the service so that the systemctl status is consistent
mysqladmin shutdown
service mysql bootstrap

=== Verify the replication ===

The key tool to verify replication status is

mysql> show status like "%wsrep%";

This will give a lot of output. You want to verify in particular

+------------------------------+--------------------------------------+
| Variable_name | Value |
+------------------------------+--------------------------------------+
| wsrep_cluster_size | 3 |
| wsrep_cluster_status | Primary |
| wsrep_local_state | 4 |
| wsrep_local_state_comment | Synced |
| wsrep_ready | ON |
+------------------------------+--------------------------------------+

You can also explicitly verify replication by creating / inserting DBs, tables, rows on one node and select on other nodes.

==== 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
* SST fails due to missing / wrong version prerequisite packages (not everything is hardcoded in package dependencies -- make sure you got percona-xtrabackup installed in the correct version, and also socat). If SST fails, do not only look into mysqls primary error logs, but also into logfiles from the SST tool in /var/lib/mysql on the donor 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 not configure one Galera node's IP address directly, but rather employ some HA solution which offers active-passive functionality. Options therefore are discussed below.

==== Read requests ====

Read requests can be directed to any node in the Galera cluster. Our standard approach is to recommend to use a loadbalancer to implement round-robin over all nodes in a Galera cluster for the read requests. But you can also chose to use a dedicated read node (the same node, or a different node, than the write node). Each of the approaches has its own advantages.

* Load balancer based setup: Read requests get distributed round-robin between the Galera nodes. Theoretically by distributing the load of the read requests, you benefit from lower latencies and more throughput. But this has never been benchmarked yet. For a discussion of available loadbalances, see next section. OX-wise, 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). This is the setup which seems to perform best according to our experience as turning off the replication monitor reduces the commits on the DB and thus the write operations per second on the underlying storage significantly, which outweights the drawback from having higher commit latency due to fully synchronous mode.
** Alternatively, you can run Galera with wsrep_causal_reads=0 when switching on OX builtin replication monitor. This is also a valid setup.
* Use a designated floating IP for the read requests: This eliminates the need of a load balancer. With this option you will not gain any performance, but the quantitative benefit is unclear anyhow.
* 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 while still having OX builtin replication monitor switched off. However we do not expect this option to be superior to the round-robin loadbalancer approach.

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

Loadbalancers used for OX -> Galera loadbalancing should be able to implement active-passive instances for the write requests, and active-active (round-robin) instances for the read requests. (If they cannot implement active-passive, you can still take a floating IP therefore.) Furthermore it is required to configure node health checks not only on the TCP level (by a simple connect), but to query the Galera health status periodically, evaluating Galera WSREP status variables. Otherwise split-brain scenarios or other bad states cannot be detected. For an example of such an health check, see our [[Clustercheck]] page.

Some customers use loadbalancing appliances. It is important to check that if the (virtual) infrastructure offers "loadbalancer" instances that they satisfy the given requirements. Often this is not the case. In particular, a simple "DNS round robin" approach is not viable.

==== LVS/ipvsadm/keepalived ====

If you want to create your own loadbalancers based on Linux, we usually recommend LVS (Linux Virtual Servers) controlled by Keepalived. LVS is a set of kernel modules implementing a L4 loadbalancer which performs quite well. Keepalived is a userspace daemon to control LVS rules, using health checks to reconfigure LVS rules if required. Keepalived / LVS requires one (or, for availability, two) dedicated linux nodes to run on. This can be a disadvantage for some installations, but usually, it pays off. We provide some configuration information on Keepalived [[Keepalived|here]].

==== MariaDB Maxscale ====

Since Maxscale has become GA in 2015, it seems to have undergone significant stability, performance and functional improvements. We are currently experimenting with Maxscale and share our installation / configuration knowledge [[Maxscale|here]]. It looks quite promising and might become ''the standard replacement'' for HAproxy, while we still presume Keepalived offers superior robustness and performance, coming with the cost of the requirement for one (or more) dedicated loadbalancer nodes.

==== HAproxy ====

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. Be aware that in large installations the number of (distributed) HAproxy instances can get quite large. Some configuration hints for HAproxy are available [[HAproxy|here]].

== Master/Slave database setup ==

While we also support also "legacy" (pre-GTID) Master/Slave replication, we recommend to use GTID based replication, for easier setup and failure recovery. Support for GTID based replication has been added with OX 7.8.0.

GTID has been available since MySQL 5.6, so no 5.5 installation instructions below, sorry. We try to be generic in this documentation (thus, applicable to Oracle Community Edition and MariaDB) and point out differences where needed. Note: Instructions below include information about Oracle Community MySQL 5.7 which is not yet formally supported.

=== Preparations ===

Our configuration process includes wiping and reinitializing the datadir. This is usually not a problem in a fresh installation. If you want to upgrade an existing database to GTID master-slave, please be prepared to wipe the datadir, i.e. take a <code>mysqldump</code> for later restoration into the properly configured master.

Depeding on the flavor of the current database, this can be something like

# mariadb or oracle mysql without GTIDs
mysqldump --databases configdb oxdb_{5..14} > backup.sql

# mysql 5.6 with GTIDs... we dont want GTIDs here
mysqldump --databases --set-gtid-purged=OFF configdb oxdb_{5..14} > backup.sql

Be sure to verify the list of databases.

=== Installation ===

Software installation is identical for master and slave.

Please follow the instructions for installing from The vendors.

* Oracle Community Edition: https://dev.mysql.com/doc/mysql-apt-repo-quick-guide/en/
* MariaDB (10.0, 10.1): https://downloads.mariadb.org/mariadb/repositories/

Stop the service (if it is running):

service mysql stop

=== Configuration ===

Configuration as per configuration files is also identical for master and slave.

Consult [[My.cnf]] for general recommendations how to configure databases for usage with OX.

For GTID based replication, make sure you add some configurables to a new <code>/etc/mysql/ox.conf.d/gtid.cnf</code> file (assuming you are following our proposed schema of adding a <code>!includedir /etc/mysql/ox.conf.d/</code>" directive to <code>/etc/mysql/my.cnf</code>):

# GTID
log-bin=mysql-bin
server-id=...
log_slave_updates = ON

Oracle Community Edition: we need to add also

enforce_gtid_consistency = ON
gtid_mode = ON

(GTID mode is on by default on MariaDB.)

Use unique a <code>server-id</code> for each server; like <code>1</code> for the master, <code>2</code> for slave. For more complicated setups (like multiple slaves), adjust accordingly.

Since applying our configuration / sizing requires reinitialization of the MySQL datadir, we wipe/recreate it. Caution: this assumes we are running an empty database. If there is data in the database you want to keep, use mysqldump. See Preparation section above.

So, to initialize the datadir:

cd /var/lib/
mv mysql mysql.old.datadir
mkdir mysql
chown mysql.mysql mysql

(When coming from an existing installation, be sure to wipe also old binlogs. They can confuse the server on startup. Their location varies by configuration.)

The step to initialize the datadir is different for the different DBs:

# MariaDB 10.0, 10.1
mysql_install_db

# MariaDB 10.2
mysql_install_db --user=mysql

# Oracle 5.6
mysql_install_db -u mysql

# Oracle 5.7
mysqld --initialize-insecure --user=mysql

(Don't be worried about the <code>insecure</code>, it just means we set the db root pw in the next steps.)

Then:

service mysql restart
mysql_secure_installation

We want to emphasize the last step to run "secure".

Steps up to here apply to both the designated master and slave. The next steps will apply to the master.

=== Replication Setup ===

==== Master Setup ====

Create a replication user on the master (but, as always, pick your own password, and use the same password in the slave setup below):

mysql -e "CREATE USER 'repl'@'gtid-slave.localdomain' IDENTIFIED BY 'IvIjyoffod2'; GRANT REPLICATION SLAVE ON *.* TO 'repl'@'gtid-slave.localdomain';"

Now would also be the time to restore a previously created mysqldump, or add other users you need for adminstration, monitoring etc (like <code>debian-sys-maint@localhost</code>, for example). Adding the OX users is explained below ("Creating Open-Xchange user").

# If you took a dump for restore before
mysql < backup.sql

To prepare for the initial sync of the slave, set the master read-only:

mysql -e "SET @@global.read_only = ON;"

Create a dump to initialize the slave:

# MariaDB
mysqldump --all-databases --triggers --routines --events --master-data --gtid > master.sql

# Oracle
mysqldump --all-databases --triggers --routines --events --set-gtid-purged=ON > master.sql

Transfer to the slave:

scp master.sql gtid-slave:

==== Slave Setup ====

Configure the replication master settings. Note we don't need complicated binlog position settings etc with GTID.

Yet again DB-specific (use the repl user password from above):

# MariaDB
mysql -e 'CHANGE MASTER TO MASTER_HOST="gtid-master.localdomain", MASTER_USER="repl", MASTER_PASSWORD="IvIjyoffod2";'

# Oracle
mysql -e "CHANGE MASTER TO MASTER_HOST='gtid-master.localdomain', MASTER_USER='repl', MASTER_PASSWORD='IvIjyoffod2', MASTER_AUTO_POSITION=1;"
# https://www.percona.com/blog/2013/02/08/how-to-createrestore-a-slave-using-gtid-replication-in-mysql-5-6/
mysql -e "RESET MASTER;"

Read the master dump:

mysql < master.sql

Start replication on the slave:

mysql -e 'START SLAVE;'
mysql -e 'SHOW SLAVE STATUS\G'

==== Master Setup (continued) ====

Finally, unset read-only on the master:

# on the master
mysql -e "SET @@global.read_only = OFF;"

=== Configure OX to use with Master/Slave replication ===

Not much special wisdom here. OX was designed to be used with master/slave databases. For the ConfigDB, <code>configdb.properties</code> allows configuration of a <code>readUrl</code> and <code>writeUrl</code> (both of which are set to the correct values if you use <code>oxinstaller</code> with the correct arguments <code>--configdb-readhost</code>, <code>--configdb-writehost</code>).

(Obviously, the master is for writing and the slave is for reading.)

For the individiual UserDBs, use <code>registerdatabase -m true</code> for the masters and <code>registerdatabase -m false -M ...</code> for the respective slaves.

Be sure to have enabled the replication monitor in <code>configdb.properties</code>: <code>com.openexchange.database.replicationMonitor=true</code> (which it is by default); while GTID can show synchronous semantics, it is specified to silently fall back to asynchronous in certain circumstances, so synchronity is not guaranteed.

We recommend, though, to not register the databases directly by their native hostname or IP, but rather use some kind of HA system in order to be able to easily move a floating/failover IP from the master to the slave in case of master failure. Configuring and running such systems (like, corosync/pacemaker, keepalived, or whatever) is out of scope of this documentation, however.

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

Notes:

* Please use a real password.
* The IPs in this example belong to the two different Open-Xchange Servers, please adjust them accordingly.
* If using a database on the same host as the middlware (usually done for POCs and demo installations), you need to grant also to the ''localhost'' host.
* Consult [[AppSuite:DB_user_privileges]] (or ''grep GRANT /opt/open-xchange/sbin/initconfigdb'') for an up-to-date list of required privileges. The following statement was correct as of the time of writing this section.

mysql> GRANT CREATE, LOCK TABLES, REFERENCES, INDEX, DROP, DELETE, ALTER, SELECT, UPDATE, INSERT, CREATE TEMPORARY TABLES, SHOW VIEW, SHOW DATABASES ON *.* TO 'openexchange'@'10.20.30.213' IDENTIFIED BY 'IntyoyntOat1' WITH GRANT OPTION;
mysql> GRANT CREATE, LOCK TABLES, REFERENCES, INDEX, DROP, DELETE, ALTER, SELECT, UPDATE, INSERT, CREATE TEMPORARY TABLES, SHOW VIEW, SHOW DATABASES ON *.* TO 'openexchange'@'10.20.30.215' IDENTIFIED BY 'IntyoyntOat1' WITH GRANT OPTION;

OX6:OXtender for Business Mobility Installation Guide

2019-10-01T05:12:27Z

Malasa: removed old installation howtos/versions from 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.

'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article [[UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.

{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility}}

Follow this [http://software.open-xchange.com/OX6/doc/BusinessMobilityOXtender/ link] to download the User Manuals in different languages.

Now the Open-Xchange groupware and admin service needs to be restarted:
/etc/init.d/open-xchange-groupware restart
/etc/init.d/open-xchange-admin restart

On the first login after the restart, all required database tables will be created.

{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=6.22/OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility|version=v6.22.x}}

=== RedHat Enterprise Linux 5 ===
'''Please note,''' the last available version for RHEL5 is 6.22.0

$ vim /etc/yum.repos.d/oxmobility.repo

[oxmobility]
name=Open-Xchange
baseurl=http://LDBACCOUNT:LDBPASSWD@software.open-xchange.com/OX6/6.22/6.22.0/OXtender/BusinessMobilityOXtender/RHEL5/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update
$ yum 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 on 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.
* Log on at the Univention Management Console (UMC)
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"
* Within the component list, select "Connector for Business Mobility" and press the "Install" button

== Installation on OX App Suite ==
The download and installation information for Open-Xchange App Suite product family (Open-Xchange Server Edition and Hosting Edition) is available at: http://oxpedia.org/wiki/index.php?title=AppSuite:Connector_for_Business_Mobility_Installation_Guide

== 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/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.

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

=== Server-side logging: Options ===
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.

There are three different mechanisms, depending on your server version: If you use 7.4.2 or later, we use ''logback''. Before that, the default was ''commons logging'', unless you explicitly installed ''Log4j''.

==== Logback ====
As said, this is the default after (and including) 7.4.2. To get more verbose output, simply extend the logback.xml configuration file by the following line:

<logger level="DEBUG" name="com.openexchange.usm"/>

==== Commons Logging ====
This is the default logging mechanism prior to 7.4.2. If the Open-Xchange Server log output is written to ''var/log/open-xchange/open-xchange.log'' it is 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.

=== Client-side logging: 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

[[Category: OX6]]

TicketSystemCustomerGuide

2019-09-02T11:26:28Z

Malasa: pgp link changed

[[Category: Support]]

= Ticket System User Guide for Customers =

==Indroduction==
Customers with valid support license have access to all their tickets via the Open-Xchange ticket system (OTRS). The ticket system provides additional features for communication between you and Open-xchange, but it is not meant as a full substitution of email conversation. Hence you still have to start new incident requests via email like described at

http://knowledgebase.open-xchange.com/support/contact-support-bug-reporting/contact-support/english.html

This user guide gives an overview about the usage and benefits using this interface.

==Preliminary==
First you have to know the login name of your Open-Xchange Portal account where the license keys are registered. If your license key doesn't include a support option you don't have access rights to the ticket system.

Please check the used email address of your Portal account via 'Edit your data' inside the license portal, it was used for your ticket system account provisioning and is now disconnected to the Portal account settings. Your ticket system and Portal account passwords are also disconnected and you have to use the password recovery of the ticket system to set the initial password. If you observe a wrong or improper email address in your Portal settings, please contact the Open-Xchange Support so we can use the address of your choice for the ticket system. In case you have purchased a new support option, the ticket system account will be provisioned within 24 hours automatically.

'''Important: Your ticket system login will be disabled automatically in case your support option expires. Please note, this can be caused by date or if the number of allowed requests outrange the contractual limit.'''

==How to get Access==
The very first time you have to use the password recovery ([https://otrs.open-xchange.com/otrs/customer.pl#Reset Forgot password?]) with the Portal account name of the following link, further steps are described within an email, you will get to the address explain inside the preliminary section:

Login URL: https://otrs.open-xchange.com/otrs/customer.pl

==Ticket System Overview==
After login you will enter the overview page 'My Tickets', this view is sadly misleading because it will list only invalid tickets.

[[File:SupportTicketSystemCustomerGuide-OverviewDefault.png]]

'''Important: You have to switch to 'Tickets' --> 'Company tickets' to get the list for valid tickets.'''

[[File:SupportTicketSystemCustomerGuide-OverviewCompany.png]]

'''Overview Top Bar'''
Tickets
My Tickets --> Default view with invalid only tickets
Company tickets --> Relevant company view with valid tickets
Search --> Ticket Search
Preferences --> Password change, language settings, PGP keys, etc ..

==Usage==
You will get a direct link by an auto reply after your initial reporting email, hence it should be very easy to navigate to the ticket you are looking for.

[[File:SupportTicketSystemCustomerGuide-AutoReplyEmailExample.png]]

Once you open the ticket detail view, you will get an overview of important details about ticket number, current state and priority within a small box at upper right of the window. Also you will find a reply button at the bottom left on the page.

[[File:SupportTicketSystemCustomerGuide-TicketDetailView.png]]

By clicking on 'Reply' you are able to give us additional details, add attachments up to 500MB size or close the ticket by your self.

[[File:SupportTicketSystemCustomerGuide-ReplyWindow.png]]

==Personal Data Policy==
According to German law, companies are forced to handle any (log) files from customers which contain data related to a third person or has any personal protection in a special way. Personal data shall mean any information concerning the personal or material circumstances of an identified or identifiable natural person. Even so they have to be deleted once they aren't used any more. To fulfil this requirement, customers and support agents have to keep the readable ticket communication, in form of email/article body, subject or attachment names, free from any personal data. This can be every thing from names, email addresses, screen-shots, logs files and even credentials to system accounts. This personal data only has to be handed over in form of attachments which was common practice before. Transfer channels for personal data are attachments via the ticket system, attachment in encrypted emails or provided by protected download links. How to send encrypted emails via PGP is described [https://confluence-public.open-xchange.com/display/SKB/How+to+send+an+encrypted+email+to+Open-Xchange+Support here].

The integrity of an 'Incident Request' with all available data needs to be saved up to 90 days after a ticket was closed to ensure a holistic assessment in case of Contractual complaints. This time frame is mandatory and gives also the customer time for detailed tests. In case of reopening an incident within these three months all information is still available and needs not to be recollected by customers and end users.

Open-Xchange introduced a weekly deletion process, the deletion work on ticket attachments and on raw email files which are affected by attachments. The automatic deletion of all ticket attachments takes place weekly at Sunday and affects all tickets which are in a 'closed' state since 90 days.

OXLDAPSync Guide

2019-03-15T06:12:22Z

Malasa: added box for "not supported"

<div style="border:2px solid red; text-align:center; padding: 1em; margin: 0.5em;">This page is DEPRECATED. oxldapsync is not supported and is outdated.</div>

{{InstallPlugin|toplevel=components|pluginname=oxldapsync|sopath=unsupported/oxldapsync|reponame=oxldapsync|version=OX 6.22 or newer}}

= How to run OX LDAP Sync =

With OX LDAP Sync you can sync user and group objects from a LDAP compatible
directory with Open-Xchange. When you modify or add an user to your
ldap directory oxldapsync will also modify or add the user to Open-Xchange.

== Prerequisites ==

# An LDAP-server (currently openldap and ADS are supported)
# You need one user distinguished name who at least can search and read user objects. If you decide to synchronize groups, the ldap user needs to search and read these objects, too.
# If you want to synchronize groups you need to know if the membership to the group is defined by the userid or by the complete distinguished name of the user.
# User attributes you want to sync with Open-Xchange
# Open-Xchange must authenticate against the LDAP server instead of the database, which is the default. In order to achieve that, deinstall package <tt>open-xchange-authentication-database</tt> and install <tt>open-xchange-authentication-ldap</tt> and configure it accordingly in changing /opt/open-xchange/etc/groupware/ldap.properties. As an alternative, <tt>open-xchange-authentication-imap</tt> could be used, if your IMAP server authenticates against your LDAP server.

== configuring OX LDAP Sync ==

After installing OXSync you will find the configuration files under
/opt/oxldapsync/etc. You can use the example configuration files
ldapsync.conf (openldap) and ldapsyn-ads.conf (Active Directory) as
starting point.

=== OpenLDAP ===

Open ldapsync in your favourite text editor change following options to your needs:

ldapuri with dns-name or ip of your
LDAP-Server
userbasedn distinguished name under which the
script will find user objects
groupbasedn distinguished name under which the
script will find group objects
ldaptype type of ldap in this case openldap
ldapuserdn distinguished name of the user
which will be used to query the
directory
ldapuserpassword password for the ldapuser
mappingfile absolute path to your ldap
attribute -> ox attribute mapping
updategroups "yes" if you want to also sync
groups with ox
updateAliases shall mail aliases of a user get
updated with the one from the ldap.
In case you can name only one
mailaddress on your directory, say
no here and you can manually add
further mailaddresses in ox. They
will not get deleted by the
synctool.
usemodifytimestamp set to yes, to update only users
since last run
userfilter searchfilter to find user objects,
internal default
"(objectClass=inetOrgPerson)"
groupfilter searchfilter to find group objects,
internal default
"(objectClass=posixGroup)"
deleteusers Say yes if you want to delete users
in ox which are not in your
directory and are not named by the
"dontModifyUids" option
deletegroups say yes to delete empty and non
existing groups in ldap in ox
dontModifyUids list of comma separeted uid's which
shall not be modified by the sync
script. You should note at least
the contextadmin
groupMemberAttribute name of attribute which holds the
members in a group object
memberAttributeIsDN say yes if groupMemberAttribute is
a distinguished name
groupDisplayNameAttribute displayname attribute for group
groupNumberAttribute unique number attribute for group
userPrimaryGroupAttribute attribute name where a users primary
is stored

In the mapping file you will find ox options to create or modify users. The name on the left side of the equal sign is the name for the ox options. On the right side you name the ldap attribute name for this option. You can also give static values by enclosing them with qoutes.

=== Active Directory ===

For active directory synchronization just modify at least ldapuri, userbasedn, groupbasedn, ldapuserdn and ldapuserpassword.

To run the script type

$ /opt/oxldapsync/sbin/oxldapsync.pl -f <CONFIG FILENAME> \
-A <CONTEXT ADMIN USERNAME> \
-P <CONTEXT ADMIN PASSWORD> \
-c <CONTEXTID>

Additional parameters are:

-h help message
-n don't save last user search time
-v Verbose mode
-s print messages to stdout

To run this program regularly just create a cronjob

= Troubleshooting =
== Special chars scrambled ==
If you run OX LDAP Sync via Cronjob an the umlauts (ä,ö,ü,...) of your entries in the "Global Addressbook" are scrambled, try setting the LANG environment variable in your crontab, e. g. German UTF-8 users should set this to something like this:

LANG=de_DE.UTF-8
#m h dom mon dow command
0 23 * * Sun /path/to/oxldapsync.pl

For more information on using the crontab please visit [http://tldp.org/LDP/LGNET/151/prestia.html this howto at The Linux Documentation Project].

[[Category: OX6]]
[[Category: AppSuite]]

AppSuite:Banner

2018-09-24T08:18:42Z

Malasa: typo

{{Version until|7.8.4}}<br>

Since OX App Suite 7.8.0 it is possible to have a banner on top of the application.

Please Note: This functionality is only supported with v7.8.x.

[[File:Banner.png]]

By default the banner is disabled, to use it edit <code>/opt/open-xchange/etc/settings/appsuite.properties</code> and add:
<pre>
io.ox/core//banner/visible=true
</pre>

To change the default values you have to add them to <code>/opt/open-xchange/etc/as-config.yml</code>
<pre>
default:
host: all
bannerCompany: 'mycompany'
bannerProductName: 'myproductname'
bannerHeight: 60
</pre>
note: the leading spaces are important in a .yml file.

This would enable and change the company/product name for all hosts/users. A more fine grained configuration is possible via the configcascade.

AppSuite:Quick launcher

2018-08-01T06:39:19Z

Malasa: init

With OX App Suite 7.10 a new concept of starting applications was introduced and replaced the tabs from previous versions.

By default you can switch the applications in the upper right part of the screen on the icon which looks like a numeric keypad.

It is however possible to enable a quick launcher to have the most used applications on the left side.

First you have to set the default configuration:

<code>vim /opt/open-xchange/etc/settings/appsuite.properties</code> and add:

<pre>
io.ox/core//apps/quickLaunchCount=3
io.ox/core//apps/quickLaunch=io.ox/mail/main,io.ox/calendar/main,io.ox/files/main
</pre>

This will enable three new quick launchers, mail, calendar and drive. 3 is the maximum.

To make it possible for the user to change the applications you have to un-protect the setting:

<code>vim /opt/open-xchange/etc/meta/appsuite.yaml</code>

<pre>
io.ox/core//apps/quickLaunch:
protected: false
</pre>

'''Note''': as in all yaml files: the leading spaces (4) on the second line are important.

After a restart or <code>reloadconfiguration</code> of OX App Suite and a re-login you should see three new icons on the left. If you also un-protected the setting you can change the applications in Settings/Basic settings.

Twitter Bundles

2018-07-19T09:33:36Z

Malasa: clean up, new screenshots

= Using Twitter with Open-Xchange =

== Preparation ==

You MAY want to replace the standard configuration of twitter integration. This depends on whether you want your own company-name to be shown to users during the twitter authentication process. If you want this please follow these steps:

* Go to https://dev.twitter.com/apps
* Log into Twitter
* Click "Create a new application" on the right

Make sure that you update to the latest version of Open-Xchange Appsuite.

[[File:Twitter_new_01.png]]

* Enter appropriate Information in "Name", "Description", "Website" and "Callback URL". "Callback URL" should be the URL by which the Server is reachable (This is not checked at this moment but may be in the future).
* Enter the text displayed in the captcha into the textfield below
* Check "Yes, I agree" under "Developer Rules Of The Road"
* Click "Create your Twitter application"

[[File:Twitter_new_02.png]]

'''Note:''' the callback URL has to be https and with the /ajax/defer path at the end.

* In the following overview click "Keys and Access Tokens"

[[File:Twitter_new_04.png]]

* Change in the "Permissions" tab "Read only" to "Read and Write" (should be default)
* Click "Update settings"

You can also update:
* Fill "Organization name" and "Organization website" if wanted
* Upload a custom application icon if wanted

Edit the file /opt/open-xchange/etc/twitteroauth.properties and insert the key and secret from the settings page above, like this:

<pre>
com.openexchange.oauth.twitter.apiKey=0JtyhCeuc7kZotWGx037jxlsG
com.openexchange.oauth.twitter.apiSecret=n8y34hSfeLa0kCizUrcnYjeUg49OfIz7De8SiKZ4TKwfKWYppj
</pre>

{{InstallPlugin|pluginname=open-xchange-oauth open-xchange-messaging|toplevel=products |sopath=appsuite/stable/backend |version=App Suite}}

{{InstallPlugin|pluginname=open-xchange-oauth|sopath=stable}}

== Configuration ==

File:Twitter new 04.png

2018-07-19T09:14:23Z

Malasa: Malasa uploaded a new version of "File:Twitter new 04.png"

File:Twitter new 02.png

2018-07-19T09:11:08Z

Malasa: Malasa uploaded a new version of "File:Twitter new 02.png"

Twitter Bundles

2018-07-18T11:53:21Z

Malasa: added note about correct callback url, see bug 59098

= Using Twitter with Open-Xchange =

== Preparation ==

You MAY want to replace the standard configuration of twitter integration. This depends on whether you want your own company-name to be shown to users during the twitter authentication process. If you want this please follow these steps:

* Go to https://dev.twitter.com/apps
* Log into Twitter
* Click "Create a new application" on the right

'''NOTE''': the callback URL changed recently, it has to be '''https://yxz.mycompany.com/ajax/defer''' and not http://xyz.mycompany.com as seen in the screenshots. Note it is https now and has an added path.

Make sure that you update to the latest version of Open-Xchange Appsuite.

[[File:Twitter_new_01.png]]

* Enter appropriate Information in "Name", "Description", "Website" and "Callback URL". "Callback URL" should be the URL by which the Server is reachable (This is not checked at this moment but may be in the future).
* Enter the text displayed in the captcha into the textfield below
* Check "Yes, I agree" under "Developer Rules Of The Road"
* Click "Create your Twitter application"

[[File:Twitter_new_02.png]]

[[File:Twitter_new_03.png]]

* In the following overview click "Settings"

[[File:Twitter_new_04.png]]

* Change "Access" from "Read only" to "Read and Write"
* Fill "Organization name" and "Organization website" if wanted
* Upload a custom application icon if wanted
* Click "Update this Twitter application´s settings"

[[File:Twitter_new_05.png]]

* Copy the String under "Consumer key" and paste it into the file "twitter.properties" as parameter "com.openexchange.twitter.consumerKey" (replacing the existing key there)

* Copy the String under "Consumer secret" and paste it into the file "twitter.properties" as parameter "com.openexchange.twitter.consumerSecret" (replacing the existing key there)

[[File:Twitter_new_06.png]]

[[File:Twitter_new_07.png]]

{{InstallPlugin|pluginname=open-xchange-oauth open-xchange-messaging|toplevel=products |sopath=appsuite/stable/backend |version=App Suite}}

{{InstallPlugin|pluginname=open-xchange-oauth-twitter open-xchange-twitter open-xchange-messaging-twitter|sopath=stable}}

== Configuration ==

My.cnf

2018-07-17T11:26:47Z

Malasa: fixed wrong utf8_general_ci instead of utf8mb4_general_ci

== Introduction ==

This page lists some performance tuning parameters which we recommend for tuning MySQL database services used for Open-Xchange installations.

We cannot guarantee this is an exhaustive list of required settings. So treat this list of tunings as probably required, but not necessarily sufficient settings for optimal MySQL performance.

Furthermore, as MySQL changes over time, settings which have been correct as of the time of writing may become incorrect later.

However, this list of settings is the result of internal performance testing and real world customer feedback, so it should be valid to some extent.

In the end, proper configuration of the database service for performance, but also consistency, durability and high availability is in the responsibility of the customer.

=== Performance items ===

* You should adjust the <code>innodb_buffer_pool_size</code> parameter for reasonable memory usage. Our DB sizing is mainly memory-driven and this is where most of the memory goes. Our standard DB machine sizing assumption is 32 GB if MySQL dedicated memory on a 48 GB total memory machine. On such a machine, you would configure 32 GB for the innodb_buffer_pool size, being aware that MySQL does also require memory for other things, in particular there are some also per-connection related memory spendings, which can become substantial if you allow for a lot of maximum concurrent connections. Please watch your memory configuration carefully, use monitoring and tools like mysqltuner.pl.

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

* 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 (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.

=== Functional items ===

* Query cache is to be switched off; as we found in our own benchmarks and as backed up by upstreams, this hurts performance in load situations with high concurrency. [https://dev.mysql.com/doc/refman/5.7/en/query-cache.htm The query cache is deprecated as of MySQL 5.7.20, and is removed in MySQL 8.0], so we recommend also to switch that off.
* Starting with App Suite 7.10.0, <code>character_set_server</code> must be set to <code>utf8mb4</code> and <code>collation_server</code> to <code>utf8mb4_general_ci</code>
* Starting with MySQL 5.7 <code>innodb_strict_mode</code> must be disabled.
* Starting with MySQL 5.7 and MariaDB 10.2 <code>sql_mode</code> must be configured according to belows matrix.

==== SQL mode matrix ====

The default for the <code>sql_mode</code> setting changes regularly with MariaDB and MySQL releases and is not even consistent anymore between the two derivates. SQL modes affect how data and queries are handled at runtime. Enabling strict modes might lead to errors in terms of failing queries or even update tasks. We strongly recommend the following configuration to avoid according runtime errors:

{| class="wikitable"
|-
! scope="col"| sql_mode
! scope="col"| App Suite 7.8.4
! scope="col"| App Suite 7.10.0
|-
! scope="row"| MySQL 5.6
| <code>NO_ENGINE_SUBSTITUTION</code>
| <code>NO_ENGINE_SUBSTITUTION</code>
|-
! scope="row"| MySQL 5.7
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code>
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION,ONLY_FULL_GROUP_BY</code>
|-
! scope="row"| MariaDB 10.1
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code>
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code>
|-
! scope="row"| MariaDB 10.2
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code>
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code>
|-
|}

=== Sample config files ===

For easy deployment we recommend not to edit existing the existing my.cnf file, rather assume the distro provides sane settings for most of the items and override items where needed.

As in MySQL there is a [https://dev.mysql.com/doc/refman/5.7/en/option-files.html last instance wins] semantic in options file parsing, we propose to create a custom include directory "ox.conf.d", put our custom config files therein, and include this directory as latest directory in /etc/mysql/my.cnf.

To put in that directory, we have one main tuning file called tunings.cnf, one galera-related file if galera is in use, and one more galera host-specific file which contains per-host settings if using galera (separate in a file of its own for easier configuration management).

So, start with adding to the existing my.cnf at the very bottom:

!includedir /etc/mysql/ox.conf.d/

Create that directory and put in there the generic ox tunings file /etc/mysql/ox.conf.d/tunings.cnf:

[mysqld]
bind-address = *

#innodb_use_native_aio = 0

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 = 0
query_cache_type = 0
default_storage_engine = InnoDB
innodb_buffer_pool_size = 32G
# the default value in MySQL 5.6.6 and higher is 8 when innodb_buffer_pool_size is greater than or equal to 1GB. Otherwise, the default is 1.
innodb_buffer_pool_instances = 32
innodb_data_file_path = ibdata1:128M:autoextend
innodb_file_per_table = 1
# innodb_log_file_size should be 25% of the innodb_buffer_pool_size
innodb_log_file_size = 4GB
# default and recommended value is 2
innodb_log_files_in_group = 2
# adjust according to your storage
#innodb_io_capacity = 1000

# we are unsure about this setting. Newer versions of MariaDB seem to be fine with low (=1) settings for this value.
# Traditionally we encountered values up to 4x the number of cores.
# Default seems to be number of cores, so let's stick the default
# In the end, we need to leave this setting up to you: if you dont get full cpu utilization in cpu-bound situations, this might be a setting to increase.
#thread_pool_size = 32

binlog_cache_size = 1M
sync_binlog = 8
binlog_format = row

character_set_server = utf8
collation_server = utf8_general_ci

# This was default_table_type previous to MySQL 5.5
default_storage_engine = InnoDB

innodb_autoinc_lock_mode = 2

# keep until 5.6, deprecated later
innodb_locks_unsafe_for_binlog = 1

# we found this has huge impact on (galera) performance
# default (consistent) setting of 1 greatly severs performance
# in galera (or async master-slave) deployments, you might be ok with setting this to 0 or 2,
# assuming our consistency / availability comes from replication / other cluster nodes
innodb_flush_log_at_trx_commit = 0

# for performance testing systems, to not use excessive disk space
#expire_logs_days = 1

# MySQL 5.7.7 has changed the default to 1. Disable it explicitly to prevent from errors based on invalid data stored by former App Suite or MySQL versions.
innodb_strict_mode = 0

# The following value refers to App Suite 7.10 on top of MySQL 5.7. For other combinations see the sql mode matrix at http://oxpedia.org/wiki/index.php?title=My.cnf.
sql_mode = NO_ENGINE_SUBSTITUTION,NO_AUTO_CREATE_USER,ONLY_FULL_GROUP_BY

If using galera, use the following galera configuration file /etc/mysql/ox.conf.d/wsrep.cnf:

[mysqld]
# adjust for your distros SO location
wsrep_provider=/usr/lib/libgalera_smm.so

# this is the big winner and enables us to switch off OX's replication monitor
wsrep_sync_wait=1

# pick a unique cluster name
wsrep_cluster_name=devcluster
# adjust for your IPs / hostnames
wsrep_cluster_address=gcomm://10.20.29.68,10.20.29.69,10.20.29.70

# put this in host.cnf
#wsrep_node_name=...
#wsrep_node_address=...

wsrep_sst_method=xtrabackup-v2
# wsrep_sst_auth if of format username:password
# pick whatever you configured on the donor node
wsrep_sst_auth=sstuser:...

# galera-specific tunings
wsrep_slave_threads = 32
pxc_strict_mode=ENFORCING

Galera-related host-specific settings go in /etc/mysql/ox.conf.d/host.cnf:

[mysqld]
# the nodes hostname
wsrep_node_name=...
# and the IP of the wsrep relevant interface, if multiple
wsrep_node_address=10.20.29.68

AppSuite:DocumentConverterInstall

2018-05-17T13:19:00Z

Malasa:

= Description =

This is the Open-Xchange implementation of the [[AppSuite:DocumentConverterAPIInstall|Document Converter API]]. While the API is open, the implementation is not licensed under GPL. It maintains the running instances of readerengines, which are headless OpenOffice instances. This behavior can be configured through documenterconverter.properties configuration file. The Document Converter is only available via a valid Open-Xchange license key.

See [[AppSuite:ReaderEngineInstall|Readerengine installation instructions]] for details on the setup of the underlying readerengine.

For a more detailed guide explaining different installation variants, inluding details on installing Document Converter Client in various configurations, visit the [[AppSuite:DocumentConverter_Installation_Guide|Installation Guide]]. The client is required in order to preview documents.

Instructions for manual steps needed for the [[AppSuite:DocumentConverterUpdate782|Update to 7.8.2]] from earlier versions.

The Document Converter is installed according to the following instructions.

{{InstallPlugin|pluginname=open-xchange-documentconverter-server|toplevel=products|sopath=appsuite/stable/documentconverter|version=App Suite|reponame=documentconverter|ldbaccount=CUSTOMERID:PASSWORD}}

You also have to add the update repository:

{{InstallPlugin|pluginname=open-xchange-documentconverter-server|toplevel=components|sopath=documentconverter/updates/7.8.4|version=App Suite|reponame=documentconverter|ldbaccount=CUSTOMERID:PASSWORD}}

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

Export ical/vcard

2018-01-25T04:59:05Z

Malasa: changed user/pw sending in curl

This is an example script that is able to get contacts,appointments,tasks as well as the global addressbook ical/vcard format.

'''NOTE:'''This example does the http request for the login as GET, so user name
and password is logged in the apache log. The example only works for users that
are created with the language en_US

~/bin> ./extract.sh --help
usage ./extract.sh serverurl user password

#!/bin/bash

SERVER=http://your.ox.server
USER=user@context
PASSWORD=userspw

test "$1" = "--help" && echo "usage $0 serverurl user password" && exit 1

test -z $1 || SERVER=$1
test -z $2 || USER=$2
test -z $3 || PASSWORD=$3

CURL='curl -b cookies -c cookies -H Expect: -s -L --location-trusted -k'

SESSION=`$CURL --data "name=$USER&password=$PASSWORD" "$SERVER/ajax/login?action=login" \
|sed 's/^.*session\":\"$[0-9A-Fa-f]*$\".*$/\1/'`

echo $SESSION | grep "error" && echo "got no session, login failed" && exit 1

P_FOLDERS=`$CURL -X GET "$SERVER/ajax/folders?action=list&columns=1%2C301%2C300%2C307%2C304%2C306%2C302%2C305%2C308%2C311%2C2%2C314%2C313%2C315&session=$SESSION&parent=1"`

TASK="not found"
TASK=`echo $P_FOLDERS | sed 's/,\"tasks\".*$//' | sed 's/.*\[$[0-9]*$$/\1/'`
CAL="not found"
CAL=`echo $P_FOLDERS | sed 's/,\"calendar\".*$//' | sed 's/.*\[$[0-9]*$$/\1/'`
CON="not found"
CON=`echo $P_FOLDERS | sed 's/,\"contacts\".*$//' | sed 's/.*\[$[0-9]*$$/\1/'`

echo ------------------------------------------------------
echo exporting private task folder $TASK:
echo ------------------------------------------------------
$CURL $URL -X GET "$SERVER/ajax/export?action=ICAL&session=$SESSION&folder=$TASK"
echo ------------------------------------------------------
echo exporting private calendar folder $CAL:
echo ------------------------------------------------------
$CURL $URL -X GET "$SERVER/ajax/export?action=ICAL&session=$SESSION&folder=$CAL"
echo ------------------------------------------------------
echo exporting private contacts folder $CON:
echo ------------------------------------------------------
$CURL $URL -X GET "$SERVER/ajax/export?action=VCARD&session=$SESSION&folder=$CON"
echo ------------------------------------------------------
echo "exporting global address book contacts folder 6:"
echo ------------------------------------------------------
$CURL $URL -X GET "$SERVER/ajax/export?action=VCARD&session=$SESSION&folder=6"
echo ------------------------------------------------------

[[Category: OX6]]
[[Category: Command line]]

AppSuite:Filestorages

2017-05-30T04:32:18Z

Malasa: path not etc/groupware anymore

= Common preparations =
This page shows how to setup external file stores. For all of these file stores you have to install the package "open-xchange-oauth", which provides the necessary authentication mechanisms.

Moreover your setup is required to be reachable via HTTPS, since the providers expect that a call-back URL to your setup is specified. Such a call-back URL is only accepted if it contains the <source enclose="none" lang="java">"https://"</source> scheme., e.g.:
<syntaxhighlight lang="java">
"https://my.oxsetup.invalid/ajax/defer"
</syntaxhighlight>

== Keep HTTPS protocol ==
[[Appsuite:Grizzly#Cluster_setup]] shows that HTTPS communication is terminated by the Apache balancer in front of the Open-Xchange nodes. To let the Open-Xchange application know about the HTTPS protocol that is used to communicate with the Apache server:
* Either set a special header in the SSL virtual hosts configurations in Apache to forward this information. The de facto standard for this is the <source enclose="none" lang="java">"X-Forwarded-Proto"</source> header. See [[Appsuite:Grizzly#X-FORWARDED-PROTO_Header]] for how to setup that header.
* Or force the Open-Xchange application to assume it is reached via SSL through setting property <source enclose="none" lang="properties">"com.openexchange.forceHTTPS=true"</source> in file ''/opt/open-xchange/etc/server.properties''.

== Deferrer URL ==
Open-Xchange application uses the deferrer URL as call-back for some of the providers, which use OAuth v2.0 authentication (such as Google).

If your OX server is reachable only via one host name, you won't have to do anything. If it is reachable by more than one host name, create or open the file ''/opt/openexchange/etc/deferrer.properties'' and set the properties therein as such:
<syntaxhighlight lang="properties">
com.openexchange.http.deferrer.url=https://mymaindomain.invalid
</syntaxhighlight>

= Dropbox =

To setup the Dropbox file store you have to install the package "open-xchange-file-storage-dropbox".

== Registering your app ==
* Log in to your Dropbox account [https://www.dropbox.com/login here], and create your Dropbox app [https://www.dropbox.com/developers/apps/create here]
* There are two options available creating an app, Drops-in App & Dropbox API App. Please select '''Dropbox API''' app and enter the name of your app.
* Go to [https://www.dropbox.com/developers/apps App Console] and select your created app. Select settings tab to view the <source enclose="none" lang="java">APP_KEY</source> (App key) and <source enclose="none" lang="java">SECRET_KEY</source> (App secret)

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/dropboxoauth.properties'':

* Enable the OAuth connector to Dropbox OAuth
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox=true
</syntaxhighlight>
<br>

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox.apiKey=REPLACE_THIS_WITH_DROPBOX_APP_KEY
com.openexchange.oauth.dropbox.apiSecret=REPLACE_THIS_WITH_DROPBOX_APP_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL. Please ensure the following conditions are met:
** The redirect URL specified in the Dropbox App needs to be the same as the one specified by this property.
** The redirect URI uses <source enclose="none" lang="java">"https://"</source> as protocol
** The redirect URI follows the pattern: <source enclose="none" lang="java">"https://" + <host-name> + "/ajax/defer"</source>
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox.redirectUrl=
</syntaxhighlight>
E.g. <source enclose="none" lang="java">"https://myappsuite.mydomain.invalid/ajax/defer"</source>
<br>

* Set the product ID of the registered Dropbox app
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox.productName=
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-dropbox|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Google Drive =

To setup the Google Drive file store you have to install the package "open-xchange-file-storage-googledrive".

== Registering your app ==
* Sign in to [https://console.developers.google.com/ Google Developers Console] using your Google account
* Please follow [https://developers.google.com/identity/sign-in/web/devconsole-project these] instructions to create a new project with a client ID, which is needed to call the sign-in API
* Enable the following APIs for your project
** BigQuery API
** Calendar API
** Contacts API
** Drive API
** Drive SDK
** Gmail API
** Google Cloud SQL
** Google Cloud Storage
** Google Cloud Storage JSON API

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/googleoauth.properties'':

* Enable the OAuth connector to Google OAuth
<syntaxhighlight lang="properties">
com.openexchange.oauth.google=true
</syntaxhighlight>
<br>

* Set the API key and secret, which is Client ID and Client Secret to call the sign-in API (Select your project, select API manager from upper left burger menu, select credentials in left side bar, select Client ID for Web application)
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.apiKey=REPLACE_THIS_WITH_YOUR_CLIENT_ID
com.openexchange.oauth.google.apiSecret=REPLACE_THIS_WITH_YOUR_CLIENT_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL. Please ensure the following conditions are met:
** The redirect URL specified in the Google App needs to be the same as the one specified by this property.
** The redirect URI uses <source enclose="none" lang="java">"https://"</source> as protocol
** The redirect URI follows the pattern: <source enclose="none" lang="java">"https://" + <host-name> + "/ajax/defer"</source>
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.redirectUrl=
</syntaxhighlight>
E.g. <source enclose="none" lang="java">"https://myappsuite.mydomain.invalid/ajax/defer"</source>
<br>

* Set the product ID of the registered Google app
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.productName=
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-googledrive|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Microsoft Onedrive =
To setup the Microsoft OneDrive file store you have to install the package "open-xchange-file-storage-onedrive".

== Registering your app ==
* Please follow [https://msdn.microsoft.com/en-us/library/ff751474.aspx this guide] to create/register your app

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/msliveconntectoauth.properties'':

* Enable the OAuth connector
<syntaxhighlight lang="properties">
com.openexchange.oauth.msliveconnect=true
</syntaxhighlight>
<br>

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.msliveconnect.apiKey=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_CLIENT_KEY
com.openexchange.oauth.msliveconnect.apiSecret=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_CLIENT_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL
<syntaxhighlight lang="properties">
com.openexchange.oauth.msliveconnect.redirectUrl=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_REDIRECT_URL
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-onedrive|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Box.com =
To setup the Box.com file store you have to install the package "open-xchange-file-storage-boxcom".

== Registering your app ==
* Sign in to [https://developers.box.com/ box Developers]
* Select '''Create a Box Application'''
* Select '''Box Content'''
* Hit '''Configure your application'''
* Enter ''redirect_uri''' (the deferrer URL; e.g. <source enclose="none" lang="java">"https://my.oxsetup.invalid/ajax/defer"</source>)
* Enable ''Read and write all files and folders''

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/boxcomoauth.properties'':

* Enable the OAuth connector
<syntaxhighlight lang="properties">
com.openexchange.oauth.boxcom=true
</syntaxhighlight>
<br>

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.boxcom.apiKey=REPLACE_THIS_WITH_YOUR_BOX_CLIENT_KEY
com.openexchange.oauth.boxcom.apiSecret=REPLACE_THIS_WITH_YOUR_BOX_CLIENT_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL
<syntaxhighlight lang="properties">
com.openexchange.oauth.boxcom.redirectUrl=REPLACE_THIS_WITH_YOUR_BOX_REDIRECT_URL
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-boxcom|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

AppSuite:OX Guard

2017-03-22T08:08:33Z

Malasa: /* Apache */ wrong location proxypass

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== Overview ==

OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.

OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.

This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:

* To setup a single server installation
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster
* To use the database service on the existing Open-Xchange installation for Guard, no replication
* To provide a basic configuration setup, no mail server configuration

=== Key Features ===

* Simple security at the touch of a button
* Provides user based security - Separate from provider
* Supplementary security to Provider based security - Layered
* Powerful features yet simple to use and understand
* Security - Inside and outside of the OX environment
* Email and Drive integration
* Uses proven PGP security

=== Availability ===

If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.

=== Requirements ===

Please review [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard OX Guard Requirements] for a full list of requirements.

Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|}

=== Important Notes ===

==== Customisation ====

OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization OX Guard Customisation] article for more details.

==== Mail Resolver ====

READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!

The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.

Once Guard is installed, please be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 will eventually execute database update tasks if installed and activated. Please take this into account.

There are several components to the Guard service. They can be all installed on the same server as the OX middleware or on a separate server.

The components required for the OX middleware are: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> <code>open-xchange-guard-reader</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

The components required for the Guard server <code>open-xchange-guard</code> and either <code>open-xchange-guard-file-storage</code> or <code>open-xchange-guard-s3-storage</code> depending on what storage you want to use. The examples below make use of the <code>open-xchange-guard-file-storage</code>. Adjust the commands accordingly to fit your needs. In addition <code>open-xchange</code> and <code>open-xchange-core</code> are required to run OX Guard.

=== Debian Linux 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/2.4.2/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</source>

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storagec</source>

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin open-xchange-guard-reader</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 11 (valid until v2.4.2) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.4.2/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/backend/SLES11 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin open-xchange-guard-reader</source>
or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-reader</source>

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.

Please note: By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the Internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module "Univention Configuration Registry". The variable has to contain the external FQDN of the OX Guard system:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</source>

Then run:

$ apt-get update
$ apt-get dist-upgrade</source>

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s</source>

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>

Then run:

$ apt-get update
$ apt-get dist-upgrade</source>

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s</source>

=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== SUSE Linux Enterprise Server 11 (valid until v2.4.2) ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/updates/SLES11 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== Configuration ==

The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options. Additional information can be found in the [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== Middleware Configuration on OX Guard node ===

If you are installing OX Guard on a node that until yet did not host an Open-Xchange middleware you have to additionally configure some parts of the following properties files:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><Proxy balancer://oxguard>
Order deny,allow
Allow from all

BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard
ProxyPass /pks balancer://oxguard/pgp</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> parameter.

'''Also Note''': If you already have a Proxy balancer for the OX backend with the same URL (say http://localhost:8080) then you don't need the second BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># OX GUard general permission, required to activate Guard in the AppSuite UI.
com.openexchange.capability.guard=true

# Default theme template id for all users that have no custom template id configured.
com.openexchange.guard.templateID=0</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.login=apiusername

# Specify the password used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.password=apipassword</source>
Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the URL suffix <code>/guardadmin</code>. In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
# Default is empty
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== SELinux ====

Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8009, which is where the Guard backend service listens to. In order to allow localhost connections to 8009 execute the following:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the master password file in <code>/opt/open-xchange/etc/oxguardpass</code>. The initiation only needs to be done '''once''' for a multi server setup, for details please see the sections '''Optional''' and/or '''Clustering'''.

'''Please Note''': If you run a cluster of OX / Guard nodes, only execute this command on '''ONE''' node. Not on all nodes! See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> is required to reset user passwords; without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.

=== Test Setup ===

Not required, but it is a good idea to test the Guard setup before starting the initialization. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.

To test, use an email address that exists on the OX backend (john@example.com for this example)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
Guard should return information from the OX backend regarding the user associated with "john@example.com". Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.

=== Enabling Guard for Users ===

Guard provides two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>

The "core" Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.

'''Guard Mail''' and '''Guard Drive''' are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of drive files.

Each of those two Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:

==== Guard Mail: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true</source>
==== Guard Drive: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true</source>
'''Please Note''': Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the <code>guard-api.properties</code> file on the OX bakend.

=== Recipient key detection ===

==== Local ====

Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.

To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver OX Guard Mail Resolver] for details.

==== External ====

Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== Clustering ===

You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.

==== MySQL ====

The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the MySQL client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== Apache ====

OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><Location /preliminary>
Order Deny,Allow
Deny from all
# Only allow access from Guard servers within the network. Do not expose this
# location outside of your network. In case you use a load balancing service in front
# of your Apache infrastructure you should make sure that access to /preliminary will
# be blocked from the Internet / outside clients. Examples:
# Allow from 192.168.0.1
# Allow from 192.168.1.1 192.168.1.2
# Allow from 192.168.0.
</Location>

ProxyPass /preliminary balancer://oxcluster/preliminary
</source>

Make sure that the balancer is properly configured in the <code>mod_proxy</code> configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose <code>/preliminary</code> to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.

If the Apache server is a dedicated server <code>/</code> instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== Open-Xchange ====

Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> on more than one server.

After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the servlet <code>/preliminary</code> on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

Afterwards restart the OX Guard service and check the log file if the OX Guard backend is able to connect to the configured REST API.

=== Multi Node ===

If you have multiple OX and Guard installations, please see the following documentation [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== Support API ==

The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere.

'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.

=== Reset password ===

<code>POST /guardsupport/?action=reset_password</code>

Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

Response:
PRIMARY if the reset was sent to the primary email address. SECONDARY if the reset email was sent to the secondary email address that the user specified

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to "not exposed" is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call. (''Since Guard 2.0'')

Parameters:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customisation] for details.

== Entropy ==

Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

Authentication IMAP Plugin description

2017-01-26T07:12:09Z

Malasa:

= Open-Xchange IMAP authentication module =

== Introduction ==
The Open-Xchange IMAP authentication module is used to perform the Open-Xchange authentication against a IMAP server. During login, a IMAP connection is opened with the user credentials given through the Open-Xchange API, e.g. the GUI login mask. If that IMAP connection succeeds, the user is authenticated and finally logged in to its Open-Xchange session.

The module does replace the database authentication module installed by default.

=== IMAP Authentication Matrix ===

The IMAP authentication module has configuration parameters which do influence the username used for the IMAP connection during login. The configuration file is:

/opt/open-xchange/etc/imapauth.properties

The parameters are:

* com.openexchange.mail.loginSource
* USE_FULL_LOGIN_INFO
* USE_MULTIPLE
* USE_FULL_LOGIN_INFO_FOR_USER_LOOKUP (starting with 7.8.1)
* USE_FULL_LOGIN_INFO_FOR_CONTEXT_LOOKUP (starting with 7.8.2)

The following examples make the behavior of that parameters visible. The login string, passed as example to the Open-Xchange login mask, is

user@domain.tld

during the user provisioning, following attributes are set for the context via the createcontext call:

{|
| attribute
| value
|-
| contextname
| domain.tld
|}

and the following parameters via the creatuser call:

{|
| attribute
| value
|-
| imaplogin
| user1337
|-
| username
| user
|-
| email
| exampleuser@otherdomain.tld
|}

com.openexchange.mail.loginSource=login<br />

{| border="1" align="center"
|-
! rowspan="2" colspan="2" | '''Property/Property'''
!colspan="2" | '''USE_FULL_LOGIN_INFO'''
|-
! '''true'''
! '''false'''
|-
!rowspan="2" | '''USE_MULTIPLE'''
! '''true'''
| user1337
| user1337
|-
! | '''false'''
| user@domain.tld
| user
|}

com.openexchange.mail.loginSource=mail<br />

{| border="1" align="center"
|-
! rowspan="2" colspan="2" | '''Property/Property'''
!colspan="2" | '''USE_FULL_LOGIN_INFO'''
|-
! '''true'''
! '''false'''
|-
!rowspan="2" | '''USE_MULTIPLE'''
! '''true'''
| exampleuser@otherdomain.tld
| exampleuser@otherdomain.tld
|-
! | '''false'''
| user@domain.tld
| user
|}

com.openexchange.mail.loginSource=name<br />

{| border="1" align="center"
|-
! rowspan="2" colspan="2" | '''Property/Property'''
!colspan="2" | '''USE_FULL_LOGIN_INFO'''
|-
! '''true'''
! '''false'''
|-
!rowspan="2" | '''USE_MULTIPLE'''
! '''true'''
| user@domain.tld
| user
|-
! | '''false'''
| user@domain.tld
| user
|}

=== IMAP Authentication Extensions ===
Since v7.8.1 the "USE_FULL_LOGIN_INFO_FOR_USER_LOOKUP" property gets introduced. According to the semantics of the "USE_FULL_LOGIN_INFO" property, the "USE_FULL_LOGIN_INFO_FOR_USER_LOOKUP" property controls whether the full login string is supposed to be considered as the internal user name. If set to "true" the full login string is used to look-up the user; e.g. uses "jane@somewhere.org" instead of only "jane".

This is useful for setups, in which the full E-Mail address is used for the internal user name. Please note, that to allow provisioning of full E-Mail addresses the USER_ID check in AdminUser.properties needs to be turned off or allow the '@' character. You have to add the individual E-Mail addresses which belong to a context in the loginmapping (-L for create/changecontext). You can add multiple E-Mail addresses to the loginmapping, separated by a comma.

{{InstallPlugin|pluginname=open-xchange-authentication-imap|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

AppSuite:Context management

2016-11-03T05:36:30Z

Malasa: /* Parameters */ added note to quota for signatures

== createcontext ==

'''<code>createcontext</code>''' is the tool to create new contexts. A context is an independent instance within the createcontext Open-Xchange system and holds users, groups
and resources and all their objects. Data from one context is not visible to other contexts. Module access (calendar, tasks, email) can be set via predefined "access combination names". These
names can be configured on the server side. All users which are created during later use of the "createuser" tool will inherit the module access rights from the context. If you do not specify any
access rights on createcontext minimal access rights will be granted. Currently, these are Webmail and Contacts access rights.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,--contextid <integer>
|The id of the context, when starting with 0, 0 is deleted
|-
| -q,--quota <integer>
|Context wide filestore quota in MB. -1 = unlimited. Note: since 7.8.2 you need quota to store signatures, even you don't use the infostore/drive. Therefore you should always set a small amount so users can store signatures.
|-
| -u,--username <string>
|Username for the new context admin user
|-
| -d,--displayname <string>
|Displayname for the new context admin user
|-
| -g,--givenname <string>
|Given name for the new context admin user
|-
| -s,--surname <string>
|Surname/last name for the new context Admin user
|-
| -p,--password <string>
|Password for the new context Admin user
|-
| -e,--email <string>
|Primary E-Mail address for the new context Admin user
|-
| -l,--lang <lang>
|Language for the new context Admin user
|-
| -t,--timezone <timezone>
|Timezone for the new context Amin user
|-
| -N,--contextname <string>
|Context name
|-
| -L,--addmapping <string>
|Add login mappings separated by ","
|-
| -F,--destination-store-id <integer>
|Specifies the optional file store identifier to which the context gets assigned; if missing the file store gets auto-detected
|-
| -D,--destination-database-id <integer>
|Specifies the optional database identifier to which the context gets assigned; if missing the database gets auto-detected
|-
| --access-combination-name <access-combination-name>
|Access combination name
|-
| --access-denied-portal <on/off>
|Denies portal access (Default is off)
|-
| --csv-import <CSV file>
| Full path to CSV file with user data to import. This option makes mandatory options obsolete, except credential options (if needed).
|}

==== --csv-import <CSV file> ====

Full path to CSV file with user data to import. This option makes mandatory command line options obsolete, except credential options (if needed). But they
have to be set in the CSV file.

With this option you can specify a csv file (a full pathname must be given) with the data which should be imported. The columnnames in the CSV file must be
the same as the long-options of the command line tools, without the prefix "--".

This option will normally be used to fill new large installations with the new data. So instead of calling
the command line tools in a shell script every time, just a csv file needs to be created, containing the whole data.

Note that the credentials of the masteradmin in the createcontext call
must be given on the command line with the -A and -P options nevertheless - if authentication is enabled. If the createuser command line tool is used, the credentials are part of the csv file, and
cannot be set as options on the command line itself. The reason for this different behavior is that different contexts have different credentials for the admin user, so they must be set in every
line of the csv file. Opposed to this the credentials of the masteradmin are always the same.

==== Extra parameters when authentication is enabled ====

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>contextid {adminuser adminpass} quota username displayname givenname surname password email</code>'''

=== Command output ===

On success:

<code>context <contextid> created</code>

On
failure:

<code>context <contextid> could not be created: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/createcontext
-c 123 -q 1000 -N CompanyA -u "admin" -d "Admin of CompanyA" -g John -s Example -p newpw -e john@example.com</code>'''

<code>context 123
created</code>

== deletecontext ==

'''<code>deletecontext</code>''' is the tool to delete contexts and all data stored that belong to it. This includes all database entries and files in the infostore but no
E-Mail components.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,--contextid <contextid>
|The id of the context
|-
| -N,--contextname <contextname>
|Context name
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>(contextid or contexname) {adminuser adminpass}</code>'''

=== Command output ===

On success:

<code>context <contextid> deleted</code>

On failure:

<code>context
<contextid> could not be deleted: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/deletecontext -c
123</code>'''

<code>context 123 deleted</code>

== listcontext ==

'''<code>listcontext</code>''' is the tool to list and search for contexts.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -s,--searchpattern <string>
|Search/List pattern, default “*”
|-
| --csv
|Command output as csv
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <adminuser>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>{adminuser adminpass}</code>'''

=== Command output ===

Standard output:

<pre>cid fid fname enabled qmax qused name
lmappings . . ... ... ... ... ... ...
</pre>

csv output:

<code>id,filestore_id,filestore_name,enabled,max_quota,used_quota,name,lmappings</code>

=== Example ===

<pre>root@oxhe:/opt/open-xchange/sbin# ./listcontexts cid fid fname
enabled qmax qused name lmappings 6 3 6_ctx_store true 1000 0 customerA 6,customerA,secondlogin
</pre>

== disablecontext ==

'''<code>disablecontext</code>''' is the tool to disable contexts. Whenever a customer tries to log in to a disabled context, the login is denied.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,--contextid <integer>
|The id of the context
|-
| -N,--contextname <string>
|Context name
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on
failure

=== Mandatory parameters ===

'''<code>(contextid or
contextname) {adminuser adminpass}</code>'''

=== Command output ===

On
success:

<code>context <contextid> disabled</code>

On failure:

<code>context <contextid> could not be disabled:
<reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/disablecontext -c 123</code>'''

<code>context 123
disabled</code>

== disableallcontexts ==

'''<code>disableallcontexts</code>''' is the tool to disable all contexts. Whenever a customer tries to log in to a disabled context, the login is denied.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user
name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on
failure

=== Mandatory parameters ===

'''<code>{adminuser
adminpass}</code>'''

=== Command output ===

On success:

<code>all contexts disabled</code>

On failure:

<code>all contexts could not be disabled: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/disableallcontexts</code>'''

<code>all contexts disabled</code>

== enablecontext ==

'''<code>enablecontext</code>''' is the tool to enable a disabled context.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from
output
|-
| -c,--contextid <integer>
|The id of the context
|-
| -N,--contextname <string>
|Context name
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <adminuser>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>(contextid or contextname) {adminuser adminpass}</code>'''

=== Command output ===

On success:

<code>context <contextid> enabled</code>

On failure:

<code>context <contextid> could not be enabled: <reason from server></code>

=== Example ===

<code>root@oxhe~#
</code>'''<code>/opt/open-xchange/sbin/enablecontext -c 123</code>'''

<code>context <contextid> enabled</code>

== enableallcontexts ==

'''<code>enableallcontexts</code>''' is the tool to enable all disabled contexts.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from
output
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user name
|-
| -P,--adminpass
<string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>{adminuser adminpass}</code>'''

=== Command output ===

On success:

<code>all contexts enabled</code>

On
failure:

<code>all contexts could not be enabled: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/enableallcontexts</code>'''

<code>all contexts enabled</code>

== getcontextcapabilities ==

'''<code>getcontextcapabilities</code>''' is the tool to list available capabilities for a certain context.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,--contextid <integer>
|The id of the context
|-
| -N,--contextname <contextname>
|context name
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Context Admin user name
|-
| -P,--adminpass <string>
|Context Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===
<code>contextid adminuser adminpass</code>

=== Command output ===

Either "There are no capabilities set for context <context-id>"
or a line-wise listing of identifiers for available capabilities

=== Example ===

<pre> root@oxhe:~# /opt/open-xchange/sbin/getcontextcapabilities -c 6
</pre>

== changecontext ==

'''<code>changecontext</code>''' makes context-wide changes.<br>

If you specify module access options; e.g. "--access-edit-password on"; then please be aware that basic module access set is the one from context's administrator. Meaning any option not explicitly specified as CLI argument will fall-back to context administrator setting for _every_ user in associated context.<br>

You can use changecontext to change the current quota for a given context. When the context has more changecontext space in use than the new quota allows,
the customer is only able to delete files until the usage is below quota. Module access (calendar,tasks,email) can be set via predefined "access combination names". These names can be configured on
the server side. All users which are created during later use of the "createuser" tool will inherit the module access rights from the context. If you do not specify any access rights on
createcontext minimal access rights will be granted. Currently, these are Webmail and Contacts access rights.

There are some default combinations in the ModuleAccessDefinitions.properties
file on the admin server, like:

{| border="1"
|-
|webmail=webmail, contacts, globaladdressbookdisabled, collectemailaddresses, editpassword
|-
|pim=webmail, ''calendar'', contacts, ''tasks'', globaladdressbookdisabled, collectemailaddresses, ''multiplemailaccounts'', ''subscription'', ''publication'', editpassword
|-
|pim_infostore=webmail, calendar, contacts, tasks, ''infostore'', ''webdav'', globaladdressbookdisabled, collectemailaddresses, multiplemailaccounts, subscription, publication
|-
|pim_mobility=webmail, calendar, contacts, tasks, syncml, ''usm'', activesync, globaladdressbookdisabled, collectemailaddresses, multiplemailaccounts, subscription, publication, ''editpassword''
|-
|groupware_standard=webmail, calendar, contacts, infostore, tasks, webdav, ical, vcard, readcreatesharedfolders, delegatetask, editpublicfolders, editgroup, editresource, editpassword, collectemailaddresses, multiplemailaccounts, subscription, publication (Groupware Standard always gets new features except mobility and OXtender. )
|-
|groupware_premium=webmail, calendar, contacts, infostore, tasks, webdav, ''webdavxml'', ical, vcard, ''syncml, ''usm'', ''olox20'', ''activesync'', readcreatesharedfolders, delegatetask, editpublicfolders, editgroup, editresource, editpassword, collectemailaddresses, multiplemailaccounts, subscription, publication
|-
|all=webmail, calendar, contacts, infostore, tasks, webdav, webdavxml, ical, vcard, syncml, usm, olox20, activesync, readcreatesharedfolders, delegatetask, editpublicfolders, editgroup, editresource, editpassword, ''publicfoldereditable'', collectemailaddresses, multiplemailaccounts, subscription, publication (This is a right tailored to a context administrator)
|}

'''Note:''' Italics denote additional rights in comparison to the previous set where applicable.

When having changed the access rights of the context and its users with "changecontext" the "downgrade" command should be called on the admin server. All unnecessary data are removed from
the data base via "groupware api". If e. g. the context 1 is changed from "pim_infostore" to "webmail", the "downgrade" command has to be called for this context then. Then, all unnecessary
folders for this context are removed from the data base.

=== Parameters ===

{| border="1"
|-
| -h,- -help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,- -contextid <integer>
|The id of the context
|-
| -N,- -contextname <string>
|The name of the context
|-
| -L,- -addmapping <string(s)>
|Add login mappings. Separated by ","
|-
| -R,- -removemapping <stirng(s)>
|Remove login mappings. Separated by ","
|-
| -q,- -quota <integer>
|Quota for the context filestore in MB
|-
| --access-combination-name <access-combination-name>
|Access combination name
|-
| --capabilities-to-add <capabilities-to-add>
| The capabilities to add as a comma-separated string (from 7.2.0 on)
|-
| --capabilities-to-remove <capabilities-to-remove>
| The capabilities to remove as a comma-separated string (from 7.2.0 on)
|-
| --capabilities-to-drop <capabilities-to-drop>
|The capabilities to drop; e.g. cleanse from storage; as a comma-separated string (from 7.6.0 on)
|-
| --quota-module <quota-module>
|The identifier of the module to which to apply the quota value (from 7.2.0 on)
|-
| --quota-value <quota-value>
| from v7.2.0 on: The quota value; zero is unlimited<br>from v7.6.0 on: The numeric quota value specifying the max. number of items allowed for context. Zero is unlimited. A value less than zero deletes the quota entry (and falls back to configured behavior)
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,- -adminuser <string>
|Master Admin user name
|-
| -P,- -adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on
failure

=== Mandatory parameters ===

'''<code>(contextid or
contextname) {adminuser adminpass} and at minimum one attribute to change</code>'''

=== Command output ===

On success:

<code>context <contextid> changed</code>

On failure:

<code>context
<contextid> could not be changed: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/changecontext -c 123 -q
500</code>'''

<code>context 123 changed</code>

== getAdminId ==

Returns the ID of the context administrator.

[[Category: Administrator]]

[[Category: AppSuite]]
[[Category: AdminGuide]]
[[Category: CommandLineTools]]

ContextRestore Bundle

2016-10-05T10:42:39Z

Malasa:

= Context Restore Documentation =

== Introduction ==

This document contains descriptions about the context restore bundle. This
bundle is a solution for restoring one single context out of a mysql dump from
a complete Open-Xchange database. In a distributed setup, it is possible to use
several files containing the dumps of different databases. The tool described
within this document does fetch the needed information out of these files.

== Limitations ==

You must not delete the last context from within a database schema.
If you just have ONE context left in your system, do NOT delete it.
That is because the deletion of the last contexts leads into deletion of the entire schema.
In that case, you have to restore a complete database dump. restorecontext will not work in that case.

== Requirements ==

For correct operation, it is required that the mysql dumps for this tool
represent a consistent state of all databases the Open-Xchange server has under
control. Furthermore this consistent state needs also to include the backup of
the filestore.

{{InstallPlugin|pluginname=open-xchange-admin-plugin-contextrestore|sopath=stable|version=7.x}}

After the package has been installed, a new shell script named
<tt>/opt/open-xchange/sbin/restorecontext</tt> The server needs to be
restarted to make the new functionality available. The functionality is
accessible via RMI, CLT and SOAP.

== Usage ==

A complete database backup has to be done before the new function can be used.
The Tool described within this document requires a full SQL dump of the
databases involved. This can be done by executing the command

$ mysqldump --all-databases --single-transaction --hex-blob

on all database machines registered in Open-Xchange as well as the
configuration Database. These three parameters are very important. The first one
lets the dump contain every database on the specified database host, the
second is used for a consistent backup and the third one is used to let all binary data
appear as hex in the dump. Instead of <tt>–-all-databases</tt> you can also
use <tt>–-database</tt> with the right database(s), if none of the switches are given as
direct argument then mysql will left out essential data in the dump. For a full
backup the switch <tt>--all-databases</tt> is recommended.

The usage of the command line tool is self-explanatory as it confirms to the
standard unix behavior. <tt>--help</tt> will show a short help with the available
parameters.

The main arguments of the tool are different database dumps (from the configdb
and the distributed user data databases). On success the tool returns the path to
the filestore of the given context. The files below this path have to be restored
afterwards in a separate process which is not part of the Open-Xchange system.
An example of a restore would look like this:

$ restorecontext -A oxadminmaster -P secret -c 1 \
-f /path/to/configdb.sql,/path/to/userdb.sql,/path/to/userdb1.sql,...

'''Note:''' restorecontext will only restore data from the database, not from the filestore. During the restore the context and the filestore content will be deleted, so make a backup first or if you deleted an context by accident you have to restore the filestore content after restorecontext.

=== Old dump without --hex-blob ===

If you have done a dump according to a former version of this document the dump contains the
direct binary data which can't be understood by the restore tool. You will get errors like
"Data truncation: Data too long for column 'uuid' at row 1".

'''ATTENTION: The steps below need to be done on a NEW MySQL instance NOT the productive one.'''

To get the correct version of the dump you need to apply the dump to a clean MySQL database.
If the dump was created with <tt>--all-databases</tt> you can just pipe the contents into mysql:
<tt>mysql < mydump.txt</tt>. If you have different dump for each database you have to create
the corresponding database in MySQL first. The name of the database to be created can be found at
the beginning of the dump file
<code>
-- Host: localhost Database: configdb
</code>
So for the example simply issue <tt>create database configdb</tt> and apply the dump directly to
this database: <tt>mysql configdb < mydump.txt</tt> (pay attention to give the name of the database
to mysql in this case).
Afterwards just create the mysqldump from this database with the correct --hex-blob parameter.

ContextRestore Bundle

2016-10-05T09:39:20Z

Malasa:

= Context Restore Documentation =

== Introduction ==

This document contains descriptions about the context restore bundle. This
bundle is a solution for restoring one single context out of a mysql dump from
a complete Open-Xchange database. In a distributed setup, it is possible to use
several files containing the dumps of different databases. The tool described
within this document does fetch the needed information out of these files.

== Limitations ==

You must not delete the last context from within a database schema.
If you just have ONE context left in your system, do NOT delete it.
That is because the deletion of the last contexts leads into deletion of the entire schema.
In that case, you have to restore a complete database dump. restorecontext will not work in that case.

== Requirements ==

For correct operation, it is required that the mysql dumps for this tool
represent a consistent state of all databases the Open-Xchange server has under
control. Furthermore this consistent state needs also to include the backup of
the filestore.

{{InstallPlugin|pluginname=open-xchange-admin-plugin-contextrestore|sopath=stable|version=7.x}}

After the package has been installed, a new shell script named
<tt>/opt/open-xchange/sbin/restorecontext</tt> The server needs to be
restarted to make the new functionality available. The functionality is
accessible via RMI, CLT and SOAP.

== Usage ==

A complete database backup has to be done before the new function can be used.
The Tool described within this document requires a full SQL dump of the
databases involved. This can be done by executing the command

$ mysqldump --all-databases --single-transaction --hex-blob

on all database machines registered in Open-Xchange as well as the
configuration Database. These three parameters are very important. The first one
lets the dump contain every database on the specified database host, the
second is used for a consistent backup and the third one is used to let all binary data
appear as hex in the dump. Instead of <tt>–-all-databases</tt> you can also
use <tt>–-database</tt> with the right database(s), if none of the switches are given as
direct argument then mysql will left out essential data in the dump. For a full
backup the switch <tt>--all-databases</tt> is recommended.

The usage of the command line tool is self-explanatory as it confirms to the
standard unix behavior. <tt>--help</tt> will show a short help with the available
parameters.

The main arguments of the tool are different database dumps (from the configdb
and the distributed user data databases). On success the tool returns the path to
the filestore of the given context. The files below this path have to be restored
afterwards in a separate process which is not part of the Open-Xchange system.
An example of a restore would look like this:

$ restorecontext -A oxadminmaster -P secret -c 1 \
-f /path/to/configdb.sql,/path/to/userdb.sql,/path/to/userdb1.sql,...

Note: restorecontext will only restore data from the database, not from the filestore. During the restore the filestore content for the context will be deleted, so make a backup first or if you deleted an context by accident you have to restore the filestore content after restorecontext.

=== Old dump without --hex-blob ===

If you have done a dump according to a former version of this document the dump contains the
direct binary data which can't be understood by the restore tool. You will get errors like
"Data truncation: Data too long for column 'uuid' at row 1".

'''ATTENTION: The steps below need to be done on a NEW MySQL instance NOT the productive one.'''

To get the correct version of the dump you need to apply the dump to a clean MySQL database.
If the dump was created with <tt>--all-databases</tt> you can just pipe the contents into mysql:
<tt>mysql < mydump.txt</tt>. If you have different dump for each database you have to create
the corresponding database in MySQL first. The name of the database to be created can be found at
the beginning of the dump file
<code>
-- Host: localhost Database: configdb
</code>
So for the example simply issue <tt>create database configdb</tt> and apply the dump directly to
this database: <tt>mysql configdb < mydump.txt</tt> (pay attention to give the name of the database
to mysql in this case).
Afterwards just create the mysqldump from this database with the correct --hex-blob parameter.

AppSuite:ExternalLoginPage

2016-08-24T12:06:08Z

Malasa:

= How to set up an external login page for App Suite =

== Who should read this document ==

This document is written for web developers who would like to create a custom login mask for the OX App Suite. The login mask can reside on an external server i. e., not directly located in the domain of the Open-Xchange machines. It is also intended for administrators who install and maintain Open-Xchange services.

== HTML ==

The Open-Xchange [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (Form login)] has a function to
create a session from external.

The full detailed explanation how the HTML form is used and errors can be handled can be found here:

[[OXSessionFormLogin|OX Session Formlogin]]

== Redirect to custom login ==

Users can still access the original product login site. If this is not wanted the following Apache
configuration for your VirtualHost can be used to redirect all requests to your custom login page:

before 7.8.0:

RewriteEngine On
RewriteRule ^/appsuite/signin /custom-login.html [R]

Since 7.8.0 it can be configured directly in <code>/opt/open-xchange/etc/as-config.yml</code>
<pre>
# Override certain settings
default:
host: all
loginLocation: 'http://example.com/appsuite/mycustomlogin.html'
</pre>
Note: you need to have the right syntax (like leading spaces) in the .yml file.

It is possible to have different login pages for different domains, just add another section with a different host: <mydomain.com> line.

== Setting custom login as logout location ==

If users should be directed to the custom login form after logout from App Suite the following property can be set globally somewhere in /opt/open-xchange/etc/settings/. Either create a new properties file or add the option in any existing one. For more complex setups e.g. with different brands please check out how to set this property in context or user scope which is explained [[ConfigCascade|here]].

io.ox/core//customLocations/logout=https://login.example.com

For cases where only one custom login page exists for all users it's also recommended to set

logoutLocation: 'https://login.example.com/'

in '''/opt/open-xchange/etc/as-config.yml'''. This setting takes effect for example if an autologin session is expired. as-config.yml itself defines settings in dependence of the hostname configured for the Open-Xchange access.

AppSuite:OX Drive

2016-04-18T12:11:36Z

Malasa: /* 7.8.0 and earlier */

= OX Drive =

In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. It provides file- and folder synchronization across multiple devices in the most simplest way for the end user, fully optimized for each device type. This article explains how to set up the server-side components for OX Drive, as well as details about the app setup.

== Key features ==

* Native Apps for Windows, Mac OS, iOS and Android
* Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)
* Apps are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.
* Controlled synchronization of files across devices
* Storage management (e.g. quota control, upload limits)
* Connection type recognition and adaptation (e.g. Wi-Fi, cell network)

== Availability ==

OX Drive is a combination of two components:
* OX Drive in OX App Suite
* OX Drive Apps (optional native app components for synchronization)

OX Drive is available for the following native apps:
* OX Drive for Windows
* OX Drive for Mac OS
* OX Drive for iOS
* OX Drive for Android

== Requirements ==

You will find the requirements under [[AppSuite:OX_System_Requirements#OX_Drive_for_Clients|OX Drive App and Platform Requirements]]

= Server-side Installation and Configuration =

This chapter describes how the backend components of OX Drive are installed and configured on the server.

== Prerequisites ==

* Open-Xchange Server v7.4.2 and above (''open-xchange-core'')
* Grizzly HTTP connector (''open-xchange-grizzly''), see [[AppSuite:Grizzly]] for details, with ''Comet'' support enabled in ''grizzly.properties''
* Valid Push-Certificates / API keys for cloud-based notifications, see configuration below
* Enabled Hazelcast for inter-OX-communication, see [[AppSuite:Running_a_cluster]] for details

== Available packages ==

Open-Xchange Drive is available with the following backend packages:

* ''open-xchange-drive'' - The main server components for OX Drive
* ''open-xchange-drive-comet'' - Provides the Push interface via long-polling for the desktop apps
* ''open-xchange-drive-help-*'' - Online help in various languages for the OX Drive applications (these were called ''open-xchange-appsuite-help-drive-*'' in versions earlier than Open-Xchange Server v7.6.2)
* ''open-xchange-drive-restricted'' - Restricted components, including prerequisites for cloud-based push notifications

Installation on the server varies depending on the underlying distribution, details are available in the following chapters.

=== OX Drive for Windows ===

Additionally OX Drive for Windows can be provided to users by installing additional packages. However there are significant differences between 7.8.0 and earlier releases and 7.8.1 and later ones:

==== 7.8.0 and earlier ====

OX Drive for Windows can be provided via the [[AppSuite:Open-Xchange_Updater|Open-Xchange Updater]] by installing the package ''open-xchange-updater-drive''. Initial installation and updates are performed by the Updater then. You don't have to add the repositories below.

==== 7.8.1 and later ====

With OX App Suite 7.8.1 and OX Drive for Windows 2.0.0, the app is able to update itself and can be downloaded from the Web UI directly via the [[AppSuite:Client_Onoarding|App Onboarding Wizard]]. Therefore the wizard must be installed and configured for OX Drive users. Besides the client onboarding feature you need the following packages:

* ''open-xchange-drive-client-windows'' - The main server component to provide the app
* ''open-xchange-drive-client-windows-generic'' - The package providing the final binary files to be installed on users machines.

To make the app download available via the app onboarding wizard, you need to enable the according scenario. Edit ''/opt/open-xchange/etc/client-onboarding-scenarios.yml'' and get to the ''drivewindowsclientinstall'' section, where you have to set the ''enabled'' property to ''true''.

Please note that there still exists a compatibility layer between the old Updater-based approach and the new direct install and self-update one. If you start providing OX Drive for Windows with 7.8.1 or later you MAY decide to enable that compatibility by installing ''open-xchange-updater-drive'', however we advice not to do so. If you already provided OX Drive for Windows with 7.8.0 or earlier, you MUST install this package and further provide the Updater. Otherwise the apps out there will not be able to be updated to the 2.0.0 version, which is then self-update capable.

===== Custom branded apps =====

OX Drive for Windows can be purchased with a custom theming. In such cases, the according binary files need to be installed on the middleware servers. Instead of the ''open-xchange-drive-client-windows-generic'' package, a package containing the branded binaries will be provided as ''open-xchange-drive-client-windows-<brand-name>'' and needs to be installed. You MUST then set the property ''com.openexchange.drive.update.branding'' in ''/opt/open-xchange/etc/drive-client-windows.properties'' to ''<brand-name>'' accordingly.

It is also possible to provide multiple brands of the app via the same OX App Suite deployment, multiple ''open-xchange-drive-client-windows-<brand-name>'' packages can be installed in parallel. Which brand is available for a certain user is determined by the ''com.openexchange.drive.update.branding'' property, which can be overwritten via [[ConfigCascade|Config Cascade]] therefore.

App brands can be managed via command line tools. The tool ''/opt/open-xchange/sbin/listdriveclients'' lists all installed brands. After updating a certain brand by installing a newer package version or installing an additional one, no server restart is necessary. Instead ''/opt/open-xchange/sbin/reloaddriveclients'' can be executed to refresh the internal server state.

=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, 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|backend}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|drive-help}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-windows}}

and run

$ yum update
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, 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=RHEL7|backend}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|drive-help}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-windows}}

and run

$ yum update
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows

=== Debian GNU/Linux 7.0 ===

If not already done, 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=DebianWheezy|backend}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|drive-help}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-windows}}

and run

$ apt-get update
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows

=== Debian GNU/Linux 8.0 ===

If not already done, 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=DebianJessie|backend}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|drive-help}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-windows}}
and run

$ apt-get update
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|backend}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|drive-help}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-windows}}

and run

$ zypper ref
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|backend}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|drive-help}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-windows}}

and run

$ zypper ref
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows

=== OX Server Edition / App Suite for UCS ===

If you have purchased the OX Server Edition / App Suite for UCS, the OX Drive is part of the offering and after the installation/update available. The necessary package for push, is available with a valid license and can be installed via the Univention App Center.

* The new license is already registered at the LDB after purchase.
* Log on at the Univention Management Console (UMC)
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"
* Within the component list, select "Open-Xchange Drive" and press the "Install" button

== Configuration ==

The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the apps.

All settings regarding the OX Drive backend component are located in the configuration file ''drive.properties''. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based app notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options.

=== Push via Google Cloud Messaging (GCM) ===

The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.android.com/google/gcm/index.html Google Cloud Messaging (GCM)]. To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android app application. The API key is included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" Android app. Alternatively, the key can be specified directly in the ''drive.properties'' configuration file:

# Specifies the API key of the server application. Required if
# "com.openexchange.drive.events.gcm.enabled" is "true" and the package
# containing the restricted drive components is not installed.
com.openexchange.drive.events.gcm.key=

Push via GCM can be enabled via:

# Enables or disables push event notifications to apps using the Google
# Cloud Messaging (GCM) service. This requires a valid configuration for the
# GCM API key, see options below. Defaults to "false".
com.openexchange.drive.events.gcm.enabled=true

Please note that push via GCM needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.

=== Push via Apple Push Notification service (APNs) ===

The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.apple.com/library/IOS/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html Apple Push Notification service (APNs)]. To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop app and the iOS mobile app are served separately with different certificates, so that both needs to be configured independantly. The required certificates are already included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" iOS and Mac OS app applications. Therefore no additional configuration is needed. Alternatively, a external certificate can be specified directly in the ''drive.properties'' configuration file (the following only shows the setup for iOS). First, the path to the PKCS #12 container file needs to be specified at:

# Specifies the path to the local keystore file (PKCS #12) containing the APNS
# certificate and keys for the iOS application, e.g.
# "/opt/open-xchange/etc/drive-apns.p12". Required if
# "com.openexchange.drive.events.apn.enabled" is "true" and the package
# containing the restricted drive components is not installed.
com.openexchange.drive.events.apn.ios.keystore=

This file is opened by the backend using the password as supplied via:

# Specifies the password used when creating the referenced keystore containing
# the certificate of the iOS application. Note that blank or null passwords
# are in violation of the PKCS #12 specifications. Required if
# "com.openexchange.drive.events.apn.enabled" is "true" and the package
# containing the restricted drive components is not installed.
com.openexchange.drive.events.apn.ios.password=

Configuration also allows to switch between development and production environments, however, this setting should be ''true'' normally:

# Indicates which APNS service is used when sending push notifications to iOS
# devices. A value of "true" will use the production service, a value of
# "false" the sandbox service. Defaults to "true".
com.openexchange.drive.events.apn.ios.production=true

The OX backend contacts the APNs servers from time to time to get informed about apps no longer reachable apps where the applications was uninstalled. The interval can be defined with the following setting:

# Configures the interval between queries to the APN feedback service for the
# subscribed iOS devices. The value can be defined using units of measurement:
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day).
# Leaving this parameter empty disables the feedback queries on this node.
# Since each received feedback is processed cluster-wide, only one node in the
# cluster should be enabled here.
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D

Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:

# Enables or disables push event notifications to apps using the Apple Push
# Notification service (APNS) for Mac OS devices. This requires a valid
# configuration for the APNS certificate and keys, see either options below,
# or install the restricted components packages for drive. Defaults to
# "false".
com.openexchange.drive.events.apn.ios.enabled=false

As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with ''com.openexchange.drive.events.apn.macos''. Please also note that push via APNS needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.

=== Further Configuration ===

* The backend component of OX Drive supplies the apps with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via ''com.openexchange.UIWebPath'' located in ''server.properties''.
* As already mentioned above, the backend relies on the [https://grizzly.java.net/comet.html Comet] component of the Grizzly http connector for sending push notifications to the desktop apps. Therefore, ''com.openexchange.http.grizzly.hasCometEnabled'' needs to be set to ''true'' in ''grizzly.properties''.

= Enabling OX Drive for Users =

OX Drive is enabled for all users that have the capability ''com.openexchange.capability.drive''. Please note that users need to have the ''infostore'' permission set to use drive. So the users that have ''drive'' enabled must be a subset of those users with ''infostore'' permission. Since 7.6.0 we enforce this via the default configuration. You can also enable this cabaility globally with the following setting in the ''drive.properties'' configuration file:

# Enables or disables the "drive" module capability globally. The capability
# can also be set more fine-grained via config cascade. Per default it is only
# enabled for users that have the "infostore" permission set. This is configured
# in /opt/open-xchange/etc/contextSets/drive.yml.
com.openexchange.capability.drive=false

More details about capabilities can be found at [[AppSuite:Capabilities]]. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at [[ConfigCascade]].

= Installation of the Apps =

== Installation of Mac OS X Desktop App ==

The OX Drive for Mac OS X will be provided via the Apple App Store:

* https://itunes.apple.com/app/ox-drive/id818195014?mt=12

=== Enabling the Finder Extension on Mac OS X ===

In order to be able to use the Finder to open documents or share objects on a Mac OS X workstation, you need to enable the Drive Finder Extension.

How to enable the Drive Finder Extension on a Mac OS X workstation:
# Open the System Preferences. In the System Preferences window, select Extensions.
# In the Extensions window, select Finder. Enable Drive Finder Extension.

== Installation of Windows Desktop App ==

See [[AppSuite:OX_Drive#OX_Drive_for_Windows|OX Drive for Windows]].

== Installation on Mobile Apps ==

The OX Drive App is available via the different App Stores:

* iOS: https://itunes.apple.com/app/ox-drive/id798570177?mt=8

* Android: https://play.google.com/store/apps/details?id=com.openexchange.drive.vanilla

== App Configuration and Deployment ==

The user needs to enter the server URL and provide his username and password. Afterwards, app-specific settings may be configured. This includes the synchronization mode (All files / Favorites only) and Photostream settings on mobile devices, or the local root synchronization folder for the desktop applications. More information is available in the online documentation.

After the initial synchronization is completed, all further changes are synchronized instantly across all devices.

= FAQ =

You will find it under [http://knowledgebase.open-xchange.com/sales-marketing/additional-software/frequently-asked-questions/ox-drive-for-clients.html OX Drive App and Platform FAQ].

AppSuite:Embedding your settings into AppSuite settings

2016-02-15T12:14:01Z

Malasa: added settings folder, advancedMode info

<div class="title">Embedding your settings into AppSuite settings</div>

''Synopsis:'' This article explains how you can embed your own configuration page via iFrame into the AppSuite's settings and pass our session onto your implementation. This is a replacement for "Config Jump" of OX6. Not to be confused with [[AppSuite:Creating_a_settings_section_in_AppSuite_settings | simply adding new settings]] into AppSuite

__TOC__

== Declare the page you want to embed ==

Before you start you need to know the group where you want to add the settings (since 7.8.0):
<pre>
gerneral:
Basic Settings
Accounts

main:
Portal
Mail
Guard
Address Book
Calendar
Tasks
Drive

tools:
Pubications and Subscriptions
Error Log
Download

external:
Groups
Resources
</pre>

Note: the layout of the settings page might differ depending on which packages you have installed and/or which capabilities the user has.

You can declare pages to embed via [[ConfigCascade|Config Cascade]] settings. There are several ways to do so, this example uses the most comfortable one, a YAML declaration:

➜ /opt/open-xchange/etc/settings/configjump.yml
io.ox/settings/configjump//changePlans:
url: "http://localhost/~fla/changePlans.php?token=[token]"
group: general
title: "Change Plan"
before: "io.ox/settings/accounts"
advancedMode: false # not needed anymore for 7.8.0

''io.ox/settings/configjump'' contains one object per embedded page (e.g. "changePlans"). If you want to add more pages, follow this pattern.

An object of this type has the following properties:

* '''url''': The URL to be branched to. The place holder [token] will be replaced by the token you get from the token login system
* '''title''': The title as to be seen on the settings page.
* '''group''': Settings section where the page is supposed to appear. Valid groups are: "general", "main", "tools", and "external". Default is "tools". For settings inside folders you have to use the group and the name of the config object, for example: group: main/io.ox/mail
* '''after''', '''before''' or '''index''': To define the exact location of the page. ''Hint:'' If you want to name a page as reference (as opposed to using the index), you need to figure out the name. One way to do so is go to that page in the settings and check for the id parameter in the URL (for example http://my.ox/appsuite/#!!&app=io.ox/settings&folder=virtual/settings/io.ox/tasks will be io.ox/tasks)

It's also possible to provide custom translations for the title. Just add "title_" plus the locale:

io.ox/settings/configjump//changePlans:
url: "http://localhost/~fla/changePlans.php?token=[token]"
title: "Change Plan"
title_en_US: "Change plan"
title_de_DE: "Plan ändern"
title_fr_FR: "..."
...
after: "io.ox/mail"

== Create a secret ==

Now you just need to declare the app your are about to embed in the backend and you are good to go:

➜ cat /opt/open-xchange/etc/tokenlogin-secrets
#
# Listing of known Web Application secrets followed by an optional semicolon-separated parameter list
#
# e.g. 1254654698621354; accessPasword=true
#

# Dummy entry
# 1234-56789-98765-4321; accessPassword=true
12345-phpapp-54321

This secret, combined with the token, can be traded for a login.

== Redeem a token ==

GET /login?action=redeemToken

* '''token''': The token you want to trade.
* '''secret''': A valid secret for your app.

This request can be sent by the embedded app to the AppSuite backend to get authorisation info.

[[Category:AppSuite]]

[[Category:UI]][[Category:Backend]]

[[Category:Administrator]][[Category:Developer]]

== Stuck somewhere? ==
You got stuck with a problem while developing? OXpedia might help you out with the article about [[AppSuite:Debugging_the_UI | debugging the UI]].

AppSuite:Embedding your settings into AppSuite settings

2016-02-15T10:20:53Z

Malasa: added overview of groups

<div class="title">Embedding your settings into AppSuite settings</div>

''Synopsis:'' This article explains how you can embed your own configuration page via iFrame into the AppSuite's settings and pass our session onto your implementation. This is a replacement for "Config Jump" of OX6. Not to be confused with [[AppSuite:Creating_a_settings_section_in_AppSuite_settings | simply adding new settings]] into AppSuite

__TOC__

== Declare the page you want to embed ==

Before you start you need to know the group where you want to add the settings (since 7.8.0):
<pre>
gerneral:
Basic Settings
Accounts

main:
Portal
Mail
Guard
Address Book
Calendar
Tasks
Drive

tools:
Pubications and Subscriptions
Error Log
Download

external:
Groups
Resources
</pre>

Note: the layout of the settings page might differ depending on which packages you have installed and/or which capabilities the user has.

You can declare pages to embed via [[ConfigCascade|Config Cascade]] settings. There are several ways to do so, this example uses the most comfortable one, a YAML declaration:

➜ /opt/open-xchange/etc/settings/configjump.yml
io.ox/settings/configjump//changePlans:
url: "http://localhost/~fla/changePlans.php?token=[token]"
group: general
title: "Change Plan"
before: "io.ox/settings/accounts"
advancedMode: false

''io.ox/settings/configjump'' contains one object per embedded page (e.g. "changePlans"). If you want to add more pages, follow this pattern.

An object of this type has the following properties:

* '''url''': The URL to be branched to. The place holder [token] will be replaced by the token you get from the token login system
* '''title''': The title as to be seen on the settings page.
* '''group''': Settings section where the page is supposed to appear. Valid groups are: "general", "main", "tools", and "external". Default is "tools".
* '''after''', '''before''' or '''index''': To define the exact location of the page. ''Hint:'' If you want to name a page as reference (as opposed to using the index), you need to figure out the name. One way to do so is go to that page in the settings and check for the id parameter in the URL (for example http://my.ox/appsuite/#!!&app=io.ox/settings&folder=virtual/settings/io.ox/tasks will be io.ox/tasks)

It's also possible to provide custom translations for the title. Just add "title_" plus the locale:

io.ox/settings/configjump//changePlans:
url: "http://localhost/~fla/changePlans.php?token=[token]"
title: "Change Plan"
title_en_US: "Change plan"
title_de_DE: "Plan ändern"
title_fr_FR: "..."
...
after: "io.ox/mail"

== Create a secret ==

Now you just need to declare the app your are about to embed in the backend and you are good to go:

➜ cat /opt/open-xchange/etc/tokenlogin-secrets
#
# Listing of known Web Application secrets followed by an optional semicolon-separated parameter list
#
# e.g. 1254654698621354; accessPasword=true
#

# Dummy entry
# 1234-56789-98765-4321; accessPassword=true
12345-phpapp-54321

This secret, combined with the token, can be traded for a login.

== Redeem a token ==

GET /login?action=redeemToken

* '''token''': The token you want to trade.
* '''secret''': A valid secret for your app.

This request can be sent by the embedded app to the AppSuite backend to get authorisation info.

[[Category:AppSuite]]

[[Category:UI]][[Category:Backend]]

[[Category:Administrator]][[Category:Developer]]

== Stuck somewhere? ==
You got stuck with a problem while developing? OXpedia might help you out with the article about [[AppSuite:Debugging_the_UI | debugging the UI]].

AppSuite:Banner

2016-02-10T12:11:43Z

Malasa:

This information is valid for 7.8.0

Since AppSuite 7.8.0 it is possible to have a banner on top of the application:

[[File:Banner.png]]

By default the banner is disabled, to use it edit <code>/opt/open-xchange/etc/settings/appsuite.properties</code> and add:
<pre>
io.ox/core//banner/visible=true
</pre>

To change the default values you have to add them to <code>/opt/open-xchange/etc/as-config.yml</code>
<pre>
default:
host: all
bannerCompany: 'mycompany'
bannerProductName: 'myproductname'
bannerHeight: 60
</pre>
note: the leading spaces are important in a .yml file.

This would enable and change the company/product name for all hosts/users. A more fine grained configuration is possible via the configcascade.

File:Banner.png

2016-02-10T12:10:35Z

Malasa:

AppSuite:Banner

2016-02-10T12:10:19Z

Malasa: Created page with "This information is valid for 7.8.0 Since AppSuite 7.8.0 it is possible to have a banner on top of the application File:Banner.png By default the banner is disabled, to..."

This information is valid for 7.8.0

Since AppSuite 7.8.0 it is possible to have a banner on top of the application

[[File:Banner.png]]

By default the banner is disabled, to use it edit <code>/opt/open-xchange/etc/settings/appsuite.properties</code> and add:
<pre>
io.ox/core//banner/visible=true
</pre>

To change the default values you have to add them to <code>/opt/open-xchange/etc/as-config.yml</code>
<pre>
default:
host: all
bannerCompany: 'mycompany'
bannerProductName: 'myproductname'
bannerHeight: 60
autoStart: "io.ox/contacts/main"
</pre>
note: the leading spaces are important in a .yml file.

This would enable and change the company/product name for all hosts/users. A more fine grained configuration is possible via the configcascade.

AppSuite:ExternalLoginPage

2016-01-19T08:28:37Z

Malasa: /* Redirect to custom login */ added as-config.yml

= How to set up an external login page for App Suite =

== Who should read this document ==

This document is written for web developers who would like to create a custom login mask for the OX App Suite. The login mask can reside on an external server i. e., not directly located in the domain of the Open-Xchange machines. It is also intended for administrators who install and maintain Open-Xchange services.

== HTML ==

The Open-Xchange [[HTTP_API#Form_Login_.28since_6.20.29|HTTP API]] has a function to
create a session from external.

The full detailed explanation how the HTML form is used and errors can be handled can be found here:

[[OXSessionFormLogin|OX Session Formlogin]]

== Redirect to custom login ==

Users can still access the original product login site. If this is not wanted the following Apache
configuration for your VirtualHost can be used to redirect all requests to your custom login page:

RewriteEngine On
RewriteRule ^/appsuite/signin /custom-login.html [R]

Since 7.8.0 it can be configured directly in <code>/opt/open-xchange/etc/as-config.yml</code>
<pre>
# Override certain settings
default:
host: all
loginLocation: 'http://example.com/appsuite/mycustomlogin.html'
</pre>
Note: you need to have the right syntax (like leading spaces) in the .yml file.

== Setting custom login as logout location ==

If users should be directed to the custom login form after logout from App Suite the following property can be set globally somewhere in /opt/open-xchange/etc/settings/. Either create a new properties file or add the option in any existing one. For more complex setups e.g. with different brands please check out how to set this property in context or user scope which is explained [[ConfigCascade|here]].

io.ox/core//customLocations/logout=https://login.example.com

For cases where only one custom login page exists for all users it's also recommended to set

logoutLocation: 'https://login.example.com/'

in '''/opt/open-xchange/etc/as-config.yml'''. This setting takes effect for example if an autologin session is expired. as-config.yml itself defines settings in dependence of the hostname configured for the Open-Xchange access.

AppSuite:Xing

2015-11-23T08:09:50Z

Malasa: new xing workflow, new screenshot

= Using Xing with OX App Suite =

This page describes how to get an API-key needed for the XING integration features available starting with App Suite version 7.6.

== Preparation ==

* go to https://dev.xing.com/login
* log in with a valid xing account. (Please note that upon entering production status the app and the personal account used to create it will be decoupled. So there is no need to use a company account here.)
* click "+ Create App" in the upper right

=== 1 App details ===
* enter reasonable app and developer details
* the app information (including logo) is what will be shown to the enduser when he decides whether to allow the app access to his xing-data
* set the domain of your App Suite server as "Callback domain" (e.g. "https://beta.ox.io/")
* enter a text for "Description (English)":

<code>
Use this connector to synchronize your XING contacts with Open-Xchange App Suite, see the public XING-profile of people sending you email, synchronize your personal information with your XING-profile, see and write XING messages and connect via XING to your contacts from within Open-Xchange App Suite. For this we humbly require the access rights to your profile and connection information you see above.<br>
The XING activity stream will be shown in a widget of the OX App Suite portal. With this widget you can also manually update your XING status.<br>
You will be able to post updates from the OX App Suite portal that contain links.<br>
The personal data of your XING-profile can be updated with your data in the OX App Suite addressbook with the press of one button whenever you want.<br>
</code>
* (This text is provided as an example for you to adapt or translate as required.)
<br>

=== 2 Access rights ===
* select access rights so they match those in this screenshot
[[Image:xing-screenshot2.png|400px|Screenshot 1, showing the rights to request]]

=== 3 User data ===
Select "Basic Data"

=== 4 Developer Details ===
Enter your address where the production key should be send to.

=== 5 OAuth ===
enter the URL of your server.

* You should received an email from Xing after finishing the process.
* The production key will be send by mail.(sent via _regular_ mail to the postal address given under "Company Profile". Please note that this may take up to a week.)

* you will see 2 API-keys: "Consumer key" and "Consumer secret".
* enter those keys in /opt/open-xchange/etc/xingoauth.properties
* If your OX server is reachable only via one host name, you won't have to do anything else.
* If your OX server is reachable by more than one host name, create or open the file "/opt/openexchange/etc/deferrer.properties" and set the properties therein as such:
com.openexchange.http.deferrer.url=https://mymaindomain.invalid

File:Xing-screenshot2.png

2015-11-23T08:06:04Z

Malasa: xing permissions

xing permissions

User:Malasa

2015-09-10T07:46:53Z

Malasa:

Hello world - justatest

---- everthing below is wip ----

==POC installation==

This document shows the requirements of some typical proof of concept installations.

A POC can be make with different setups, depending on the goal of the installation.

The goals could be:
* test Open-Xchange in general
* test with existing environment
* test a clustered setup

It should be defined what the customer wants to test:
* webmail/groupware/infostore
* Outlook oxtender
* Business mobility (EAS)
* mobile gui
* everything

Here are some examples of the sizing of a POC installation. Usually 'small' should do it, if the customer wants to test with a lot of accounts (especially also EAS/Outlook) 'medium' is recommended.

{| class="poc size"
|-
|
! small
! medium
! cluster
|-
| Hardware
| VM, 2GB memory
| VM, 8GB memory
| 2x OX 8GB, 2x DB, external IMAP/SMTP, NFS, loadbalancer
|-
| Storage
| 20GB local
| 40GB local
| OX 40GB local, DB 20GB local, NFS 20GB
|-
| DB
| local
| local
| 2x DB VM/Server
|-
| SMTP/IMAP
| local/external
| local/external
| external
|-
|OS
|colspan="3" style="text-align: center;" |one of the supported (Debian6, RHEL5/6, CentOS5, SLES11)
|}

These are the minimum requirements. The used storage depends on the amount of users want to test the POC. A VM can be replaced with real hardware if wanted or run at a service provider in the cloud.

===1st mail to customer===

This is usually done during some calls, if not use this template. The second part, what we need, is always needed:

<pre>
Dear Customer,

The proof of concept installation can be make with different setups, depending on the goal
you have.

please identify the goals:
* test Open-Xchange in general
* test with existing environment
* test a clustered setup

please identify what you want to test:
* webmail/groupware/infostore
* Outlook oxtender
* Business mobility (EAS)
* mobile gui
* webdav access (for the infostore)
* Mac OS X access
* everything

The smallest needed setup would be:
VM/real hardware with 2GB of memory, 20GB of local storage, an installed supported OS (Debian6, RHEL5/6, CentOS5, SLES11). If you want to test the system with https (which is recommended) we need a valid certificate for the server installed.

We need:

- server address/name
- ssh root access to the server from <our external ip's>, ssh keys attached
- http access to the server from <our external ip's> on port 80 and/or 443 (if https is used)
- access to a working smtp and imap server if you want to send and receive mails.
- imap account of the testuser with password if applicable.

</pre>

===POC license key===
Order the license key from our sales department.

===Installation===

After getting back the needed information the system can be installed. Update the system first if necessary.

Adding the needed repositories (ox, updates!, oxtenders, mobile etc. if needed).

The Open-Xchange installation itself should be done as described in the [[Main_Page_HESE#quickinstall|installtion guide]].

The simplest thing is to use imap authentication.

2do:
push config
mobile config
webdav config
caldav/varddav

Custom plugins should be defined in a SOW.

====Branding====
A very small and quick branding would be the change of the [[Gui_Plugin_Development|window title]], this will help you too, and maybe a change of the logo. Extended branding should be defined in a SOW.

====Testing====

All installed plugins have to be tested.

2do: a list of tests

===2nd mail to customer===
<pre>
Dear customer,

the setup of the server is ready.

url:<pocurl>
user:<testuser/password>

You can create new accounts as user root on the comandline on the server. Keep in mind that you first have to create the needed imap accounts as well.

2do: <insert an example cmdline createuser with prefilled data>

You can find more information about the groupware handling if you click on the question mark in the upper right corner and select help.

<use the sections if applicable>
If you want to test Outlook, please look at the [http://software.open-xchange.com/OX6/doc/Outlook-OXtender/OX6-OXtender2-for-Microsoft-Outlook-English.pdf documentation]

2do: more documentation sections for other plugins.

</pre>

ChangePasswordExternal

2015-03-03T07:14:45Z

Malasa: changed path to stable/backend

== 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/backend}}

== Enable the password change dialog within the AppSuite Frontend ==

After the installation of the package, you must explicitly enable the password change dialog for each AppSuite user. The simplest option to do this, is executing the following command:

/opt/open-xchange/sbin/changeuser -c <_context_id_> -u <_user_name_> --access-edit-password on

You can also use all other AppSuite provisioning interfaces like JAVA RMI or SOAP. Please review the corresponding documentation for each interface for details.

Screenshot of the password change dialog within AppSuite -> Settings -> Basic Settings -> Password

[[File:Passwordchange_installation_dialog_view_appsuite.png]]

== Configuration Options ==

As you see in the screenshot, there are different password options like the min. length etc. Those options can be configured within the following properties file. After you have modified this file, you must restart the open-xchange process.

/opt/open-xchange/etc/passwordchange.properties

To configure the actual script, which gets executed after the user uses the AppSuite password change dialog, you have to edit the following properties file:

/opt/open-xchange/etc/change_pwd_script.properties

And for example add the path to an existing script:

com.openexchange.passwordchange.script.shellscript=/bin/pwchange.pl

INFO: If you implement a custom script, you have to implement pre-defined exit codes for your script, which then get translated to user friendly error messages. The list of pre-defined exit codes are documented within the above mentioned properies file.

IMPORTANT: AppSuite does not ship with any readymade password change scripts. For examples, please see below.

=== 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:OX Guard

2014-12-16T15:10:14Z

Malasa: /* Debian GNU/Linux 7.0 */ password for update dir needed

= OX Guard =

OX Guard is a security solution that provides protection for email communications and files. Fully integrated with both OX as a Service and standard OX App Suite installations, it allows users to send and read encrypted messages and store and share encrypted files – and requires no additional setup or knowledge. OX Guard offers a simple way to increase security by limiting the opportunity for unauthorized access while data is en-route or in-storage, creating extra peace of mind.

This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:

* To setup a single server installation
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster
* To use the database service on the existing Open-Xchange installation for Guard, no replication
* To provide a basic configuration setup, no mailserver configuration

== Key features ==

* Simple security at the touch of a button
* Provides user based security - Separate from provider
* Supplementary security to Provider based security - Layered
* Powerful features yet simple to use and understand
* Security - Inside and outside of the OX environment
* Email and Drive integration
* Uses proven PGP security

== Availability ==

If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.

== Requirements ==

Please review following URL for remaining requirements

Please review [[AppSuite:OX_System_Requirements#OX_Guard|OX Guard Requirements]] for a full list of requirements.

Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment without having any of the other Open-Xchange App Suite core services installed. OX App Suite v7.6.0 or later is required to operate this extension both in a single or multi server environments.

Prerequisites:
* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.6.0 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [[AppSuite:UpdatingOXPackages|Updating OX-Packages]] explains how that can be done.

== Please Note ==

OX Guard version 1.0 supports branding / theming using the configuration cascade, defining a templateID for a user or context. Additional details will be provided in customization documentation

= Download and Installation =

=== General ===
The installation of the open-xchange-rest package which is required for Guard will eventually execute database update tasks if installed and activated. Please take this into account.

=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL6|appsuite/stable/guard-backend}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL6|appsuite/stable/guard-ui}}

and run

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static

=== Debian GNU/Linux 7.0 ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|appsuite/stable/guard-backend}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|appsuite/stable/guard-ui}}

and run

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|appsuite/stable/guard-backend}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|appsuite/stable/guard-ui}}

and run

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

$ update-alternatives --config java

Now select the Java 1.7 JRE, example:

There are 2 alternatives which provide `java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.

= Update OX Guard =

=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|appsuite/7.6.0/guard-backend/updates}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|appsuite/7.6.0/guard-ui/updates}}

and run

$ yum update
$ yum upgrade

After the new packages are installed, the guard process needs a restart:

<pre>$ /etc/init.d/open-xchange-guard restart</pre>

=== Debian GNU/Linux 7.0 ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|appsuite/stable/guard-backend/updates}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|appsuite/stable/guard-ui/updates}}
http://software.open-xchange.com/products/appsuite/stable/guard-backend/updates/DebianWheezy/
Then run

$ apt-get update
$ apt-get dist-upgrade

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s

After the new packages are installed, the guard process needs a restart:

<pre>$ /etc/init.d/open-xchange-guard restart</pre>

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLES11|appsuite/7.6.0/guard-backend/updates}}
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLES11|appsuite/7.6.0/guard-ui/updates}}

and run

$ zypper dup -r appsuite-7.6.0-guard-backend-updates
$ zypper dup -r appsuite-7.6.0-guard-ui-updates

You might need to run

$ zypper ref

to update the repository metadata before running ''zypper up''.

After the new packages are installed, the guard process needs a restart:

<pre>$ open-xchange-guard restart</pre>

= Configuration =

The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file guard.properties located in /opt/open-xchange/guard/etc. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options.

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

Open-Xchange config_db host - Guard will establish a connection to the config_db

com.openexchange.guard.configdbHostname=localhost

Guard database for storing user keys

com.openexchange.guard.oxguardDatabaseHostname=localhost

Username and Password for the two databases above

com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password

Open-Xchange REST API host

com.openexchange.guard.restApiHostname=localhost

Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below)

com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword

External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients

com.openexchange.guard.externalEmailURL=URL_TO_OX

== Configure services ==

=== Apache ===

Configure the mod_proxy_http module by adding the Guard API.

'''Redhat Enterprise Linux 6 or CentOS 6'''
$ vim /etc/httpd/conf.d/proxy_http.conf

'''Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11'''
$ vim /etc/apache2/conf.d/proxy_http.conf

<Proxy balancer://oxguard>
Order deny,allow
Allow from all<br>
BalancerMember http://localhost:8080/oxguard timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy><br>

ProxyPass /appsuite/api/oxguard balancer://oxguard

'''Please Note:''' The Guard API settings must be inserted before the existing “<Proxy /appsuite/api>” parameter.

After the configuration is done, restart the Apache webserver

$ apachectl restart

=== Open-Xchange ===

Please remove comments in front of the following settings to the configuration file guard.properties on the Open-Xchange backend servers:

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

# OX GUard general permission, required to activate Guard in the AppSuite UI.
com.openexchange.capability.guard=true

# Default theme template id for all users that have no custom template id configured.
com.openexchange.guard.templateID=0

Configure the API username and password that you assigned to Guard in the server.properties file

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

# Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.login=apiusername

# Specify the password used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.password=apipassword

Restart the OX backend

$ /etc/init.d/open-xchange restart

=== SELinux ===

Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8080, which is where the Guard backend service listens to. In order to allow localhost connections to 8080 execute the following:

$ setsebool -P httpd_can_network_connect 1

== Initiating the Guard database and key store ==

Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the Guard databases. The administration script also takes care of the creation of the master keys and the master password file in /opt/open-xchange/guard. The initiation only needs to be done once for a multi server setup, for details please see “Optional / Clustering”.

/opt/open-xchange/guard/sbin/guard init

'''Please Note:''' It is important to understand that the master password file located at /opt/open-xchange/guard/oxguardpass is required to reset user passwords, without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table.

== Start Guard ==

The services have been configured and the database has been initiated, it's time to start Guard

$ /etc/init.d/open-xchange-guard start

== Enabling Guard for Users ==

Guard provides two capabilities for users in the environment:

* '''Guard Mail:''' com.openexchange.capability.guard-mail
* '''Guard Drive:''' com.openexchange.capability.guard-drive

Each of those two Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:

'''Guard Mail:'''
$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true

'''Guard Drive:'''
$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true

'''Please Note:''' Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the guard.properties file on the OX bakend

== Optional ==

=== SSL Configuration ===

Per default the connection between the Guard backend and the configured Open-Xchange REST API host is unencrypted. Even though that Guard will never transmit unencrypted emails to or from the REST API you can optionally encrypt the whole communication between those two components by using SSL. To enforce Guard to use SSL in the communication between those two components enable the follwing configuration in Guard configuration file.

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

com.openexchange.guard.backend_ssl=true

The Guard backend is most commonly placed behind a load balancer (APACHE or other) and defaults to HTTP for incoming and outgoing traffic, using the load balancer to do SSL with the users. If you want Guard to use SSL for all communications, you need to set up the SSL key to use.

Please note that you have to provide access to the certificates.

com.openexchange.guard.useSSL: true
com.openexchange.guard.SSLPort: 8443
com.openexchange.guard.SSLKeyStore: //keystore location//
com.openexchange.guard.SSLKeyName: //alias name here//
com.openexchange.guard.SSLKeyPass: //ssl password//

'''Please Note:''' Enabling SSL might decrease performance and/or create more system load due to additional encoding of the HTTP streams.

For details on SSL installation and configuration, please see [[AppSuite:GuardSSL|OX Guard SSL Installation]]

== Recipient key detection ==

=== Local ===

Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.

To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the com.openexchange.mailmapping.MailResolver class or by interfacing Guard with your mail resolver system.
Please see [[Appsuite:GuardMailResolver|OX Guard Mail Resolver]] for details

=== External ===

OX Guard can also detect if the external recipient's account is also supported by its own Guard system in case the feature is publically announced via DNS.

The required DNS entry to allow external senders to get the public key has to look like:

_oxguard.example.com TXT "https://ox.hoster.com/appsuite/api/oxguard"

Such an entry needs to exist for all mail domains (not only the OX host domain obviously).

== Clustering ==

You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.

=== MySQL ===

The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL my.cnf:

bind = 0.0.0.0

This allows the Guard backend to bind to the MySQL host which is configured in the guard.properties file with com.openexchange.guard.configdbHostname. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the mysql client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:

GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;

=== Apache ===

OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via mod_proxy we need to add a servlet called "preliminary" to proxy_http.conf, example based on a clustered mod_proxy configuration:

<Location /preliminary>
Order Deny,Allow
Deny from all
# Only allow access from Guard servers within the network. Do not expose this
# location outside of your network. In case you use a load balancing service in front
# of your Apache infrastructure you should make sure that access to /preliminary will
# be blocked from the internet / outside clients. Examples:
# Allow from 192.168.0.1
# Allow from 192.168.1.1 192.168.1.2
# Allow from 192.168.0.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location>

Make sure that the balancer is properly configured in the mod_proxy configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose /preliminary to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to /preliminary from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard BalancerMembers to the oxguard balancer configuration (also in proxy_http.conf) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.

If the Apache server is a dedicated server / instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):

$ apt-get install open-xchange-guard-ui-static

=== Open-Xchange ===

Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:

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

and set:

com.openexchange.IPCheck=false

The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):

$ apt-get install open-xchange-guard-ui

Restart the Open-Xchange service afterwards.

=== OX Guard ===

After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in /opt/open-xchange/guard/etc/guard.properties:

com.openexchange.guard.restApiHostname=apache.example.com

Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the serblet /preliminary on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into /opt/open-xchange/guard/etc/guard.properties:

com.openexchange.guard.oxBackendPort=80

Please also change all settings in regards to MySQL like com.openexchange.guard.configdbHostname, com.openexchange.guard.oxguardDatabaseHostname, com.openexchange.guard.databaseUsername or com.openexchange.guard.databasePassword. Afterwards restart the OX Guard service and check the logfile if the OX Guard backend is able to connect to the configured REST API.

AppSuite:ExternalLoginPage

2014-09-25T06:50:45Z

Malasa: /* HTML */ typo formlogin, not fromlogin

= How to set up an external login page for App Suite =

== Who should read this document ==

This document is written for web developers who would like to create a custom login mask for the OX App Suite. The login mask can reside on an external server i. e., not directly located in the domain of the Open-Xchange machines. It is also intended for administrators who install and maintain Open-Xchange services.

== HTML ==

The Open-Xchange [[HTTP_API#Form_Login_.28since_6.20.29|HTTP API]] has a function to
create a session from external.

The full detailed explanation how the HTML form is used and errors can be handled can be found here:

[[OXSessionFormLogin|OX Session Formlogin]]

== Redirect to custom login ==

Users can still access the original product login site. If this is not wanted the following Apache
configuration for your VirtualHost can be used to redirect all requests to your custom login page:

RewriteEngine On
RewriteRule ^/appsuite/signin /custom-login.html [R]

== Setting custom login as logout location ==

If users should be directed to the custom login form after logout from App Suite the following property can be set globally somewhere in /opt/open-xchange/etc/settings/. Either create a new properties file or add the option in any existing one. For more complex setups e.g. with different brands please check out how to set this property in context or user scope which is explained [[ConfigCascade|here]].

io.ox/core//customLocations/logout=https://login.example.com

For cases where only one custom login page exists for all users it's also recommended to set

logoutLocation: 'https://login.example.com/'

in '''/opt/open-xchange/etc/as-config.yml'''. This setting takes effect for example if an autologin session is expired. as-config.yml itself defines settings in dependence of the hostname configured for the Open-Xchange access.

OX Outlook Uploader

2014-08-14T02:54:00Z

Malasa: license link broken

=Open-Xchange Microsoft Outlook® Uploader=

Open-Xchange provides Open-Xchange Microsoft Outlook® Uploader (short: ''OXUploader''), a migration tool to export data from Microsoft Outlook® or from a Microsoft Exchange Server® to the Open-Xchange Server.

=Features=
* Migration of E-Mails, appointments, contacts, distribution lists, tasks and sticky notes
* Folder structure is preserved, subfolders are created as necessary
* Attachments of E-Mails and other objects are migrated
* Support for recurring appointments and participants
* Migration of .pst-files
* Migration of data files from installed mail profiles
* Migration of Microsoft Exchange mailboxes
* Migration of Microsoft Exchange Public Stores
* Easy to use 3-step interactive wizard to configure the migration
* Unattended mode to perform migrations without user interaction
* Commandline interface to automate batch migrations

=Prerequisites=
The OXUploader migration tool is installed on a windows system having access to the data that should be migrated. The data is then migrated from there to the Open-Xchange server. Please ensure that the following requirements are met before installing the tool:

==Windows System==
You will finde the client requirements under [[AppSuite:OX_System_Requirements#MS_Windows_.2F_MS_Outlook.C2.AE_.2F_OX_Notifier_.2F_OX_Updater|Connector for Microsoft Outlook Requirements]]

==Open-Xchange Server==
* Latest Version of the Open-Xchange Server
* The user account(s) for which the data should be migrated should already have been created

=Download and installation=

To download the Open-Xchange Microsoft Outlook® Uploader installation packages and Release Notes, follow this [http://software.open-xchange.com/components/outlookuploader/6.20.5/ link]

After the download of the package, you can start the installation by double-clicking on the package. Please follow the installation steps in the wizard. The installation does not require administrative rights.

=Usage (interactive mode)=

{|
| [[image:OXUploader_Wizard_1.png|thumb]] ||
==1. Choose the migration source==
* First, either choose to migrate a personal storage file (.pst file), a data store from the local mail profiles, or an Exchange server mailbox.
* Depending on your choice, you can specify the migration source in the next step.
|-
| [[image:OXUploader_Wizard_2a.png|thumb]] ||
==2a. Select a personal storage file to migrate==
* When clicking on Browse the standard folder for saving .pst files opens.
* As some .pst files are password protected the password can be entered in the second field.
* When having chosen a file, click on Next.
|-
| [[image:OXUploader_Wizard_2b.png|thumb]] ||
==2b. Select a data file from a profile to migrate==
* Select one of the existing profiles from the drop-down menu.
* Select a store from the profile.
* Finally, enter a password if needed.
* To proceed, click Next.
|-
| [[image:OXUploader_Wizard_2c.png|thumb]] ||
==2c. Select an Exchange Server mailbox to migrate==
* Enter the URL of the Microsoft Exchange server.
* Select the username of the the account on the Exchange server.
* Click on "Logon..." to connect to the Exchange server and fetch the available mailboxes.
* When being asked, enter your password to logon to the Exchange server
* Select one of the existing mailboxes from the drop-down menu.
* To proceed, click Next.
|-
| [[image:OXUploader_Wizard_3.png|thumb]] ||
==3. Please enter information about the server==
* In the Server URL field, enter the Open-Xchange Server address.
* Enter your username in the second field.
* Enter your password in the third field.
* In order to make further settings, activate the "Configure advanced settings" checkbox.
* To proceed, click on Next.
|-
| [[image:OXUploader_Wizard_4a.png|thumb]] ||
==4a. Configure advanced options==
* If the folders should be migrated into a subfolder, enter it's name in the first field.
* In case not all mail folders are to be exported, the folders can be selected by clicking on the "Select..." button.
* Select the type of items to be migrated by marking the apporpiate checkboxes, and optionally define a minimum date for the items.
|-
| [[image:OXUploader_Wizard_4b.png|thumb]] ||
==4b. Configure advanced options==
* If no notification mails for appointments and tasks should be generated activate the respective checkbox.
* If mails with non resolved recipients should be skipped activate the respective checkbox.
* In order to ignore the "Trash", "Junk" or "Sync Issues" folders for the migration, activate the respective checkbox.
* If empty folders should be skipped, activate the respective checkbox.
* If the target folders should be emptied before items are migrated into them, activate the respective checkbox.
|-
| [[image:OXUploader_Wizard_5.png|thumb]] ||

==5. Migration in process==
* This window displays the status and a log protocol of the migration.
* When the process is finished, click on Next.
|-
| [[image:OXUploader_Wizard_6.png|thumb]] ||
==6. Migration completed==
* This window displays an overview of the migration and you can view the log file by clickin on the respective button.
* To close the wizard, click on Finish.
|}

=Usage (unattended mode)=

The migration tool can be started in a special "batch mode", where no user interaction is necessary. The options for the migration can be set in the configuration files, or passed via the commandline when starting the tool, see (3). When the parameter "batchmode" is "true", the migration starts automatically. In this case, at least the following settings have to be available, either supplied via the commandline or defined in the configuration file:
* Username
* ServerURL
* (PSTFile ''or'' ProfileName) and (StoreName ''or'' ExchangeServerURL)
* Password ''or'' AdminUser and AdminPassword

For example, to migrate the .pst-file "c:\test.pst", a command could look
like:
<pre>OXUploaderC.exe -batchmode true -pstfile "c:\test.pst" -serverurl "http://ox.example.invalid" -username test -password secret</pre>

Multiple instances of the tool can be run simultaneously from one or multiple client machines, more information can be found in (6).

=Configuration=

==Configuration files==

The application's configuration settings can be adjusted in config files, both for the OXUploader.exe main application for interactive mode and for the commandline version of the tool OXUploaderC.exe (see below). The files are named as the corresponding executable, with the file extension ".config": OXUploader.exe.config and OXUploaderC.exe.config respectively. A description of each parameter can be found in [[#Configuration parameters|Configuration parameters]]

==Commandline parameters==

Furthermore, the application can be started with commandline parameters. All supplied options overwrite the default settings from the configuration file, which are assumed if an option is missing. The following parameters are recognized:
<pre>-adminuser <Admin username on the OX server (for admin migration)>
-adminpassword <Admin password on the OX server (for admin migration)>
-appointmentsmindate <Minimum date of appointments to be migrated>
-batchmode <true/false>
-clearfolders <true/false>
-emailssmindate <Minimum date of e-mails to be migrated>
-exchangemailboxname <Name of the Exchange mailbox to migrate>
-exchangeserverurl <URL of the Exchange server>
-exchangeserverusername <Username on the Exchange server>
-exportappointmentparticipants <true/false>
-exportappointmentuids <true/false>
-ignorejunkfolder <true/false>
-ignoresyncissuesfolder <true/false>
-ignoretrashfolder <true/false>
-importfoldername <Name of the migration target subfolder>
-logautoflush <true/false>
-logconsole <true/false>
-loglevel <off/error/warning/info/verbose>
-logonexchangemailbox <true/false>
-logpostdata <true/false>
-logtextfile <Path to logfile>
-migrateappointments <true/false>
-migratecontacts <true/false>
-migrateemails <true/false>
-migratenotes <true/false>
-migratetasks <true/false>
-password <Password on the OX server>
-profilename <Name of the profile>
-pstfile <Path to PST file>
-pstpassword <Password for the PST file>
-serverurl <URL of the OX server>
-skipemptyfolders <true/false>
-storename <Name of the store inside the profile>
-tasksmindate <Minimum date of tasks to be migrated>
-uploadchunksize <Number of uploaded mails per request>
-uploadthresholdbytes <Threshold of bytes for sending forced>
-username <Username on the OX server>
-recoverableexceptionmaxretries <max. retries after recoverable error>
-suppressnotificationmails <true/false>
-skipmailswithnonresolvedrecipients <true/false>
</pre>

=Misc=

The following chapters contain some advanced information and configration options for the OXUploader migration tool.

==Performance considerations==

The time needed to perform a migration correspondends with the size of the .pst file, of course. So, for large mailboxes, this could be a quite time intensive task, and may be improved in knowledge of the following observations, especially when performing multiple simultaneous batch migrations.
The I/O-ratio is about the following: Per each byte read from disk, about 0.65 bytes are written to disk, and 0.12 bytes are sent to the server. This is caused by the fact that the messages read out from the .pst-file are exported to RFC822 .eml files first, then those files are loaded again before finally sending them to the server. Therefore, the throughput of the local file system should be as fast as possible. Since the temporary created RFC822 e-mail files are created in the user's temp folder, it would be best to move the location to a separate location as the .pst-file - another hdd, maybe even a ramdisk for the temp directory would make sense for heavy batch migrations. It's also recommended to temporarily disable virus protection and indexing services during the migration, and Outlook 2007 should be preferred against Outlook 2003.

==Limitations when running multiple instances==

When executing multiple migrations simulataneously from one machine, each instance of the tool must have exclusive access to the .pst-file it is migrating. Furthermore, each instance must use a different logfile. The tool relies on Outlook, and so it also can't work around Outlooks own limitations, especially as Outlook is designed as client application. More details can be found at the knowledge base article here: http://support.microsoft.com/kb/257757/en-us .

==Admin migration==

When the server is configured appropiate, the migration tool can also be used to import .pst-files into the OX account of the specified user, without the need to supply the user's password. Therefore, the username and password of a special admin user is needed for authentication against the OX server.
For example, to migrate the .pst-file "c:\test.pst" into the account "test", a command could look like:
<pre>OXUploaderC.exe -batchmode true -pstfile "c:\test.pst" -serverurl "http://ox.example.invalid" -username test -adminuser admin -adminpassword secret</pre>

==Personal storage files==

Sometimes .pst-files are broken our corrupted, and the migration tool may not be able to open them correctly, or opening them takes a very long time when the internal repair operations take place.
To reduce the impact of broken .pst-files, it's recommended to check the integrity of the files using Microsofts SCANPST.exe tool, see http://support.microsoft.com/kb/287497 . Sadly this utility is designed to run interactively, but there are some utilities out there that automate the SCANPST.exe tool to be run from the commandline, pointing to the .pst-file to scan, for example cmdscan.exe from http://www.olfolders.de/Lang/English/OLfix/download.htm . Doing so, one would be able to incorporate a SCANPST.exe launch prior a batch call to the migration tool, e.g. the following command could be invoked to scan and repair the .pst file "c:\test.pst", passing the path to the SCANPST.exe location:
<pre>cmdscan.exe -rename "c:\Program Files (x86)\Microsoft Office\Office12\SCANPST.EXE" "c:\test.pst"</pre>

==Duplicated items==

Migrating the same items into the same target folder multiple times usually results in the items getting duplicated on the server.
An exception to this rule are appointments with unique identifiers (UIDs), see http://www.ietf.org/rfc/rfc2445.txt, chapter 4.8.4.7, for details. To avoid importing an appointment with the same identifier multiple times, the server rejects an appointment when the UID already exists on the server. To force the migration of appointments regardless of their UIDs, the tool optionally removes the UIDs from the appointment. The relevant setting is named "ExportAppointmentUIDs", when set to "False", existing UIDs are removed before sending them to the server.
Furthermore, the migration tool has an option to clear the folder contents before triggering the export. When "ClearFolders" is set to "True", the target folder is emptied prior to the items being exported. Note that any existing data in these folders will be permanently lost.

==Exchange mailboxes==

Instead of using a local mail profile or a .pst file for migration, it's also possible to logon to and migrate an Exchange mailbox directly. It's recommeded that the migration tool is executed inside the exchange domain by the owner of the mailbox.
To perform an administrative migration for other user's mailboxes, the following preconditions must be met:
* Ensure the target account already has been created on the OX server
* Grant the administrating user "Receive As" permissions to the mailbox store of all accounts that should be migrated, details can be found at http://support.microsoft.com/default.aspx?scid=kb;EN-US;821897 and http://msexchangeteam.com/archive/2006/01/25/418099.aspx
* The migration tool is ececuted by the administrative user, who already should be logged on to the exchange domain
The administrative migration can only be executed from the commandline in "batch mode", see (5) for details. The mailbox or the name of the user that is going to be migrated needs to be specified inside the commandline parameter "exchangemailboxname". For example, to migrate the mailbox of exchange user "test" to the Open-Xchange account with username "test", combined with admin migration at the OX server (see (6c) for details), one could execute the migration tool in the following way:
<pre>OXUploaderC.exe -batchmode true -exchangeserverurl 192.168.0.4 -exchangemailboxname test -serverurl "http://ox.example.invalid" -username test -adminuser admin -adminpassword secret</pre>
Or, if the password of the OX user is available:
<pre>OXUploaderC.exe -batchmode true -exchangeserverurl 192.168.0.4 -exchangemailboxname test -serverurl "http://ox.example.invalid" -username test -password secret</pre>

==Administrative installation==

The OXUploader migration tool itself can be installed without the need for elevated access rights by the end user, as the installer only accesses the local non-roaming application data directory and the HKCU hive in the registry. It can't be installed 'per machine', which means that it is not allowed to set the value of the ALLUSERS msi property to "1".
The tool can be pre-configured for the end-users by setting public properties at the commandline for the installation process. These are processed by the installer and then written into the tool's config-file. The following parameters can be adjusted (the values in square brackets that are listed below indicate the default values of the properties when not overridden by the msi commandline - so that would be the default pre-configuration):
<pre>ADMINUSER []
ADMINPASSWORD []
BATCHMODE [False]
CLEARFOLDERS [False]
EXPORTAPPOINTMENTPARTICIPANTS [True]
EXPORTAPPOINTMENTUIDS [True]
IGNOREJUNKFOLDER [True]
IGNORETRASHFOLDER [True]
IMPORTFOLDERNAME []
LOGAUTOFLUSH [True]
LOGCONSOLE [False]
LOGLEVEL [Info]
LOGTEXTFILE [.\pst2ox.log]
MIGRATEAPPOINTMENTS [True]
MIGRATECONTACTS [True]
MIGRATEEMAILS [True]
MIGRATENOTES [True]
MIGRATETASK [True]
PASSWORD []
PROFILENAME []
PSTFILE []
PSTPASSWORD []
SERVERURL [http://]
SKIPEMPTYFOLDERS [True]
STORENAME []
UPLOADCHUNKSIZE [25]
UPLOADTHRESHOLDBYTES [2097152]
OXUSERNAME []
RECOVERABLEEXCEPTIONMAXRETRIES [3]
SUPPRESSNOTIFICATIONMAILS [True]
SKIPMAILSWITHNONRESOLVEDRECIPIENTS [False]
</pre>

For example, to predefine a Server URL that should be used for the
migration afterwards, one would execute e.g.:
<pre> "Open-Xchange Outlook Uploader.msi" SERVERURL="http://ox.example.invalid"</pre>

==Address Resolution==

While the Open-Xchange server uses SMTP as the only recipient address type, data from Microsoft Exchange might contain several additional address types. To migrate such Exchange data to the Open-Xchange server, each e-mail recipient or particpiant of an appointment or task needs a valid SMTP address. While the migration tool tries to retrieve the SMTP address of message recipients in different ways, sometimes there might be recipients that can't be resolved without a connection to the Microsoft Exchange server / Active Directory and it's global address lists. Especially, this may happen with .pst-files that were created using Microsofts EXMERGE tool.
In order to resolve that issue, the OXUploader migration tool can establish a connection to the exchange server and to it's global address list prior migrating a .pst-file to the Open-Xchange server, so that the recipient's SMTP addresses can be resolved. To do so, there are two parameters that can be set to logon to the exchange server prior migrating the .pst-file: [[#ExchangeServerURL|ExchangeServerURL]] and [[#ExchangeServerUsername|ExchangeServerUsername]]. The username parameter is optional (if not defined, the identity of the current windows user is used) and normally should not need to be set in batch-mode to prevent a windows logon prompt.
For example, to logon to the exchange server at "192.168.0.4" and perform an admin migration for the username "test" in unattended mode, a command could look like:
<pre>OXUploaderC.exe -batchmode true -exchangeserverurl 192.168.0.4 -serverurl "http://ox.example.invalid" -username test -adminuser admin -adminpassword secret -pstfile ".\test.pst" -logtextfile ".\test.log"</pre>

==Public Folders==

When migrating an Exchange Public Folders store, the folders are migrated below the root Public Folders folder on the Open-Xchange server. To do so, the user performing the migration must have appropiate permissions to create public folders on the server. Since access rights of the folders are not migrated, custom permissions on the folders should be applied manually afterwards.

=Configuration parameters=
This chapter describes all possible configuration parameters that can be found in the OXUploader.exe.config / OXUploaderC.exe.config configuration files or can be passed to the migration tool from the commandline.

; <span id="AdminPassword">AdminPassword</span>: The password associated with the administrator user ([[#AdminUser|AdminUser]]) on the Open-Xchange server. Only used when performing [[#Admin_migration|admin migration]].
; <span id="AdminUser">AdminUser</span>: The username of the administrator user on the Open-Xchange server. Only used when performing [[#Admin_migration|admin migration]].
; <span id="AppointmentsMinDate">AppointmentsMinDate</span>: If defined, only appointments that end after this date are migrated. Recurring appointments are migrated, if the end date of the series has not been set, or if the end date of the series is not after this defined value. Date format should be ''yyy-MM-dd''.
; <span id="BatchMode">BatchMode</span>: Specifies whether the tool should be run in a special batchmode without user interaction or not, see [[#Usage_(unattended_mode)|unattended mode]] for details.
; <span id="ClearFolders">ClearFolders</span>: When set to 'True', the migration tool clears the target folder contents before exporting items to that folders. Existing subfolders are not affected by this setting, only the folder's contents. Also, the folder clear-command is only executed for folders that are actually migrated, not for ignored or skipped folders.
; <span id="EMailsMinDate">EMailsMinDate</span>: If defined, only e-mails that were sent or received after this date are migrated. Date format should be ''yyyy-MM-dd''.
; <span id="ExchangeMailboxName">ExchangeMailboxName</span>: Specifies the mailbox name on the Microsoft Exchange server that should be used for migration. Used in combination with the [[#ExchangeServerURL|ExchangeServerURL]] and [[#ExchangeServerUsername|ExchangeServerUsername]] parameters. If not defined, the default mailbox for the Exchange user is used. This parameter is also used to define a shared Exchange mailbox, see [[#Exchange mailboxes|Exchange mailboxes]] for details.
; <span id="ExchangeServerURL">ExchangeServerURL</span>: The URL of the Microsoft Exchange server that hosts the mailbox to be migrated. Only used, when [[#PSTFile|PSTFile]] and [[#ProfileName|ProfileName]] are not defined.
; <span id="ExchangeServerUsername">ExchangeServerUsername</span>: The username of the Exchange account to migrate. Used in combination with the [[#ExchangeServerURL|ExchangeServerURL]] and [[#ExchangeMailboxName|ExchangeMailboxName]] parameters. If not defined, the current windows identity is used.
; <span id="ExportAppointmentParticipants">ExportAppointmentParticipants</span>: Specifies whether the participants (recipients) of appointments should be migrated or not. If set to 'False', only the Open-Xchange user ([[#Username|Username]]) will participate the exported appointments, otherwise all original participants will be added to the migrated appointment, too.
; <span id="ExportAppointmentUIDs">ExportAppointmentUIDs</span>: Specifies whether the unique identifiers (UIDs) of appointments should be migrated or not. Details can be found in the chapter [[#Duplicated items|Duplicated items]].
; <span id="HistoryFile">HistoryFile</span>: The path to the file where the migration tool stores the migration results internally to keep track of which folders already have been migrated successfully.
; <span id="IgnoreJunkFolder">IgnoreJunkFolder</span>: Whether to ignore the ''Junk'' folder during the migration or not.
; <span id="IgnoreSyncIssuesFolder">IgnoreSyncIssuesFolder</span>: Whether to ignore the ''Sync Issues'' folder during the migration or not.
; <span id="IgnoreTrashFolder">IgnoreTrashFolder</span>: Whether to ignore the ''Trash'' folder during the migration or not.
; <span id="ImportFolderName">ImportFolderName</span>: Specifies the name of an additional subfolder below the OX default folders that is used as target for the migrated folders. If left blank, the OX default folders are used as target directly.
; <span id="LogAutoFlush">LogAutoFlush</span>: Specifies whether the log should be flushed to disk automatically after each entry.
; <span id="LogConsole">LogConsole</span>: Whether to output the log to the console or not.
; <span id="LogLevel">LogLevel</span>: Specifies the verbosity of the generated log, possible values are ''Error'', ''Warning'', ''Info'' and ''Verbose''.
; <span id="LogonExchangeMailbox">LogonExchangeMailbox</span>: It's possible to establish a connection to the an MS Exchange server and to it's global address list prior migrating .pst-files, so that the recipient's SMTP addresses can be resolved. When set to ''True'', the URL of the Exchange server has to be defined in [[#ExchangeServerURL|ExchangeServerURL]].
; <span id="LogPOSTData">LogPOSTData</span>: For debugging reasons, this option enables or disables logging of the complete POST data that is sent to the Open-Xchange server during migration.
; <span id="LogTextFile">LogTextFile</span>: Specifies the path to the logfile.
; <span id="MigrateAppointments">MigrateAppointments</span>: Whether to migrate appointments or not.
; <span id="MigrateContacts">MigrateContacts</span>: Whether to migrate contacts and distribution lists or not.
; <span id="MigrateEMails">MigrateEMails</span>: Whether to migrate e-mail or not.
; <span id="MigrateNotes">MigrateNotes</span>: Whether to migrate sticky notes or not.
; <span id="MigrateTasks">MigrateTasks</span>: Whether to migrate tasks or not.
; <span id="Password">Password</span>: The password for the target account ([[#UserName|UserName]]) on the Open-Xchange server.
; <span id="ProfileName">ProfileName</span>: The name of the local mail profile to be migrated. Used in combination with the [[#StoreName|StoreName]] parameter.
; <span id="PSTFile">PSTFile</span>: The path to the .pst-file to be migrated.
; <span id="PSTPassword">PSTPassword</span>: The password to access the .pst-file, only needed if the .pst has been protected with a password.
; <span id="RecoverableExceptionMaxRetries">RecoverableExceptionMaxRetries</span>: Specifies how often a request is repeated in case of possibly recoverable errors.
; <span id="ServerURL">ServerURL</span>: The URL of the Open-Xchange server.
; <span id="SkipEmptyFolders">SkipEmptyFolders</span>: Whether to include folders that don't contain any items or not. Subfolders in empty folders are not affected by this setting.
; <span id="StoreName">StoreName</span>: The name of the message store inside the local mail profile. Used in combination with the [[#ProfileName|ProfileName]] parameter.
; <span id="TasksMinDate">TasksMinDate</span>: If defined, only tasks with a due date after this date are migrated. Date format should be ''yyyy-MM-dd''.
; <span id="UploadChunkSize">UploadChunkSize</span>: Specifies the number of e-mail items that are sent to the Open-Xchange server during the migration per each request.
; <span id="UploadThresholdBytes">UploadThresholdBytes</span>: Specifies a value in bytes after which an e-mail message chunk is sent to the server, even if when the [[#UploadChunkSize|UploadChunkSize]] is not yet exceeded.
; <span id="Username">Username</span>: The user name of the target account on the Open-Xchange server.
; <span id="SuppressNotificationMails">SuppressNotificationMails</span>: Whether to suppress server generated notification mails for new appointments/tasks or not.
; <span id="SkipMailsWithNonResolvedRecipients">SkipMailsWithNonResolvedRecipients</span>: Whether the OXUploader skips migrating mails with at least one non resolved recipient or not.

=Functional limitations=
* Due to differences in handling recurring tasks between the Open-Xchange server and Microsoft Exchange, recurring tasks are not supported.
* Folder permissions are not transferred to the Open-Xchange server; each new subfolder that is created during the migration gets a set of default permissions (target user has admin permissions).

=Reporting of Bugs=
Please report bugs and missing features via [https://bugzilla.open-xchange.com/enter_bug.cgi?product=Open-Xchange%20MS%20Outlook%20Uploader Open-Xchange Bugzilla]. Many thanks in advance for your support.

Product: Open-Xchange MS Outlook Uploader

=Open-Xchange Microsoft Outlook® Uploader (Open Source via SVN)=

Portions of the Software may use, include third party software, other copyrighted material or Open Source Software. Acknowledgements, licensing terms and disclaimers for such material are contained in separate agreements. Licensee’s use of such material is governed by the terms of the applicable agreements and can be found on the OX web site, are listed under: [http://www.open-xchange.com/licenses-for-open-xchange-ms-outlook-uploader http://www.open-xchange.com/licenses-for-open-xchange-ms-outlook-uploader]

==Compile from sources==

=== Download and install Outlook Redemption ===

The Open-Xchange Microsoft Outlook Uploader requires the Outlook Redemption library® by Dmitry Streblechenko. As the distributable version of Redemption cannot be used in open source projects, it is not included in the repository. However, for development purposes only, you can download a copy of the library at [http://www.dimastr.com/redemption/ http://www.dimastr.com/redemption/] and install it on your development PC.

=== Checkout the sources from Subversion ===

The source code for the Open-Xchange Microsoft Outlook® Uploader is available in a public Subversion repository. To checkout the latest sources, use the following command:

svn --username anonymous checkout https://svn.open-xchange.com/migration/OXUploader

=== Build using Visual Studio® ===

The Open-Xchange Microsoft Outlook® Uploader can be compiled easily using Visual Studio 2008®. For both the interactive and the commandline version of the migration tool, there are C# project files (.csproj) in the PST2OX and the PST2OXc subdirectories (PST2OX is the 'codename' of the migration tool). Just open the project file in Visual Studio and build the project.

AppSuite:Writing a contacts plugin

2014-04-28T02:55:03Z

Malasa:

== Where and how to start ==
Plugins are collected in the folder ui/apps/plugins. Start your new plugin there: Create a folder and in this folder, create two files: <tt>register.js</tt> (where everything happens) and <tt>manifest.json</tt>

== What are you going to do ==
Your plugin code can interact with the app suite is by way of extension points and extensions. Stated briefly an extension point is an invitation to contributing an implementation to a part of the UI. For example the contact detail view consists of an extension point that receives contributions in the form of renderers, that render different parts of the contact. Say, one for rendering the display name, one for the mail addresses, one for the postal addresses and so on. All these, in turn then, make up the contacts detail view. It is easy for plugins to affect this set of extensions. A plugin can contribute its own extension to an extension point, thereby rendering a different part of a contact or contributing a new button to work on a contact. A plugin can also disable existing extensions, thereby removing parts of the UI.

== Hans-On ==
=== Register ===
As an example, let's add a new renderer to the contact detail view. Let's create a new file myplugin/apps/com.example/contacts/register.js:

<pre class="language-javacript">
define('com.example/contacts/register', ['io.ox/core/extensions'], function (ext) {
'use strict';

ext.point('io.ox/contacts/detail').extend({
id: 'com-example-contact-reversename',
after: 'contact-details',
draw: function (baton) {

var name = baton.data.display_name;
var rev = name.split("").reverse().join("");

this.append(
$("<h1>").text(rev)
));
}
});
});
</pre>

=== Manifest ===
Next we have to make sure our code is actually loaded by the UI at the right moment. The right moment in our case is right before it loads the file apps/io.ox/contacts/view-detail, where the extension point is processed. For this, we need another [[AppSuite:UI_manifests_explained | manifest]] file at myplugin/apps/com.example/contacts/manifest.json:

<pre class="language-javacript">
{
namespace: "io.ox/contacts/view-detail"
}
</pre>

After writing your code, always [[AppSuite:GettingStarted#Building | build]] your javascript code to make apply.
See the [[AppSuite:GettingStarted#Development_cycle | development cycle]] to keep easy steps in mind you need while developing.

=== Running a local backend? ===

If using a local backend, restart it to pick up on the changed manifest, or, for a remote backend, edit myplugin/src/manifests.js again so it reads:

<pre class="language-javacript">
define(function () {
return [
{
path: "com.example/main",
title: 'Hello World App'
},
{
path: "com.example/contacts/register",
namespace: "io.ox/contacts/view-detail"
}
];
});
</pre>

reload the UI and navigate to a contact. It should contain the new section with the display name in reverse.

== Extension Points ==
Trouble [[AppSuite:Extending_the_UI_(Hands-on_introduction)#Trouble_finding_the_right_extension_point.3F | finding the right extension point]]?
Learn more about Extension points regarding [[AppSuite:Extension_points | these articles]].
== Stuck somewhere? ==
You got stuck with a problem while developing? OXpedia might help you out with the article about [[AppSuite:Debugging_the_UI | debugging the UI]].

[[Category:AppSuite]]
[[Category:UI]]
[[Category:Developer]]

Template:OXLoadBalancingClustering Database

2014-02-08T09:25:23Z

Malasa: /* 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" flavor of the Galera database.

=== Installation ===

==== Debian systems ====

The following has been tested with Squeeze, but the Wheezy procedure should not be different, besides 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 squeeze main
deb-src http://repo.percona.com/apt squeeze 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. It is convenient to use the rpmforge repo. (''epel'' works not since its socat expects readline libraries version 5, while RHEL 6 (at leat 6.4) provides version 6.)

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 wget http://pkgs.repoforge.org/rpmforge-release/rpmforge-release-0.5.3-1.el6.rf.x86_64.rpm
yum localinstall rpmforge-release-0.5.3-1.el6.rf.x86_64.rpm

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 Percona-XtraDB-Cluster-client
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.

==== ''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
# 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 all nodes of a Galera cluster are not 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).

For testing purposes it is possible to use Keepalived to create a software loadbalancer on a therefore dedicated linux node. Documentation is available [[Keepalived|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:GettingStarted 7.4.2

2013-11-13T04:21:48Z

Malasa: /* Writing */ typo

<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 OX App Suite development. This document will get you started to develop your first own app for OX App Suite with a minimal setup. We will look at the steps necessary but will also tempt you to learn more by linking you to some more in-depth documentation about these topics. Depending on how you wound up reading this page, you will probably have already completed some of the steps below.

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

== Installing ==

First, you need to install some tools which are necessary for UI development. For now, the simplest way is to download the source of the OX App Suite UI. Since the source code is kept in a [http://git-scm.com/ Git] repository, you will need <tt>git</tt> to download it:

$ git clone --depth 1 -b release-7.4.1 https://code.open-xchange.com/git/wd/frontend/web

This downloads the latest version and unpacks it into a subdirectory <tt>web</tt> in the current directory.

The option <tt>--depth 1</tt> prevents the download of the entire history, and reduces the download size from hundreds of MB to less than 20MB. The option <tt>-b release-7.4.1</tt> specifies a git branch. The full functionality described in this article is only available in the branch <tt>release-7.4.1</tt> until 7.4.1 is released.

The tools which you will need are contained in the directory <tt>ui/bin</tt>. To simplify their use, you should add this directory to your <tt>$PATH</tt>:

$ export PATH="$PATH:$(pwd)/web/ui/bin"

== Create Workspace ==

Your entire work on an app can take place inside a 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 relative paths will be relative to this directory from now on.

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

$ mkdir -p apps/com.example

== Writing ==

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 ==

The source code of your app can't be used by OX App Suite as it. It has to be first 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:

$ build-appsuite app

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 ==

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, start <tt>appserver</tt> using [http://ox.io/ ox.io] as server:

<nowiki>$ appserver --server=https://www.ox.io/appsuite/ build</nowiki>

This command will serve your app from the local directory <tt>build</tt>, and get everything else from the URL specified by the <tt>--server</tt> parameter. To serve multiple apps, you can specify multiple local directories separated by spaces.

You should start <tt>appserver</tt> in a separate terminal, since it needs to run in the background. To stop <tt>appserver</tt>, press <tt>Ctrl+C</tt> in its terminal.

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

http://localhost:8337/appsuite

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

If you later add images or other files, which are not JavaScript, CSS or LessCSS, then you need to [[AppSuite:Appserver#Use_with_Apache | use a web server]] to serve them.

=== Development cycle ===

Once you are sure that your setup works, you can extend the example and write the actual code of your app. Keep in mind that after [[#Writing | writing your code]], you will always need to [[#Building | build the app]] and have your [[#Hosting the app | Appserver]] running in the background, but don't need to restart it after every build.

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

== Packaging ==

When your app is done, you probably want to test it on a staging system, and later install it on a production system. To keep track of which installed files belong to which version of which app, you should use the native package manager of the Linux distribution of the target system. The packages can be easily created using the build system.

=== Initialization ===
First, you need to create several files describing how to package you app. Use the <tt>init-packaging</tt> task of the build system:

$ build-appsuite init-packaging
Node version: v0.10.21
Build path: build
Build version: 0.0.1-1.20131025.133931
Package name: example-app
Version [0.0.1]:
Maintainer (Name <e-mail>): Maintainer <maintainer@example.com>
Copyright line [2013 Open-Xchange, Inc]:

Known licenses for which you don't need to specify a file:
APACHE-2, BSD-2-CLAUSE, BSD-3-CLAUSE, CC-BY-3, CC-BY-NC-3, CC-BY-NC-ND-3,
CC-BY-NC-SA-3, CC-BY-ND-3, CC-BY-SA-3, CC0-1, EXPAT, GPL-2, GPL-3, LGPL-3

License name [CC-BY-NC-SA-3.0]: BSD-3-Clause
Short description: Example app

The task presents a number of interactive prompts to get the necessary information about the generated packages. The default values are presented in square brackets ([...]) and can be selected by just pressing Enter. Otherwise, the entered values should follow the Debian Maintainer's Guide. Debian tools are especially picky about the syntax of the maintainer name and email address.

If none of the known licenses suit you, you can enter any other license name. Then you will be asked to enter the file name of your license text. It should be a plain text file using the UTF-8 encoding.

Some or even all prompts can be skipped by explicitly specifying the information as a build variable. The list of variable names is available in the reference of the <tt>[[AppSuite:UI_build_system#init-packaging|init-packaging]]</tt> task.

After answering all the questions, you can customize the generated files to account for any additional packaging requirements.

=== Static Files ===
If your app includes images (e.g. themes do this most of the time), then you should check the generated packaging files for sections marked

## Uncomment for multiple packages
#...

and remove the '#' at the start of each line in each block. This enables the creation of a second package, with a name ending in "<tt>-static</tt>". The images and any other files which are not JavaScript or CSS are served by the Apache web server, instead of the OX App Suite application server. These files are copied to a separate package for the case that the web server is on a dedicated system or maybe even has its own cluster. The default package is installed on the OX application server, and the second, "<tt>-static</tt>" package is installed on the web server.

=== Building Packages ===
Since the actual package format depends on the distribution it is built for, and there already exist tools to create packages from suitably arranged source code archives, the OX App Suite build system merely prepares such source archives. Using the <tt>dist</tt> task to create the archives:

$ build-appsuite dist
Node version: v0.10.21
Build path: build
Build version: 0.0.1-1.20131025.150034
dpkg-source: info: using source format `3.0 (quilt)'
dpkg-source: info: building example-app using existing ./example-app_0.0.1.orig.tar.bz2
dpkg-source: info: building example-app in example-app_0.0.1-1.debian.tar.bz2
dpkg-source: info: building example-app in example-app_0.0.1-1.dsc

$ ls tmp/packaging/
example-app-0.0.1 example-app_0.0.1-1.dsc
example-app.spec example-app_0.0.1.orig.tar.bz2
example-app_0.0.1-1.debian.tar.bz2

The task creates a temporary directory and four files. The archive with the extension <tt>.orig.tar.bz2</tt> contains the source of your app. It is required to build both Debian and RPM packages. The files with extensions <tt>.debian.tar.bz2</tt> and <tt>.dsc</tt> are used together with the <tt>.orig.tar.bz2</tt> archive to build Debian packages. The file with the extension <tt>.spec</tt> is used together with the <tt>.orig.tar.bz2</tt> archive to build RPM packages.

==== Building Debian Packages ====
The Debian package can be built directly in the temporary directory created by the <tt>dist</tt> task:

$ cd tmp/packaging/example-app-0.0.1/
$ dpkg-buildpackage -b

The package will be placed in <tt>tmp/packaging/</tt>.

==== Building RPM Packages ====
The RPM package build tool <tt>rpmbuild</tt> requires the files to be in a specific directory layout before building:

$ mkdir -p ~/rpmbuild/{SOURCES,SPECS,BUILD,RPMS}
$ cp tmp/packaging/*.orig.tar.bz2 ~/rpmbuild/SOURCES/
$ cp tmp/packaging/*.spec ~/rpmbuild/SPECS/
$ rpmbuild --define "_topdir $HOME/rpmbuild" -bb ~/rpmbuild/SPECS/*.spec

The package will be placed in <tt>~/rpmbuild/RPMS/noarch/</tt>.

The parameter <tt>--define "_topdir $HOME/rpmbuild"</tt> can also be specified in the file <tt>~/.rpmmacros</tt> or, on some distributions, is even unnecessary.

== Further Reading ==
* You just build your first app for OX App Suite, keep in mind that there [[AppSuite:Developing for the UI#What_can_i_build.3F | quite a few options]] how you can develop for OX App Suite.
* It's highly recommended to gain more knowledge about all the benefits [[AppSuite:UI_build_system | the UI build system]] and [[AppSuite:Appserver|the Appserver]] are providing you for developing OX App Suite.
* If you're stuck somewhere, the article about [[AppSuite:Debugging_the_UI | debugging the UI]] might help you.
* Get a better overview about [[AppSuite:Developing for the UI | developing the user inferface]].

Caldav carddav Bundles

2013-07-30T02:49:01Z

Malasa: /* Alternative 2: Apache useragent detection */

= Installation and Configuration of the CalDAV- and CardDAV-bundles =

The Open-Xchange server can be accessed via it's CalDAV- and CardDAV-interfaces to allow the synchronization of Calendar- and Contact-data with external applications like the Mac OS X iCal and Address Book clients. The synchronization protocols are available starting with Version 6.20.1 Rev5.

CalDAV and CardDAV are standard protocols for the exchange of calendar data and address data respectively. The CalDAV interface publishes all the user's calendar folders via CalDAV so the user can subscribe to them in a client application. Similarly, the CardDAV interface publishes the user's contact folders. Depending on the used client, the user can either subscribe one or more folders, or access all available data in an aggregated way.

== User Guide and Client Configuration ==
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].

== Webserver Configuration ==
In order to redirect DAV requests to the appropiate servlets, the webserver's configuration may need to be adjusted using one of the following alternatives.

=== Alternative 1: Apache vhost (recommended) ===
Please edit your file /etc/apache2/ox6.conf so that ''' the existing OX configuration as well as the CalDAV/CardDav configuration are placed inside their own virtual hosts sections.'''.

This is an <b>example</b> where MYSERVER.TLD is the domain-name of the ox-server:

$ vi /etc/apache2/ox6.conf

NameVirtualHost *:80
<VirtualHost *:80>
ServerName dav.MYSERVER.TLD
ErrorLog /tmp/dav.err.log
TransferLog /tmp/dav.access.log
<Proxy />
Order allow,deny
Allow from all
</Proxy>
# for ajp http service
ProxyPass / ajp://localhost:8009/servlet/dav/ smax=0 ttl=60 retry=5
# for grizzly http service
#ProxyPass / http://localhost:8009/servlet/dav/ smax=0 ttl=60 retry=5
</VirtualHost>

<VirtualHost *:80>
ServerName MYSERVER.TLD
ServerAdmin webmaster@localhost
DocumentRoot /var/www/

<Directory /var/www/>
AllowOverride None
Order allow,deny
allow from all
RedirectMatch ^/$ /ox6/
Options +FollowSymLinks +SymLinksIfOwnerMatch
</Directory>
# deflate
AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css text/xml application/xml text/x-js application/x-javascript

# pre-compressed files
AddType text/javascript .jsz
AddType text/css .cssz
AddType text/xml .xmlz
AddType text/plain .po

AddEncoding gzip .jsz .cssz .xmlz
SetEnvIf Request_URI "\.(jsz|cssz|xmlz)$" no-gzip

ExpiresActive On

<Location /ox6>
# Expires (via ExpiresByType to override global settings)
ExpiresByType image/gif "access plus 6 months"
ExpiresByType image/png "access plus 6 months"
ExpiresByType image/jpg "access plus 6 months"
ExpiresByType image/jpeg "access plus 6 months"
ExpiresByType text/css "access plus 6 months"
ExpiresByType text/html "access plus 6 months"
ExpiresByType text/xml "access plus 6 months"
ExpiresByType text/javascript "access plus 6 months"
ExpiresByType text/x-js "access plus 6 months"
ExpiresByType application/x-javascript "access plus 6 months"
ExpiresDefault "access plus 6 months"
Header append Cache-Control "private"
Header unset Last-Modified
Header unset Vary
# Strip version
RewriteEngine On
RewriteRule v=\w+/(.+) $1 [L]
# Turn off ETag
Header unset ETag
FileETag None
</Location>

<Location /ox6/ox.html>
ExpiresByType text/html "now"
ExpiresDefault "now"
Header unset Last-Modified
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
# Turn off ETag
Header unset ETag
FileETag None
</Location>

<Location /ox6/index.html>
ExpiresByType text/html "now"
ExpiresDefault "now"
Header unset Last-Modified
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
# Turn off ETag
Header unset ETag
FileETag None
</Location>
</VirtualHost>

If you use this method, you have to make sure that dav.MYSERVER.TLD is reachable, your dns configuration need an entry for this name. Take care of the the dav.* logfiles, the example writes them without logrotation to /tmp.

=== Alternative 2: Apache useragent detection ===
For environments where it is inconvenient to setup a vhost there is the possibility to redirect to relevant servlets another way: Via useragent detection. This is not recommended for the following reason: Per definition this is a whitelist-approach and any client sending a useragent-string not explicitly listed in the configuration will not be able to connect . Useragent-strings may also change between different versions of an application or may even be actively changed into something non-standard.

$ vi /etc/apache2/ox6.conf

RewriteEngine On
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]
RewriteCond %{HTTP_USER_AGENT} Address%20Book [OR]
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]
RewriteCond %{HTTP_USER_AGENT} CoreDAV
# select if you run ajp (proxy_ajp.conf) or grizzly (proxy_http.conf), here ajp is used:
RewriteRule (.*) ajp://localhost:8009/servlet/dav$1 [P] # for ajp http service
#RewriteRule (.*) http://localhost:8009/servlet/dav$1 [P] # for grizzly http service

'''Note:''' The address book app on OSX 10.6 uses a localized user-agent string. If you're expecting clients with non-english language settings, you need to add the translated user-agent string to these rewrite rules. For example: "Adressbuch" for german OSX clients.

== Autodiscovery ==

By providing some DNS service name registrations for your domain and adding an additional rewrite-rule to the webserver's configuration, it's possible for some clients to automatically discover the account settings by just providing the user's e-mail address and password. The procedure is specified in [http://tools.ietf.org/html/rfc6764 RFC 6764].

The following example illustrates the DNS entries where MYSERVER.TLD would be the domain name of the ox-server, both for CalDAV and CardDAV via HTTP and HTTPS on the virtual host dav.MYSERVER.TLD:

_caldavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.
_caldav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.
_carddavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.
_carddav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.

Additionally, a rewrite-rule similar to the following example should be added to the webserver configuration of the virtual host to enable the bootstrapping process:

RewriteEngine On
RewriteCond %{REQUEST_URI} ^/\.well-known/caldav [OR]
RewriteCond %{REQUEST_URI} ^/\.well-known/carddav
RewriteRule (.*) / [L,R]

== Which packages do I need? ==
To get CalDAV and CardDAV up and running you need the following packages:

In v6.20 and earlier:
* open-xchange-webdav-directory - Assembles the *DAV interfaces into a common tree. This is needed for publishing certain properties so clients accept the OX is a WebDAV Server.
* open-xchange-webdav-acl - The WebDAV equivalent of the /ajax/user interface. Allows clients to discover the current and other users and their addressbooks and calendars.
* open-xchange-carddav - The CardDAV interface exposing the users addressbook via carddav
* open-xchange-caldav - The CalDAV inteface exposing the users calendars via caldav

With v6.22 we have significantly reduced the number of packages necessary to install Open-Xchange Server.
In v6.22 and later only one package is needed:
* open-xchange-dav

== Installation on OX App Suite ==
The download and installation information for Open-Xchange App Suite product family (Open-Xchange Server Edition and Hosting Edition) is available at: http://oxpedia.org/wiki/index.php?title=AppSuite:Caldav_carddav_Bundles

{{InstallPlugin|pluginname=open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory |sopath=updates}}

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

== CalDAV Configuration ==

The following configuration options are available in the configuration files caldav.properties and caldav.yml:

===com.openexchange.caldav.enabled===
The property '''com.openexchange.caldav.enabled''' governs whether a user has access to the CalDAV interface. This can be configured along the config cascade, in the default setting, everyone that has access to the infostore also has access to caldav. This is achieved in the following way:

In v6.20 and earlier:

/opt/open-xchange/etc/groupware/caldav.properties:
com.openexchange.caldav.enabled=false

/opt/open-xchange/etc/groupware/contextSets/caldav.yml
premium:
com.openexchange.caldav.enabled: true
withTags: ucInfostore

With v6.22 and up:

/opt/open-xchange/etc/caldav.properties:
com.openexchange.caldav.enabled=false

/opt/open-xchange/etc/contextSets/caldav.yml
premium:
com.openexchange.caldav.enabled: true
withTags: ucInfostore

This means: In general CalDAV is turned off, but using the contextSets feature of the config cascade it is turned on for everyone that has infostore access.

===com.openexchange.caldav.tree===
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.

===com.openexchange.caldav.interval.start===
Defines the minimum end time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_month" (default), "one_year" and "six_months".

===com.openexchange.caldav.interval.end===
Defines the maximum start time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_year" (default) and "two_years".

===com.openexchange.caldav.url===
Tells users where to find a caldav folder. This can be displayed in frontends. You can use the variables [hostname] and [folderId]. If you chose to deploy caldav as a virtual host (say 'dav.open-xchange.com') use https://dav.open-xchange.com/caldav/[folderId] as the value. If you are using user-agent sniffing use https://[hostname]/caldav/[folderId].

== CardDAV Configuration ==

The following configuration options are available in the configuration files carddav.properties and carddav.yml:

===com.openexchange.carddav.enabled===
Similarly to CalDAV, the property '''com.openexchange.carddav.enabled''' governs whether CardDAV is available for a certain user. This is configured exactly like CalDAV with the config cascade only enabling this for users that have access to the infostore:

/opt/open-xchange/etc/groupware/carddav.properties:
com.openexchange.carddav.enabled=false

/opt/open-xchange/etc/groupware/contextSets/carddav.yml
premium:
com.openexchange.carddav.enabled: true
withTags: ucInfostore

===com.openexchange.carddav.ignoreFolders===
A comma-separated list of folder IDs to exclude from the synchronization. Use this to disable syncing of very large folders (e.g. the global address list in large contexts, which always has ID 6). By default, no folders are excluded.

===com.openexchange.carddav.tree===
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.

===com.openexchange.carddav.exposedCollections===
Controls which collections are exposed via the CardDAV interface. Possible values are '0', '1' and '2'. A value of '1' makes each visible folder available as a resource collection, while '2' only exposes an aggregated collection containing all contact resources from all visible folders. The default value '0' exposes either an aggregated collection or individual collections for each folder, depending on the client's user-agent that is matched against the pattern in 'userAgentForAggregatedCollection'.

===com.openexchange.carddav.userAgentForAggregatedCollection===
Regular expression to match against the client's user-agent to decide whether the aggregated collection is exposed or not. The default pattern matches all known varieties of the Mac OS Addressbook client, that doesn't support multiple collections. Only used if 'exposedCollections' is set to '0'. The pattern is used case insensitive.

===com.openexchange.carddav.reducedAggregatedCollection===
Specifies if all visible folders are used to create the aggregated collection, or if a reduced set of folders only containing the global addressbook and the personal contacts folders should be used. This setting only influences the aggregated collection that is used for clients that don't support multiple collections. Possible values are 'true' and 'false.

AppSuite:Connector for Business Mobility Installation Guide

2013-06-28T09:01:06Z

Malasa: appsuite, no groupware dir ...

= 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 on OX 6.x ==
The download and installation information for Open-Xchange 6 product family (Open-Xchange Server Edition and Hosting Edition) is available at: http://oxpedia.org/wiki/index.php?title=OXtender_for_Business_Mobility_Installation_Guide

{{InstallPlugin|pluginname=open-xchange-meta-mobility|toplevel=products|sopath=appsuite/stable/mobilityconnector|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility|version=App Suite}}

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.

== 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. When using Apache 2 and mod_proxy_ajp, this servlet can simply be added to the webservers proxy_ajp configuration:
ProxyPass /Microsoft-Server-ActiveSync ajp://127.0.0.1:8009/Microsoft-Server-ActiveSync smax=0 ttl=60 retry=5

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/groupware/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 =
* [[OXtender_for_Business_Mobility_WinPhone7 | Windows Phone 7]]
* [[OXtender_for_Business_Mobility_WinMob | Windows Mobile]]
* [[OXtender_for_Business_Mobility_iPhone | iPhone]]
* [[OXtender_for_Business_Mobility_BlackBerry | BlackBerry]]
* [[OXtender_for_Business_Mobility_Nokia | Nokia S60]]
* [[OXtender_for_Business_Mobility_Android | Android ]]

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

AppSuite:Parallel UISupport OX6 AppSuite RHEL 6 CentOS 6

2013-05-23T08:40:02Z

Malasa: /* Configure services */ changed logfile path

= Add OX6 UI to an OX App Suite Installation =
This document outlines the steps required to add an OX6 UI to an OX App Suite installation.

= Supported OX Versions =
Running parallel UIs (OX6 and OX App Suite) is supported beginning with OX6 version 6.22.2 (backend version 7.0.2) and OX App Suite version 7.0.1.

= Requirements =
* An OX App Suite installation v7.0.2 or later. This update guide is valid for a system installed through our [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6|OX App Suite Download and Installation Guide for RedHat Enterprise Linux 6]]. It applies also to installations on 100% compatible RHEL clones such as CentOS.
* If you have custom plugins written by yourself which depends on an specific Open-Xchange Server, Open-Xchange can't guarantee that the plugins will work with the parallel setup.
* As for every modification of the installation we strongly recommend that you make a backup of your system(s) before you proceed.

= Add Open-Xchange Repository =
We start by adding some OX6 frontend repos to our yum repos. Note: the <code>.../RHEL6</code> repo also is valid for CentOS 6.

# /etc/yum.repos.d/ox.repo
[ox-frontend]
name=Open-Xchange-frontend
baseurl=http://software.open-xchange.com/OX6/6.22/frontend/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

= Updating repositories and install packages =

Install the OX6 frontend packages.

$ yum install open-xchange-gui

This will install the OX6 fronted packages. (OX App Suite frontend package names start with <code>open-xchange-appsuite</code>.)

= Configure services =

Since we are only adding a frontend, there is nothing to change in the configuration of the backend servers, the database, mail, or such. It is only required to adjust the apache web server configuration in the file <code>/etc/httpd/conf.d/ox.conf</code>.

Basically we need to merge the [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6#Configure_services|OX App Suite]] and [[Open-Xchange_Installation_Guide_for_RHEL6_622#Configure_services|OX6]] versions of this file. A sample is given in the following.

# /etc/httpd/conf.d/ox.conf
<VirtualHost *:80>
ServerAdmin webmaster@localhost

DocumentRoot /var/www/html

<Directory /var/www/html>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Order allow,deny
allow from all
RedirectMatch ^/$ /appsuite/
</Directory>

<Directory /var/www/html/appsuite>
Options None +SymLinksIfOwnerMatch
AllowOverride Indexes FileInfo
</Directory>

ErrorLog /var/log/httpd/error.log

# Possible values include: debug, info, notice, warn, error, crit,
# alert, emerg.
LogLevel warn

CustomLog /var/log/httpd/access.log combined

# deflate
AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css text/xml application/xml text/x-js application/x-javascript

# pre-compressed files
AddType text/javascript .jsz
AddType text/css .cssz
AddType text/xml .xmlz
AddType text/plain .po

AddEncoding gzip .jsz .cssz .xmlz
SetEnvIf Request_URI "\.(jsz|cssz|xmlz)$" no-gzip

ExpiresActive On

<Location /ox6>
# Expires (via ExpiresByType to override global settings)
ExpiresByType image/gif "access plus 6 months"
ExpiresByType image/png "access plus 6 months"
ExpiresByType image/jpg "access plus 6 months"
ExpiresByType image/jpeg "access plus 6 months"
ExpiresByType text/css "access plus 6 months"
ExpiresByType text/html "access plus 6 months"
ExpiresByType text/xml "access plus 6 months"
ExpiresByType text/javascript "access plus 6 months"
ExpiresByType text/x-js "access plus 6 months"
ExpiresByType application/x-javascript "access plus 6 months"
ExpiresDefault "access plus 6 months"
Header append Cache-Control "private"
Header unset Last-Modified
Header unset Vary
# Strip version
RewriteEngine On
RewriteRule v=\w+/(.+) $1 [L]
# Turn off ETag
Header unset ETag
FileETag None
</Location>

<Location /ox6/ox.html>
ExpiresByType text/html "now"
ExpiresDefault "now"
Header unset Last-Modified
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
# Turn off ETag
Header unset ETag
FileETag None
</Location>

<Location /ox6/index.html>
ExpiresByType text/html "now"
ExpiresDefault "now"
Header unset Last-Modified
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
# Turn off ETag
Header unset ETag
FileETag None
</Location>
</VirtualHost>

Restart the web server:

$ /etc/init.d/httpd restart

That's it. It should now be able to access the OX6 frontend using the location <code>/ox6/</code> in the request.

AppSuite:Grizzly

2013-04-17T14:44:56Z

Malasa: /* Apache configuration */

=Grizzly based backend=
Up to OX App Suite we were limited to AJP based communication between the HTTP server and the OX backend server. Starting with the release 7.0.1 of OX App Suite, we offer a second HTTP based connector for the communication between the HTTP server and the backend. This new connector is based on Oracle's '''[http://grizzly.java.net Project Grizzly]''' - a [http://en.wikipedia.org/wiki/New_I/O NIO] and Web framework.

=Packages=
Next, we'll show some information on the packages needed to install a Grizzly based backend, give you some in depth information about the package dependencies of '''open-xchange''' on '''open-xchange-ajp''' and '''open-xchange-grizzly''' and cover possible conflicts between those packages.

==HttpService as packaging dependency==
[[File:HttpServiceDependency.png|thumb|left|alt=The HttpService dependency.]]
The open-xchange package depends on a virtual package called '''open-xchange-httpservice'''. This service is provided by both, the old '''open-xchange-ajp''' and the new '''open-xchange-grizzly''' packages. Only one of these two packages can be installed at a time because they block each other.

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

{{InstallPlugin|pluginname=open-xchange-grizzly| toplevel=products | sopath=appsuite/stable/backend|version=App Suite}}

=Cluster setup=
[[File:GrizzlOXClusterSetup.png|left|alt=The default cluster setup.]]
This picture shows our default cluster setup. It consists of a proxying balancer (in our case Apache) and a cluster of multiple OX App Suite backends. The balancer receives HTTP and/or HTTPS requests. It then decides which requests should be handled by itself and which should be forwarded, so they can be handled by one of the OX App Suite backends. That's where the AJP or HTTP connector is used.
<div style="clear: both"></div>

==Configuration==
As requests pass the balancer first, we'll start with a look at how to configure the balancer before configuring the Grizzly-based OX App Suite backends.

===Apache configuration===
{{Template:ApacheOXModsDebian|connector=http}}

If you used AJP before, you have to delete /etc/apache2/conf.d/proxy_ajp.conf.

{{Template:ApacheAppSuiteConf/sandbox|connector=http|connectorConf=/etc/apache2/conf.d/proxy_http.conf|apacheconf=/etc/apache2/sites-enabled/000-default|docroot=/var/www/|loadmodule=|easProxyName=eas_oxcluster}}

====X-FORWARDED-PROTO Header====

[[Appsuite:Grizzly#Cluster_setup]] shows that HTTPS communication is terminated by the Apache balancer in front of the OX backends. To let the backends know about the protocol that is used to communicate with the Apache server we have to set a special header in the ssl virtual hosts configurations in Apache to forward this information. The de facto standard for this is the X-Forwarded-Proto header.

To add it to your Apache configuration you have to open the default ssl vhost configuration via:

$ vim /etc/apache2/sites-enabled/default-ssl

and add

RequestHeader set X-Forwarded-Proto "https"

to each of the virtual hosts used to communicate with the OX App Suite backends.

===Grizzly configuration===

====Available configuration files====

====/opt/open-xchange/etc/server.conf====
This extract of the server.properties shows the properties that can be applied to the grizzly and ajp backend.
<pre>
...
# DEFAULT ENCODING FOR INCOMING HTTP REQUESTS
# This value MUST be equal to web server's default encoding
DefaultEncoding=UTF-8
...
# The host for the connector's (ajp, http) network listener. Set to "*" if you
# want to listen on all available interfaces.
#Default value: 127.0.0.1, bind to localhost only.
com.openexchange.connector.networkListenerHost=*

# The default port for the connector's (ajp, http) network listener.
# Default value: 8009.
com.openexchange.connector.networkListenerPort=8009

# Specify the max. number of allowed request parameters for the connector (ajp, http)
# Default value: 30
com.openexchange.connector.maxRequestParameters: 30

# To enable proper load balancing and request routing from {client1, client2 ..
# .} --> balancer --> {backend1, backend2 ...} we have to append a backend route
# to the JSESSIONID cookies separated by a '.'. It's important that this backend
# route is unique for every single backend behind the load balancer.
# The string has to be a sequence of characters excluding semi-colon, comma and
# white space so the JSESSIONID cookie stays in accordance with the cookie
# specification after we append the backendroute to it.
# Default value: OX0
com.openexchange.server.backendRoute=OX1

# Decides if we should consider X-Forward-Headers that reach the backend.
# Those can be spoofed by clients so we have to make sure to consider the headers only if the proxy/proxies reliably override those
# headers for incoming requests.
# Default value: false
com.openexchange.server.considerXForwards = false

# The name of the protocolHeader used to identify the originating IP address of
# a client connecting to a web server through an HTTP proxy or load balancer.
# This is needed for grizzly based setups that make use of http proxying.
# If the header isn't found the first proxy in front of grizzly will be used
# as originating IP/remote address.
# Default value: X-Forwarded-For
com.openexchange.server.forHeader=X-Forwarded-For

# A list of know proxies in front of our httpserver/balancer as comma separated IPs e.g: 192.168.1.50, 192.168.1.51
com.openexchange.server.knownProxies =
...
</pre>

====/opt/open-xchange/etc/grizzly.conf====
Next we'll look at the parts of the grizzly.properties that configure only the grizzly backend but not the ajp backend.
<pre>
# Grizzly.properties
#
# This file configures the grizzly server contained in the package
# open-xchange-grizzly. In your OX setup grizzly is located behind the
# load-balancer and accepts incoming client requests. Communication with the
# load balancer is done via http, e.g via Apache's mod_proxy_http.

### Push technology
################################################################################

# Comet is an umbrella term used to describe a technique allowing web browser to
# receive almost real time updates from the server. The two most common
# approaches are long polling and streaming. Long polling differs from streaming
# in that each update from the server ultimately results in another follow up
# request from the client.
# Default value: true
com.openexchange.http.grizzly.hasCometEnabled=true

# Bi-directional, full-duplex communications channels over a single TCP
# connection.
# Default value: false
com.openexchange.http.grizzly.hasWebSocketsEnabled=true

### JMX
################################################################################

# Do you want to enable grizzly monitoring via JMX? Default value: true.
com.openexchange.http.grizzly.hasJMXEnabled=true

### Protocol
################################################################################

# Grizzly is able to communicate via AJP besides its default prototcol HTTP.
# Do you want to use AJP instead of HTTP?
# Default value: false
com.openexchange.http.grizzly.hasAJPEnabled=false
</pre>

====/opt/open-xchange/etc/requestwatcher.conf====
And finally the properties to configure the requestwatchers of the http and ajp backends
<pre>
# Requestwatcher.properties
#
# This file configures the requestwatchers contained in the packages
# open-xchange-grizzly and open-xchange-ajp. The requestwatcher keeps track of
# incoming requests and periodically checks the age of the currently processing
# requests. If a request exceeds the configured maximum age, infos about the
# request and its processing thread are logged either into the configured
# logfiles or syslog depending on your configuration.

# Enable/disable the requestwatcher.
# Default value: true (enabled).
com.openexchange.requestwatcher.isEnabled: true

# Define the requestwatcher's frequency in milliseconds.
# Default value: 30000.
com.openexchange.requestwatcher.frequency: 30000

# Define the maximum allowed age of requests in milliseconds.
# Default value: 60000.
com.openexchange.requestwatcher.maxRequestAge: 60000

# Permission to stop & re-init system (works only for the ajp connector)
com.openexchange.requestwatcher.restartPermission: false
</pre>

==Multiple Proxies in front of the cluster==
[[File:GrizzlOXClusterMultipleProxySetup.png|left|935px|alt=The default cluster with multiple proxies setup.]]
<div style="clear: both"></div>

===X-FORWARDED-FOR Header===

Wikipedia[http://en.wikipedia.org/wiki/X-Forwarded-For] describes the X-Forwarded-For Header as:

The '''X-Forwarded-For''' ('''XFF''') HTTP header field is a ''de facto'' standard for identifying the originating IP address of a client connecting to a web server through an HTTP proxy or load balancer. This is an HTTP request header which was introduced by the [[Squid (software)|Squid]] caching proxy server's developers. An effort has been started at IETF for standardizing the '''Forwarded''' HTTP header.

In this context, the caching servers are most often those of large ISPs who either encourage or force their users to use proxy servers for access to the World Wide Web, something which is often done to reduce external bandwidth through caching. In some cases, these proxy servers are transparent proxies, and the user may be unaware that they are using them.

Without the use of XFF or another similar technique, any connection through the proxy would reveal only the originating IP address of the proxy server, effectively turning the proxy server into an anonymizing service, thus making the detection and prevention of abusive accesses significantly harder than if the originating IP address was available. The usefulness of XFF depends on the proxy server truthfully reporting the original host's IP address; for this reason, effective use of XFF requires knowledge of which proxies are trustworthy, for instance by looking them up in a whitelist of servers whose maintainers can be trusted.

====Format====
The general format of the field is:

: <tt>X-Forwarded-For: client, proxy1, proxy2</tt>

where the value is a comma+space separated list of IP addresses, the left-most being the original client, and each successive proxy that passed the request adding the IP address where it received the request from. In this example, the request passed through proxy1, proxy2, and then proxy3 (not shown in the header). proxy3 appears as remote address of the request.

The given information should be used with care since it is easy to forge an X-Forwarded-For field. The last IP address is always the IP address that connects to the last proxy, which means it is the most reliable source of information. X-Forwarded-For data can be used in a forward or reverse proxy scenario.

Just logging the X-Forwarded-For field is not always enough: The last proxy IP address in a chain is not contained within the X-Forwarded-For field, it is in the actual IP header. A web server should log BOTH the request's source IP address and the X-Forwarded-For field information for completeness.

===Getting the remote IP===
If you want the backends in the GrizzlOX-Cluster to use '''Client''''s(95.223.182.44) instead of '''Balancer''''s IP as remote address for e.g reporting the LogProperty '''com.openexchange.grizzly.remoteAddress''' for faulty requests in the Open-Xchange logs, you have to change these parameters from their default values seen in /opt/open-xchange/etc/server.properties to:

# Decides if we should consider X-Forward-Headers that reach the backend.
# Those can be spoofed by clients so we have to make sure to consider the headers only if the proxy/proxies reliably override those
# headers for incoming requests.
# Default value: false
com.openexchange.server.considerXForwards = '''true'''

# The name of the protocolHeader used to identify the originating IP address of
# a client connecting to a web server through an HTTP proxy or load balancer.
# This is needed for grizzly based setups that make use of http proxying.
# If the header isn't found the first proxy in front of grizzly will be used
# as originating IP/remote address.
# Default value: X-Forwarded-For
com.openexchange.server.forHeader='''X-Forwarded-For'''

# A list of know proxies in front of our httpserver/balancer as comma separated IPs e.g: 192.168.1.50, 192.168.1.51
com.openexchange.server.knownProxies = '''192.168.1.50, 192.168.1.51'''

After you have changed the the configuration you have to restart the backend server via

$ /etc/init.d/open-xchange restart

The remote IP is detected in the following way: All configured known proxies are removed from the list of IPs listed in the X-FORWARDED-FOR header, beginning frome the right side of the list. The rightmost leftover IP is then seen as our new remote address as it represents the first IP not known to us.

==Make Grizzly speak AJP instead of HTTP==
Grizzly normally acts as an HTTP server and demands that the balancing proxy in front of it communicates via HTTP. This behaviour can be changed to Grizzly accepting the Apache JServ Protocol by simply adjusting the Grizzly and Apache configurations and restarting both servers.

===Grizzly.properties===

Change this parameter from the value seen in [[#Grizzly configuration|Grizzly configuration]] to:

### Protocol
################################################################################

# Grizzly is able to communicate via AJP besides its default prototcol HTTP.
# Do you want to use AJP instead of HTTP?
# Default value: false
com.openexchange.http.grizzly.hasAJPEnabled='''true'''

===Apache configuration===

Change the HTTP related parameters from the values seen in [[#Apache configuration|Apache configuration]] to AJP. This involves the IfModule directive and the BalancerMember declarations.

To make Apach communicate via AJP instead of HTTP you have to replace the proxy_http with the proxy_ajp module.

<IfModule mod_proxy_'''ajp'''.c>
ProxyRequests Off
# When enabled, this option will pass the Host: line from the incoming request to the proxied host.
ProxyPreserveHost On
<Proxy balancer://oxcluster>
Order deny,allow
Allow from all
# multiple server setups need to have the hostname inserted instead localhost
BalancerMember '''ajp'''://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
# Enable and maybe add additional hosts running OX here
# BalancerMember '''ajp'''://oxhost2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
</Proxy>
# Microsoft recommends a minimum timeout value of 15 minutes for eas connections
<Proxy balancer://eas_oxcluster>
Order deny,allow
Allow from all
# multiple server setups need to have the hostname inserted instead localhost
BalancerMember '''ajp'''://localhost:8009 timeout=1800 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
# Enable and maybe add additional hosts running OX here
# BalancerMember '''ajp'''://oxhost2:8009 timeout=1800 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
</Proxy>

$ a2dismod proxy_http && a2enmod proxy_ajp

===Restart the servers===

$ /etc/init.d/open-xchange restart
$ /etc/init.d/apache2 restart

=Switching from open-xchange-grizzly to open-xchange-ajp=
It's possible to switch the '''open-xchange-grizzly''' based setup to a setup based on the alternative '''open-xchange-ajp''' if you don't depend on certian realtime features like websockets, comet based communication or the already mentioned WEBDAV MKCALENDAR command.

==1. Install the ajp backend==
Install the '''open-xchange-ajp''' package via your package manager. This will inform you about a conflict between the currently installed '''open-xchange-grizzly''' and the package you want to install. To solve the conflict you either have to manually remove '''open-xchange-grizzly''' before installing '''open-xchange-ajp''' or let the package manager handle this conflict automatically for you.

;Debian:
$ aptitude install open-xchange-ajp
;Suse:
$ zypper in open-xchange-ajp
;RedHat:
$ yum install open-xchange-ajp

==2. Adapt the module configuration of apache==
Adapt the installed apache modules to switch the proxy connector in use from http to ajp

$ a2dismod proxy_http && a2enmod proxy_ajp

==3. Adapt the apache configuration to use the new connector==
To make use of apaches new ajp connector for communication with '''open-xchange-ajp''' whe have to change it's configuration

{{Template:ApacheAppSuiteConf/sandbox|connector=ajp|connectorConf=/etc/apache2/conf.d/proxy_ajp.conf|apacheconf=/etc/apache2/sites-enabled/000-default|docroot=/var/www/|loadmodule=}}

==4.Restart services==
$ /etc/init.d/apache2 restart
$ /etc/init.d/open-xchange restart

[[Category: AppSuite]]

AppSuite:Grizzly

2013-04-17T14:44:09Z

Malasa: /* Apache configuration */

=Grizzly based backend=
Up to OX App Suite we were limited to AJP based communication between the HTTP server and the OX backend server. Starting with the release 7.0.1 of OX App Suite, we offer a second HTTP based connector for the communication between the HTTP server and the backend. This new connector is based on Oracle's '''[http://grizzly.java.net Project Grizzly]''' - a [http://en.wikipedia.org/wiki/New_I/O NIO] and Web framework.

=Packages=
Next, we'll show some information on the packages needed to install a Grizzly based backend, give you some in depth information about the package dependencies of '''open-xchange''' on '''open-xchange-ajp''' and '''open-xchange-grizzly''' and cover possible conflicts between those packages.

==HttpService as packaging dependency==
[[File:HttpServiceDependency.png|thumb|left|alt=The HttpService dependency.]]
The open-xchange package depends on a virtual package called '''open-xchange-httpservice'''. This service is provided by both, the old '''open-xchange-ajp''' and the new '''open-xchange-grizzly''' packages. Only one of these two packages can be installed at a time because they block each other.

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

{{InstallPlugin|pluginname=open-xchange-grizzly| toplevel=products | sopath=appsuite/stable/backend|version=App Suite}}

=Cluster setup=
[[File:GrizzlOXClusterSetup.png|left|alt=The default cluster setup.]]
This picture shows our default cluster setup. It consists of a proxying balancer (in our case Apache) and a cluster of multiple OX App Suite backends. The balancer receives HTTP and/or HTTPS requests. It then decides which requests should be handled by itself and which should be forwarded, so they can be handled by one of the OX App Suite backends. That's where the AJP or HTTP connector is used.
<div style="clear: both"></div>

==Configuration==
As requests pass the balancer first, we'll start with a look at how to configure the balancer before configuring the Grizzly-based OX App Suite backends.

===Apache configuration===
{{Template:ApacheOXModsDebian|connector=http}}

{{Template:ApacheAppSuiteConf/sandbox|connector=http|connectorConf=/etc/apache2/conf.d/proxy_http.conf|apacheconf=/etc/apache2/sites-enabled/000-default|docroot=/var/www/|loadmodule=|easProxyName=eas_oxcluster}}

====X-FORWARDED-PROTO Header====

[[Appsuite:Grizzly#Cluster_setup]] shows that HTTPS communication is terminated by the Apache balancer in front of the OX backends. To let the backends know about the protocol that is used to communicate with the Apache server we have to set a special header in the ssl virtual hosts configurations in Apache to forward this information. The de facto standard for this is the X-Forwarded-Proto header.

To add it to your Apache configuration you have to open the default ssl vhost configuration via:

$ vim /etc/apache2/sites-enabled/default-ssl

and add

RequestHeader set X-Forwarded-Proto "https"

to each of the virtual hosts used to communicate with the OX App Suite backends.

===Grizzly configuration===

====Available configuration files====

====/opt/open-xchange/etc/server.conf====
This extract of the server.properties shows the properties that can be applied to the grizzly and ajp backend.
<pre>
...
# DEFAULT ENCODING FOR INCOMING HTTP REQUESTS
# This value MUST be equal to web server's default encoding
DefaultEncoding=UTF-8
...
# The host for the connector's (ajp, http) network listener. Set to "*" if you
# want to listen on all available interfaces.
#Default value: 127.0.0.1, bind to localhost only.
com.openexchange.connector.networkListenerHost=*

# The default port for the connector's (ajp, http) network listener.
# Default value: 8009.
com.openexchange.connector.networkListenerPort=8009

# Specify the max. number of allowed request parameters for the connector (ajp, http)
# Default value: 30
com.openexchange.connector.maxRequestParameters: 30

# To enable proper load balancing and request routing from {client1, client2 ..
# .} --> balancer --> {backend1, backend2 ...} we have to append a backend route
# to the JSESSIONID cookies separated by a '.'. It's important that this backend
# route is unique for every single backend behind the load balancer.
# The string has to be a sequence of characters excluding semi-colon, comma and
# white space so the JSESSIONID cookie stays in accordance with the cookie
# specification after we append the backendroute to it.
# Default value: OX0
com.openexchange.server.backendRoute=OX1

# Decides if we should consider X-Forward-Headers that reach the backend.
# Those can be spoofed by clients so we have to make sure to consider the headers only if the proxy/proxies reliably override those
# headers for incoming requests.
# Default value: false
com.openexchange.server.considerXForwards = false

# The name of the protocolHeader used to identify the originating IP address of
# a client connecting to a web server through an HTTP proxy or load balancer.
# This is needed for grizzly based setups that make use of http proxying.
# If the header isn't found the first proxy in front of grizzly will be used
# as originating IP/remote address.
# Default value: X-Forwarded-For
com.openexchange.server.forHeader=X-Forwarded-For

# A list of know proxies in front of our httpserver/balancer as comma separated IPs e.g: 192.168.1.50, 192.168.1.51
com.openexchange.server.knownProxies =
...
</pre>

====/opt/open-xchange/etc/grizzly.conf====
Next we'll look at the parts of the grizzly.properties that configure only the grizzly backend but not the ajp backend.
<pre>
# Grizzly.properties
#
# This file configures the grizzly server contained in the package
# open-xchange-grizzly. In your OX setup grizzly is located behind the
# load-balancer and accepts incoming client requests. Communication with the
# load balancer is done via http, e.g via Apache's mod_proxy_http.

### Push technology
################################################################################

# Comet is an umbrella term used to describe a technique allowing web browser to
# receive almost real time updates from the server. The two most common
# approaches are long polling and streaming. Long polling differs from streaming
# in that each update from the server ultimately results in another follow up
# request from the client.
# Default value: true
com.openexchange.http.grizzly.hasCometEnabled=true

# Bi-directional, full-duplex communications channels over a single TCP
# connection.
# Default value: false
com.openexchange.http.grizzly.hasWebSocketsEnabled=true

### JMX
################################################################################

# Do you want to enable grizzly monitoring via JMX? Default value: true.
com.openexchange.http.grizzly.hasJMXEnabled=true

### Protocol
################################################################################

# Grizzly is able to communicate via AJP besides its default prototcol HTTP.
# Do you want to use AJP instead of HTTP?
# Default value: false
com.openexchange.http.grizzly.hasAJPEnabled=false
</pre>

====/opt/open-xchange/etc/requestwatcher.conf====
And finally the properties to configure the requestwatchers of the http and ajp backends
<pre>
# Requestwatcher.properties
#
# This file configures the requestwatchers contained in the packages
# open-xchange-grizzly and open-xchange-ajp. The requestwatcher keeps track of
# incoming requests and periodically checks the age of the currently processing
# requests. If a request exceeds the configured maximum age, infos about the
# request and its processing thread are logged either into the configured
# logfiles or syslog depending on your configuration.

# Enable/disable the requestwatcher.
# Default value: true (enabled).
com.openexchange.requestwatcher.isEnabled: true

# Define the requestwatcher's frequency in milliseconds.
# Default value: 30000.
com.openexchange.requestwatcher.frequency: 30000

# Define the maximum allowed age of requests in milliseconds.
# Default value: 60000.
com.openexchange.requestwatcher.maxRequestAge: 60000

# Permission to stop & re-init system (works only for the ajp connector)
com.openexchange.requestwatcher.restartPermission: false
</pre>

==Multiple Proxies in front of the cluster==
[[File:GrizzlOXClusterMultipleProxySetup.png|left|935px|alt=The default cluster with multiple proxies setup.]]
<div style="clear: both"></div>

===X-FORWARDED-FOR Header===

Wikipedia[http://en.wikipedia.org/wiki/X-Forwarded-For] describes the X-Forwarded-For Header as:

The '''X-Forwarded-For''' ('''XFF''') HTTP header field is a ''de facto'' standard for identifying the originating IP address of a client connecting to a web server through an HTTP proxy or load balancer. This is an HTTP request header which was introduced by the [[Squid (software)|Squid]] caching proxy server's developers. An effort has been started at IETF for standardizing the '''Forwarded''' HTTP header.

In this context, the caching servers are most often those of large ISPs who either encourage or force their users to use proxy servers for access to the World Wide Web, something which is often done to reduce external bandwidth through caching. In some cases, these proxy servers are transparent proxies, and the user may be unaware that they are using them.

Without the use of XFF or another similar technique, any connection through the proxy would reveal only the originating IP address of the proxy server, effectively turning the proxy server into an anonymizing service, thus making the detection and prevention of abusive accesses significantly harder than if the originating IP address was available. The usefulness of XFF depends on the proxy server truthfully reporting the original host's IP address; for this reason, effective use of XFF requires knowledge of which proxies are trustworthy, for instance by looking them up in a whitelist of servers whose maintainers can be trusted.

====Format====
The general format of the field is:

: <tt>X-Forwarded-For: client, proxy1, proxy2</tt>

where the value is a comma+space separated list of IP addresses, the left-most being the original client, and each successive proxy that passed the request adding the IP address where it received the request from. In this example, the request passed through proxy1, proxy2, and then proxy3 (not shown in the header). proxy3 appears as remote address of the request.

The given information should be used with care since it is easy to forge an X-Forwarded-For field. The last IP address is always the IP address that connects to the last proxy, which means it is the most reliable source of information. X-Forwarded-For data can be used in a forward or reverse proxy scenario.

Just logging the X-Forwarded-For field is not always enough: The last proxy IP address in a chain is not contained within the X-Forwarded-For field, it is in the actual IP header. A web server should log BOTH the request's source IP address and the X-Forwarded-For field information for completeness.

===Getting the remote IP===
If you want the backends in the GrizzlOX-Cluster to use '''Client''''s(95.223.182.44) instead of '''Balancer''''s IP as remote address for e.g reporting the LogProperty '''com.openexchange.grizzly.remoteAddress''' for faulty requests in the Open-Xchange logs, you have to change these parameters from their default values seen in /opt/open-xchange/etc/server.properties to:

# Decides if we should consider X-Forward-Headers that reach the backend.
# Those can be spoofed by clients so we have to make sure to consider the headers only if the proxy/proxies reliably override those
# headers for incoming requests.
# Default value: false
com.openexchange.server.considerXForwards = '''true'''

# The name of the protocolHeader used to identify the originating IP address of
# a client connecting to a web server through an HTTP proxy or load balancer.
# This is needed for grizzly based setups that make use of http proxying.
# If the header isn't found the first proxy in front of grizzly will be used
# as originating IP/remote address.
# Default value: X-Forwarded-For
com.openexchange.server.forHeader='''X-Forwarded-For'''

# A list of know proxies in front of our httpserver/balancer as comma separated IPs e.g: 192.168.1.50, 192.168.1.51
com.openexchange.server.knownProxies = '''192.168.1.50, 192.168.1.51'''

After you have changed the the configuration you have to restart the backend server via

$ /etc/init.d/open-xchange restart

The remote IP is detected in the following way: All configured known proxies are removed from the list of IPs listed in the X-FORWARDED-FOR header, beginning frome the right side of the list. The rightmost leftover IP is then seen as our new remote address as it represents the first IP not known to us.

==Make Grizzly speak AJP instead of HTTP==
Grizzly normally acts as an HTTP server and demands that the balancing proxy in front of it communicates via HTTP. This behaviour can be changed to Grizzly accepting the Apache JServ Protocol by simply adjusting the Grizzly and Apache configurations and restarting both servers.

===Grizzly.properties===

Change this parameter from the value seen in [[#Grizzly configuration|Grizzly configuration]] to:

### Protocol
################################################################################

# Grizzly is able to communicate via AJP besides its default prototcol HTTP.
# Do you want to use AJP instead of HTTP?
# Default value: false
com.openexchange.http.grizzly.hasAJPEnabled='''true'''

===Apache configuration===

Change the HTTP related parameters from the values seen in [[#Apache configuration|Apache configuration]] to AJP. This involves the IfModule directive and the BalancerMember declarations.

To make Apach communicate via AJP instead of HTTP you have to replace the proxy_http with the proxy_ajp module.

<IfModule mod_proxy_'''ajp'''.c>
ProxyRequests Off
# When enabled, this option will pass the Host: line from the incoming request to the proxied host.
ProxyPreserveHost On
<Proxy balancer://oxcluster>
Order deny,allow
Allow from all
# multiple server setups need to have the hostname inserted instead localhost
BalancerMember '''ajp'''://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
# Enable and maybe add additional hosts running OX here
# BalancerMember '''ajp'''://oxhost2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
</Proxy>
# Microsoft recommends a minimum timeout value of 15 minutes for eas connections
<Proxy balancer://eas_oxcluster>
Order deny,allow
Allow from all
# multiple server setups need to have the hostname inserted instead localhost
BalancerMember '''ajp'''://localhost:8009 timeout=1800 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
# Enable and maybe add additional hosts running OX here
# BalancerMember '''ajp'''://oxhost2:8009 timeout=1800 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
</Proxy>

$ a2dismod proxy_http && a2enmod proxy_ajp

===Restart the servers===

$ /etc/init.d/open-xchange restart
$ /etc/init.d/apache2 restart

=Switching from open-xchange-grizzly to open-xchange-ajp=
It's possible to switch the '''open-xchange-grizzly''' based setup to a setup based on the alternative '''open-xchange-ajp''' if you don't depend on certian realtime features like websockets, comet based communication or the already mentioned WEBDAV MKCALENDAR command.

==1. Install the ajp backend==
Install the '''open-xchange-ajp''' package via your package manager. This will inform you about a conflict between the currently installed '''open-xchange-grizzly''' and the package you want to install. To solve the conflict you either have to manually remove '''open-xchange-grizzly''' before installing '''open-xchange-ajp''' or let the package manager handle this conflict automatically for you.

;Debian:
$ aptitude install open-xchange-ajp
;Suse:
$ zypper in open-xchange-ajp
;RedHat:
$ yum install open-xchange-ajp

==2. Adapt the module configuration of apache==
Adapt the installed apache modules to switch the proxy connector in use from http to ajp

$ a2dismod proxy_http && a2enmod proxy_ajp

==3. Adapt the apache configuration to use the new connector==
To make use of apaches new ajp connector for communication with '''open-xchange-ajp''' whe have to change it's configuration

{{Template:ApacheAppSuiteConf/sandbox|connector=ajp|connectorConf=/etc/apache2/conf.d/proxy_ajp.conf|apacheconf=/etc/apache2/sites-enabled/000-default|docroot=/var/www/|loadmodule=}}

==4.Restart services==
$ /etc/init.d/apache2 restart
$ /etc/init.d/open-xchange restart

[[Category: AppSuite]]

AppSuite:Grizzly

2013-04-17T14:42:27Z

Malasa: /* Apache configuration */

=Grizzly based backend=
Up to OX App Suite we were limited to AJP based communication between the HTTP server and the OX backend server. Starting with the release 7.0.1 of OX App Suite, we offer a second HTTP based connector for the communication between the HTTP server and the backend. This new connector is based on Oracle's '''[http://grizzly.java.net Project Grizzly]''' - a [http://en.wikipedia.org/wiki/New_I/O NIO] and Web framework.

=Packages=
Next, we'll show some information on the packages needed to install a Grizzly based backend, give you some in depth information about the package dependencies of '''open-xchange''' on '''open-xchange-ajp''' and '''open-xchange-grizzly''' and cover possible conflicts between those packages.

==HttpService as packaging dependency==
[[File:HttpServiceDependency.png|thumb|left|alt=The HttpService dependency.]]
The open-xchange package depends on a virtual package called '''open-xchange-httpservice'''. This service is provided by both, the old '''open-xchange-ajp''' and the new '''open-xchange-grizzly''' packages. Only one of these two packages can be installed at a time because they block each other.

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

{{InstallPlugin|pluginname=open-xchange-grizzly| toplevel=products | sopath=appsuite/stable/backend|version=App Suite}}

=Cluster setup=
[[File:GrizzlOXClusterSetup.png|left|alt=The default cluster setup.]]
This picture shows our default cluster setup. It consists of a proxying balancer (in our case Apache) and a cluster of multiple OX App Suite backends. The balancer receives HTTP and/or HTTPS requests. It then decides which requests should be handled by itself and which should be forwarded, so they can be handled by one of the OX App Suite backends. That's where the AJP or HTTP connector is used.
<div style="clear: both"></div>

==Configuration==
As requests pass the balancer first, we'll start with a look at how to configure the balancer before configuring the Grizzly-based OX App Suite backends.

===Apache configuration===
{{Template:ApacheOXModsDebian|connector=http}}

{{Template:ApacheAppSuiteConf/sandbox|connector=http|connectorConf=/etc/apache2/conf.d/proxy_http.conf|apacheconf=/etc/apache2/sites-enabled/000-default|docroot=/var/www/|loadmodule=|easProxyName=eas_oxcluster}}

====X-FORWARDED-PROTO Header====

[[Appsuite:Grizzly#Cluster_setup]] shows that HTTPS communication is terminated by the Apache balancer in front of the OX backends. To let the backends know about the protocol that is used to communicate with the Apache server we have to set a special header in the ssl virtual hosts configurations in Apache to forward this information. The de facto standard for this is the X-Forwarded-Proto header.

To add it to your Apache configuration you have to open the default ssl vhost configuration via:

$ vim /etc/apache2/sites-enabled/default-ssl

and add

RequestHeader set X-Forwarded-Proto "https"

to each of the virtual hosts used to communicate with the OX App Suite backends.

===Grizzly configuration===

====Available configuration files====

====/opt/open-xchange/etc/server.conf====
This extract of the server.properties shows the properties that can be applied to the grizzly and ajp backend.
<pre>
...
# DEFAULT ENCODING FOR INCOMING HTTP REQUESTS
# This value MUST be equal to web server's default encoding
DefaultEncoding=UTF-8
...
# The host for the connector's (ajp, http) network listener. Set to "*" if you
# want to listen on all available interfaces.
#Default value: 127.0.0.1, bind to localhost only.
com.openexchange.connector.networkListenerHost=*

# The default port for the connector's (ajp, http) network listener.
# Default value: 8009.
com.openexchange.connector.networkListenerPort=8009

# Specify the max. number of allowed request parameters for the connector (ajp, http)
# Default value: 30
com.openexchange.connector.maxRequestParameters: 30

# To enable proper load balancing and request routing from {client1, client2 ..
# .} --> balancer --> {backend1, backend2 ...} we have to append a backend route
# to the JSESSIONID cookies separated by a '.'. It's important that this backend
# route is unique for every single backend behind the load balancer.
# The string has to be a sequence of characters excluding semi-colon, comma and
# white space so the JSESSIONID cookie stays in accordance with the cookie
# specification after we append the backendroute to it.
# Default value: OX0
com.openexchange.server.backendRoute=OX1

# Decides if we should consider X-Forward-Headers that reach the backend.
# Those can be spoofed by clients so we have to make sure to consider the headers only if the proxy/proxies reliably override those
# headers for incoming requests.
# Default value: false
com.openexchange.server.considerXForwards = false

# The name of the protocolHeader used to identify the originating IP address of
# a client connecting to a web server through an HTTP proxy or load balancer.
# This is needed for grizzly based setups that make use of http proxying.
# If the header isn't found the first proxy in front of grizzly will be used
# as originating IP/remote address.
# Default value: X-Forwarded-For
com.openexchange.server.forHeader=X-Forwarded-For

# A list of know proxies in front of our httpserver/balancer as comma separated IPs e.g: 192.168.1.50, 192.168.1.51
com.openexchange.server.knownProxies =
...
</pre>

====/opt/open-xchange/etc/grizzly.conf====
Next we'll look at the parts of the grizzly.properties that configure only the grizzly backend but not the ajp backend.
<pre>
# Grizzly.properties
#
# This file configures the grizzly server contained in the package
# open-xchange-grizzly. In your OX setup grizzly is located behind the
# load-balancer and accepts incoming client requests. Communication with the
# load balancer is done via http, e.g via Apache's mod_proxy_http.

### Push technology
################################################################################

# Comet is an umbrella term used to describe a technique allowing web browser to
# receive almost real time updates from the server. The two most common
# approaches are long polling and streaming. Long polling differs from streaming
# in that each update from the server ultimately results in another follow up
# request from the client.
# Default value: true
com.openexchange.http.grizzly.hasCometEnabled=true

# Bi-directional, full-duplex communications channels over a single TCP
# connection.
# Default value: false
com.openexchange.http.grizzly.hasWebSocketsEnabled=true

### JMX
################################################################################

# Do you want to enable grizzly monitoring via JMX? Default value: true.
com.openexchange.http.grizzly.hasJMXEnabled=true

### Protocol
################################################################################

# Grizzly is able to communicate via AJP besides its default prototcol HTTP.
# Do you want to use AJP instead of HTTP?
# Default value: false
com.openexchange.http.grizzly.hasAJPEnabled=false
</pre>

====/opt/open-xchange/etc/requestwatcher.conf====
And finally the properties to configure the requestwatchers of the http and ajp backends
<pre>
# Requestwatcher.properties
#
# This file configures the requestwatchers contained in the packages
# open-xchange-grizzly and open-xchange-ajp. The requestwatcher keeps track of
# incoming requests and periodically checks the age of the currently processing
# requests. If a request exceeds the configured maximum age, infos about the
# request and its processing thread are logged either into the configured
# logfiles or syslog depending on your configuration.

# Enable/disable the requestwatcher.
# Default value: true (enabled).
com.openexchange.requestwatcher.isEnabled: true

# Define the requestwatcher's frequency in milliseconds.
# Default value: 30000.
com.openexchange.requestwatcher.frequency: 30000

# Define the maximum allowed age of requests in milliseconds.
# Default value: 60000.
com.openexchange.requestwatcher.maxRequestAge: 60000

# Permission to stop & re-init system (works only for the ajp connector)
com.openexchange.requestwatcher.restartPermission: false
</pre>

==Multiple Proxies in front of the cluster==
[[File:GrizzlOXClusterMultipleProxySetup.png|left|935px|alt=The default cluster with multiple proxies setup.]]
<div style="clear: both"></div>

===X-FORWARDED-FOR Header===

Wikipedia[http://en.wikipedia.org/wiki/X-Forwarded-For] describes the X-Forwarded-For Header as:

The '''X-Forwarded-For''' ('''XFF''') HTTP header field is a ''de facto'' standard for identifying the originating IP address of a client connecting to a web server through an HTTP proxy or load balancer. This is an HTTP request header which was introduced by the [[Squid (software)|Squid]] caching proxy server's developers. An effort has been started at IETF for standardizing the '''Forwarded''' HTTP header.

In this context, the caching servers are most often those of large ISPs who either encourage or force their users to use proxy servers for access to the World Wide Web, something which is often done to reduce external bandwidth through caching. In some cases, these proxy servers are transparent proxies, and the user may be unaware that they are using them.

Without the use of XFF or another similar technique, any connection through the proxy would reveal only the originating IP address of the proxy server, effectively turning the proxy server into an anonymizing service, thus making the detection and prevention of abusive accesses significantly harder than if the originating IP address was available. The usefulness of XFF depends on the proxy server truthfully reporting the original host's IP address; for this reason, effective use of XFF requires knowledge of which proxies are trustworthy, for instance by looking them up in a whitelist of servers whose maintainers can be trusted.

====Format====
The general format of the field is:

: <tt>X-Forwarded-For: client, proxy1, proxy2</tt>

where the value is a comma+space separated list of IP addresses, the left-most being the original client, and each successive proxy that passed the request adding the IP address where it received the request from. In this example, the request passed through proxy1, proxy2, and then proxy3 (not shown in the header). proxy3 appears as remote address of the request.

The given information should be used with care since it is easy to forge an X-Forwarded-For field. The last IP address is always the IP address that connects to the last proxy, which means it is the most reliable source of information. X-Forwarded-For data can be used in a forward or reverse proxy scenario.

Just logging the X-Forwarded-For field is not always enough: The last proxy IP address in a chain is not contained within the X-Forwarded-For field, it is in the actual IP header. A web server should log BOTH the request's source IP address and the X-Forwarded-For field information for completeness.

===Getting the remote IP===
If you want the backends in the GrizzlOX-Cluster to use '''Client''''s(95.223.182.44) instead of '''Balancer''''s IP as remote address for e.g reporting the LogProperty '''com.openexchange.grizzly.remoteAddress''' for faulty requests in the Open-Xchange logs, you have to change these parameters from their default values seen in /opt/open-xchange/etc/server.properties to:

# Decides if we should consider X-Forward-Headers that reach the backend.
# Those can be spoofed by clients so we have to make sure to consider the headers only if the proxy/proxies reliably override those
# headers for incoming requests.
# Default value: false
com.openexchange.server.considerXForwards = '''true'''

# The name of the protocolHeader used to identify the originating IP address of
# a client connecting to a web server through an HTTP proxy or load balancer.
# This is needed for grizzly based setups that make use of http proxying.
# If the header isn't found the first proxy in front of grizzly will be used
# as originating IP/remote address.
# Default value: X-Forwarded-For
com.openexchange.server.forHeader='''X-Forwarded-For'''

# A list of know proxies in front of our httpserver/balancer as comma separated IPs e.g: 192.168.1.50, 192.168.1.51
com.openexchange.server.knownProxies = '''192.168.1.50, 192.168.1.51'''

After you have changed the the configuration you have to restart the backend server via

$ /etc/init.d/open-xchange restart

The remote IP is detected in the following way: All configured known proxies are removed from the list of IPs listed in the X-FORWARDED-FOR header, beginning frome the right side of the list. The rightmost leftover IP is then seen as our new remote address as it represents the first IP not known to us.

==Make Grizzly speak AJP instead of HTTP==
Grizzly normally acts as an HTTP server and demands that the balancing proxy in front of it communicates via HTTP. This behaviour can be changed to Grizzly accepting the Apache JServ Protocol by simply adjusting the Grizzly and Apache configurations and restarting both servers.

===Grizzly.properties===

Change this parameter from the value seen in [[#Grizzly configuration|Grizzly configuration]] to:

### Protocol
################################################################################

# Grizzly is able to communicate via AJP besides its default prototcol HTTP.
# Do you want to use AJP instead of HTTP?
# Default value: false
com.openexchange.http.grizzly.hasAJPEnabled='''true'''

===Apache configuration===

Change the HTTP related parameters from the values seen in [[#Apache configuration|Apache configuration]] to AJP. This involves the IfModule directive and the BalancerMember declarations.

To make Apach communicate via AJP instead of HTTP you have to replace the proxy_http with the proxy_ajp module. If you used AJP before, you have to delete /etc/apache2/conf.d/proxy_ajp.conf.

<IfModule mod_proxy_'''ajp'''.c>
ProxyRequests Off
# When enabled, this option will pass the Host: line from the incoming request to the proxied host.
ProxyPreserveHost On
<Proxy balancer://oxcluster>
Order deny,allow
Allow from all
# multiple server setups need to have the hostname inserted instead localhost
BalancerMember '''ajp'''://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
# Enable and maybe add additional hosts running OX here
# BalancerMember '''ajp'''://oxhost2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
</Proxy>
# Microsoft recommends a minimum timeout value of 15 minutes for eas connections
<Proxy balancer://eas_oxcluster>
Order deny,allow
Allow from all
# multiple server setups need to have the hostname inserted instead localhost
BalancerMember '''ajp'''://localhost:8009 timeout=1800 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
# Enable and maybe add additional hosts running OX here
# BalancerMember '''ajp'''://oxhost2:8009 timeout=1800 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
</Proxy>

$ a2dismod proxy_http && a2enmod proxy_ajp

===Restart the servers===

$ /etc/init.d/open-xchange restart
$ /etc/init.d/apache2 restart

=Switching from open-xchange-grizzly to open-xchange-ajp=
It's possible to switch the '''open-xchange-grizzly''' based setup to a setup based on the alternative '''open-xchange-ajp''' if you don't depend on certian realtime features like websockets, comet based communication or the already mentioned WEBDAV MKCALENDAR command.

==1. Install the ajp backend==
Install the '''open-xchange-ajp''' package via your package manager. This will inform you about a conflict between the currently installed '''open-xchange-grizzly''' and the package you want to install. To solve the conflict you either have to manually remove '''open-xchange-grizzly''' before installing '''open-xchange-ajp''' or let the package manager handle this conflict automatically for you.

;Debian:
$ aptitude install open-xchange-ajp
;Suse:
$ zypper in open-xchange-ajp
;RedHat:
$ yum install open-xchange-ajp

==2. Adapt the module configuration of apache==
Adapt the installed apache modules to switch the proxy connector in use from http to ajp

$ a2dismod proxy_http && a2enmod proxy_ajp

==3. Adapt the apache configuration to use the new connector==
To make use of apaches new ajp connector for communication with '''open-xchange-ajp''' whe have to change it's configuration

{{Template:ApacheAppSuiteConf/sandbox|connector=ajp|connectorConf=/etc/apache2/conf.d/proxy_ajp.conf|apacheconf=/etc/apache2/sites-enabled/000-default|docroot=/var/www/|loadmodule=}}

==4.Restart services==
$ /etc/init.d/apache2 restart
$ /etc/init.d/open-xchange restart

[[Category: AppSuite]]

AppSuite:Upgrade from 6.22 for CentOS6

2013-03-25T14:15:56Z

Malasa: /* Update Open-Xchange Repositories */

= Update of Open-Xchange Server v6.22 to OX App Suite 7.0 on CentOS 6. =
This example describes updating an OX 6 Server installation to OX App Suite 7.

= Supported update path =
Updates from an OX6 installation to App Suite are only possible from 6.22 to 7.0. If you have an earlier version of Open-Xchange Server 6 installed, please update to the latest release of v6.22 before attempting an update to OX App Suite 7. See [[Open-Xchange_620_622_Update_Guide_for_CentOS6|Open-Xchange 6.20 to 6.22 Update Guide for CentOS 6]] for instructions regarding that update.

= Requirements =
* An Open-Xchange Server installation v6.22.0 or later. This update guide is valid for a system installed through our [[Open-Xchange_Installation_Guide_for_CentOS_6_622|Download and Installation Guide for CentOS 6]]
* If you have custom packages done by Open-Xchange, please discuss with your Open-Xchange contact when these packages are available for OX App Suite 7. Do not attempt the update earlier.
* Custom packages built for 6.22.1 or earlier might not work with OX App Suite 7.0.
* As for every update we strongly recommend that you make a backup of your system(s) before you proceed.

= Update Open-Xchange Repositories =
We start by adding the App Suite repos to our yum repos. Edit the file <code>/etc/yum.repos.d/ox.repo</code>:

[appsuite-frontend]
name=Appsuite-frontend
baseurl=http://software.open-xchange.com/products/appsuite/stable/appsuiteui/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[appsuite-backend]
name=Appsuite-backend
baseurl=http://software.open-xchange.com/products/appsuite/stable/backend/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[appsuite-usm]
name=Appsuite-usm
baseurl=http://software.open-xchange.com/products/appsuite/stable/usm/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[appsuite-eas]
name=Appsuite-eas
baseurl=http://LDBUSERNAME:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/mobilityconnector/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

Verify the repos:

# yum repolist

It may be necessary to

# yum clean all

to make your new repos appear.

= Updating repositories and update packages =

Download and update all installed packages:

$ yum update

This will install new config files of some packages as <code>.rpmnew</code> files. Check those files to identlfy files where you want to keep the existing version, put the new version in place, or merge them.

One configuration setting is to be made manually:

# vi /opt/open-xchange/etc/cluster.properties
com.openexchange.cluster.name=oxcluster

= Restart Open-Xchange =

To restart Open-Xchange Server after the update, run

$ /etc/init.d/open-xchange restart

You might want to check with

$ ps aux | grep open-xchange

that there is exactly one newly spawned process running Open-Xchange Server.

Now the backend has been upgraded to 7.0.x. The v6.22 frontend might still work with this new backend but is *NOT*' supported up to version 6.22.1. Upon the first connection after the backend update, you will ge tthe message <code>Error: updating database, try later</code>. The second try should succeed.

= Add the OX App Suite UI =

# yum install open-xchange-appsuite open-xchange-appsuite-backend open-xchange-appsuite-manifest

It them remains to adjust Apache's <code>ox.conf</code> as well as <code>proxy_ajp.conf</code>. Full sample versions of those files are given in the following.

# /etc/httpd/conf.d/ox.conf
<VirtualHost *:80>
ServerAdmin webmaster@localhost

DocumentRoot /var/www/html

<Directory /var/www/html>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Order allow,deny
allow from all
RedirectMatch ^/$ /appsuite/
</Directory>

<Directory /var/www/html/appsuite>
Options None +SymLinksIfOwnerMatch
AllowOverride Indexes FileInfo
</Directory>

ErrorLog ${APACHE_LOG_DIR}/error.log

# Possible values include: debug, info, notice, warn, error, crit,
# alert, emerg.
LogLevel warn

CustomLog ${APACHE_LOG_DIR}/access.log combined

# deflate
AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css text/xml application/xml text/x-js application/x-javascript

# pre-compressed files
AddType text/javascript .jsz
AddType text/css .cssz
AddType text/xml .xmlz
AddType text/plain .po

AddEncoding gzip .jsz .cssz .xmlz
SetEnvIf Request_URI "\.(jsz|cssz|xmlz)$" no-gzip

ExpiresActive On

<Location /ox6>
# Expires (via ExpiresByType to override global settings)
ExpiresByType image/gif "access plus 6 months"
ExpiresByType image/png "access plus 6 months"
ExpiresByType image/jpg "access plus 6 months"
ExpiresByType image/jpeg "access plus 6 months"
ExpiresByType text/css "access plus 6 months"
ExpiresByType text/html "access plus 6 months"
ExpiresByType text/xml "access plus 6 months"
ExpiresByType text/javascript "access plus 6 months"
ExpiresByType text/x-js "access plus 6 months"
ExpiresByType application/x-javascript "access plus 6 months"
ExpiresDefault "access plus 6 months"
Header append Cache-Control "private"
Header unset Last-Modified
Header unset Vary
# Strip version
RewriteEngine On
RewriteRule v=\w+/(.+) $1 [L]
# Turn off ETag
Header unset ETag
FileETag None
</Location>

<Location /ox6/ox.html>
ExpiresByType text/html "now"
ExpiresDefault "now"
Header unset Last-Modified
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
# Turn off ETag
Header unset ETag
FileETag None
</Location>

<Location /ox6/index.html>
ExpiresByType text/html "now"
ExpiresDefault "now"
Header unset Last-Modified
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
# Turn off ETag
Header unset ETag
FileETag None
</Location>
</VirtualHost>

# /etc/httpd/conf.d/proxy_ajp.conf
# Please note that the servlet path to the soap API has changed:
<Location /webservices>
# restrict access to the soap provisioning API
Order Deny,Allow
Deny from all
Allow from 127.0.0.1
# you might add more ip addresses / networks here
# Allow from 192.168 10 172.16
</Location>
# the old path is kept for compatibility reasons

<Location /servlet/axis2/services>
# restrict access to the soap provisioning API
Order Deny,Allow
Deny from all
Allow from 127.0.0.1
# you might add more ip addresses / networks here
# Allow from 192.168 10 172.16
</Location>
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so

<IfModule mod_proxy_ajp.c>
ProxyRequests Off
<Proxy balancer://oxcluster>
Order deny,allow
Allow from all
# multiple server setups need to have the hostname inserted instead localhost
BalancerMember ajp://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
# Enable and maybe add additional hosts running OX here
# BalancerMember ajp://oxhost2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
ProxySet stickysession=JSESSIONID
</Proxy>

# OX AppSuite frontend
<Proxy /appsuite/api>
ProxyPass balancer://oxcluster/ajax
</Proxy>

<Proxy /ajax>
ProxyPass balancer://oxcluster/ajax
</Proxy>
<Proxy /servlet>
ProxyPass balancer://oxcluster/servlet
</Proxy>
<Proxy /infostore>
ProxyPass balancer://oxcluster/infostore
</Proxy>
<Proxy /publications>
ProxyPass balancer://oxcluster/publications
</Proxy>
<Proxy /Microsoft-Server-ActiveSync>
ProxyPass balancer://oxcluster/Microsoft-Server-ActiveSync
</Proxy>
<Proxy /usm-json>
ProxyPass balancer://oxcluster/usm-json
</Proxy>
<Proxy /webservices>
ProxyPass balancer://oxcluster/webservices
</Proxy>
</IfModule>

After this, stop and start the httpd and open-xchange services. Then you should be able to use the App Suite UI.

= Remove the OX6 GUI =

This step is optional. You may just skip it and offer both GUIs, the OX6 GUI and the OX App Suite UI. This will only be supported after the 6.22.2 release!

If you want to uninstall the OX6 GUI, this step consists of removing the OX6 GUI packages and and adjusting Apache's configuration.

The packages to be removed can be identified by their version number in the output of <code>rpm -qa | grep open-x</code>. It will probably boil down to uninstall everything which starts with <code>open-xchange-gui</code>, as the names of the OX App Suite UI packages start with <code>open-xchange-appsuite</code>.

# yum remove open-xchange-gui*

Then adjust the <code>/etc/httpd/conf.d/ox.conf</code> file to remove obsolete stuff which was required for the OX6 GUI, but is not required by the OX App Suite. To do so, you may consult the [[AppSuite:Open-Xchange_Installation_Guide_for_CentOS_6|Installation Guide for OX App Suite]] to learn which sections of the file are required for an OX App Suite UI.

The file <code>/etc/httpd/conf.d/proxy_ajp.conf</code> will not require adjustments; the settings for OX App Suite are a superset of the settings of the OX6 GUI.

= Leftover configuration files and runtime data =

After the update you may see leftover configuration files and runtime data below <code>/opt/open-xchange/etc</code> It is safe to remove all files ending in .rpmsave or .rpmnew once you are confident that your configuration is working after the update.

Open-Xchange cPanel Installation

2013-03-08T05:47:15Z

Malasa: /* Preparation */

= Install Open-Xchange on WHM/cPanel =

== Requirements ==

OXtender for cPanel requires to have WHM 11.30 and newer installed running on RHEL 5 or CentOS 5.
It supports Open-Xchange versions 6.20 and newer. This guide, however, describes how to setup Open-Xchange
Server 6.22 and above.

== Mode of operation ==

It is recommended to run Open-Xchange on one or more separate machines. See the "''Hosting Edition deployment tutorials''" at [[Main_Page_HESE#quickinstall]].
The connection between cPanel and Open-Xchange is done via some cPanel/WHM hooks and UI plugins using SOAP as communication channel. That means that SOAP must be enabled on Open-Xchange.

[[Image:CPOX.png]]

Once the package open-xchange-cpanel is installed on the cPanel/WHM system, every cPanel user created within WHM will be created as an admin account and context in Open-Xchange.
In addition, there's a single program to create all existing cPanel Accounts in Open-Xchange.

== Availability ==

OXtender for cPanel is available with a valid Open-Xchange Hosting Edition license. To get pricing information that meets your individual requirements, please contact Open-Xchange at [http://www.open-xchange.com/en/solutions/cpanel/shop.html http://www.open-xchange.com/en/solutions/cpanel/shop.html]

== Known issues ==

* If you have existing cpanel plugins that use <tt>/script</tt> hooks (or <tt>/usr/local/cpanel/script</tt>), as well as /usr/local/cpanel/hooks, take care to make a backup of these files because they will be replaced by the <tt>open-xchange-cpanel</tt> rpm
* Users with the same email localpart from different domains in a single cPanel account and a single context do not work because user names as well as display names must be unique
* cPanel account names cannot be renamed when using the ox integration
* Error handling needs to be improved.
* Add-on domain handling needs to be improved
* Unable to indicate errors in open-xchange account creation when adding users in WHM/cPanel because the WHM/cPanel hooks have no possibility
* transferring cpanel users from one cpanel server to another is not supported

==Release Notes==

To download the Release Notes, follow this:
[http://software.open-xchange.com/OX6/OXtender-stable/cPanel/ Download]

== Install and prepare Open-Xchange ==

Follow one of the [http://oxpedia.org/index.php?title=Main_Page_HESE Open-Xchange installation guides] to install Open-Xchange and either just install the packages

'''On OX6 with backend versions < 7.0.1''':
open-xchange-meta-cpanel

'''On OX6 with backend versions >= 7.0.1''':
open-xchange-meta-cpanel open-xchange-meta-backend-ox6 open-xchange-meta-ui-ox6

'''On OX App Suite version >= 7.0.1 (older versions not supported):'''
open-xchange-meta-cpanel open-xchange-meta-backend-appsuite open-xchange-meta-ui-appsuite

or take care of '''the following exceptions''':

* Do not install the package <tt>open-xchange-mailfilter</tt>. cPanel does not support SIEVE at the moment.
* Install the package <tt>open-xchange-admin-soap-reseller</tt>
* Instead of <tt>open-xchange-authentication-database</tt>, install the package <tt>open-xchange-authentication-imap</tt>

'''Important:'''

* Do '''NOT''' create a context, just follow the installation guide up to the database registration
* Add the following argument to initconfigdb: <tt>--addon-sql "reseller.sql autocid.sql"</tt>

== Preparation ==

* run the command
$ /opt/open-xchange/sbin/initrestrictions -A oxadminmaster -P secret
once you've finished the open-xchange installation
* On OX6 take care to install the packages <tt>open-xchange-gui-wizard-plugin</tt> <tt>open-xchange-gui-wizard-plugin-gui</tt>. The wizard must be used to enforce the user to provide a real valid displayname.
* On OX6 edit file <tt>/opt/open-xchange/etc/settings/open-xchange-gui-wizard-plugin.properties</tt> and set
ui/wizard/firstrunmode=true
* edit file <tt>/opt/open-xchange/etc/imapauth.properties</tt> and set
USE_MULTIPLE=true

you also have to set IMAP_SERVER=<ip or hostname> to the cpanel server in the same file.
* edit file <tt>/opt/open-xchange/etc/mail.properties</tt> and set
com.openexchange.mail.adminMailLoginEnabled=true
* edit file <tt>/opt/open-xchange/etc/sessiond.properties</tt> and set
com.openexchange.sessiond.autologin=true
* edit file <tt>/opt/open-xchange/etc/AdminUser.properties</tt> and set
PRIMARY_MAIL_UNCHANGEABLE=false
* allow access from the cPanel server, edit <tt>/etc/httpd/conf.d/proxy_ajp.conf</tt>

<Location /servlet/axis2/services>
# restrict access to the soap provisioning API
Order Deny,Allow
Deny from all
Allow from 127.0.0.1
Allow from <your cpanel server ip>
# you might add more ip addresses / networks here
# Allow from 192.168 10 172.16
</Location>
[...]

== Install and prepare WHM/cPanel on CentOS5 ==

'''Note:''' Choose either CentOS5 or RHEL5. Nothing else is supported to integrate Open-Xchange with cPanel.

'''Important: If you have existing cpanel plugins that use <tt>/script</tt> hooks (or <tt>/usr/local/cpanel/script</tt>), as well as /usr/local/cpanel/hooks, take care to make a backup of these files because they will be replaced by the <tt>open-xchange-cpanel</tt> rpm'''

* Follow the installation guide http://docs.cpanel.net/twiki/bin/view/AllDocumentation/InstallationGuide/Quick-StartInstallationGuide
* run <tt>/scripts/upcp</tt>
* run <tt>/scripts/perlinstaller SOAP::Lite</tt>
'''NOTE: This can take very long and it might look like it is hanging at'''
We are about to install SOAP::Lite and for your convenience will provide
you with list of modules and prerequisites, so you'll be able to choose
only modules you need for your configuration.

XMLRPC::Lite, UDDI::Lite, and XML::Parser::Lite are included by default.
Installed transports can be used for both SOAP::Lite and XMLRPC::Lite.

Press <enter> to see the detailed list.

Just be patient and wait for it to finish.
* add the repository http://software.open-xchange.com/OX6/OXtender-stable/cPanel/RHEL5 to your yum configuration

'''VERY IMPORTANT:'''
Due to the inability of yum to correctly handle the x86_64 architecture, it is important to add the line

exclude=*.i386

to your yum repo configuration (see below).
Check http://wiki.centos.org/FAQ/General#head-357346ff0bf7c14b0849c3bcce39677aaca528e9 for details.

=== yum repo config on i386 ===

$ vi /etc/yum.repos.d/oxintegration.repo
[oxcpintegration]
name=Open-Xchange cPanel
baseurl=http://LDBACCOUNT:LDBPASSWORD@software.open-xchange.com/OX6/OXtender-stable/cPanel/RHEL5
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

=== yum repo config on x86_64 ===

$ vi /etc/yum.repos.d/oxintegration.repo
[oxcpintegration]
name=Open-Xchange cPanel
baseurl=http://LDBACCOUNT:LDBPASSWORD@software.open-xchange.com/OX6/OXtender-stable/cPanel/RHEL5
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m
#IMPORTANT!!!!!
exclude=*.i386

* install the package <tt>open-xchange-cpanel</tt>
$ yum install open-xchange-cpanel
* run the installer (-h for help):
$ /usr/local/cpanel/bin/oxcpanelinstall --oxurl http://ox.example.com --oxadmin-password oxadminmasterpassword

Now your Open-Xchange server is integrated with your cPanel installation.

To check the connection, run

$ /usr/local/cpanel/bin/oxcpanelenable -c

This program can also be used to enable all existing cPanel users in OX.
Run
$ /usr/local/cpanel/bin/oxcpanelenable -h
for more information.

== Create all cPanel Accounts in Open-Xchange ==

Like mentioned before, you must now create accounts in Open-Xchange for all your
existing cPanel accounts. This will not happen automatically. New accounts created in WHM, however, will automatically created in Open-Xchange.

To create an ox account per cPanel account you can either run

$ /usr/local/cpanel/bin/oxcpanelenable -e

or in the Open-Xchange WHM plugin click on every single cPanel Account and enable it.

== Debugging ==

* run the command
$ sudo /usr/local/cpanel/bin/oxcpanelenable -c
to check Open-Xchange connection before doing anything else. It must output
'''connection check successfull'''
* All errors happening during cPanel account creation and mail account creation are logged into the files <tt>/usr/local/cpanel/logs/open-xchange_log</tt> and <tt>/usr/local/cpanel/logs/error_log</tt>. If something does not work, check these logs first!
* <tt>/usr/local/cpanel/bin/oxcpanelinstall</tt> creates a debug output file with every execution, check its output, e.g.:
$ /usr/local/cpanel/bin/oxcpanelinstall --oxurl http://myox.example.com --oxadmin-password secret
running installer, please wait. Debugoutput is placed into file /tmp/cpoxinst3542.out

= WHM OX Plugin Usage =

To create Open-Xchange accounts, nothing else is required than to create cPanel accounts
as usual. Due to the design of the WHM plugin mechanism, however, it is not possible to
indicate any errors that might happen when creating the account in Open-Xchange fails.

You can easily check, however, if the Open-Xchange account creation failed when you open
the Open-Xchange plugin which can be found in the left menu in WHM almost on the bottom.

[[File:whm-ox-failed.png]]

Failed attempts to create an ox accounts can be seen there because in that case, the account
is not enabled.
In such a case you need to Terminate that account and create it again after you fixed the reason for the failed attempt. Check the logs for errors.

[[File:whm-ox-enable.png]]

In addition you will find all relevant error messages in <tt>/usr/local/cpanel/logs/open-xchange_log</tt> and <tt>/usr/local/cpanel/logs/error_log</tt>.

= cPanel OX Plugin Usage =

To create email accounts in Open-Xchange, nothing else is required than to create email accounts
in cPanel. Due to the design of the cPanel plugin mechanism, however, it is not possible to
indicate any errors that might happen when creating the account in Open-Xchange fails.

To check whether the email account creation fails, just open the Open-Xchange plugin and check
if the recently created email account(s) appear in the list. If not, contact your hosting provider or, if you are the owner of the machine, you will find all relevant error messages in <tt>/usr/local/cpanel/logs/open-xchange_log</tt> and <tt>/usr/local/cpanel/logs/error_log</tt>.

[[File:cpanel-account-list.png]]

= Running multiple WHM/cPanel instances with a single Open-Xchange instance (cluster) =

'''Starting with version 1.0.0 Rev2''' it is possible to run multiple WHM/cPanel instances with a single Open-Xchange (cluster) installation. This, however, requires some extra management which is not part of the <tt>open-xchange-cpanel</tt> package nor is there any other ready to use ui for that.

The setup of the cPanel server and OXtender is the same as described in the [[Open-Xchange_cPanel_Installation#Install_and_prepare_WHM.2FcPanel_on_CentOS5|installation section]].
The same applies to the installation of the Open-Xchange server. Once the Open-Xchange server is installed, however, you need to create a subadmin account per WHM/cPanel server. These subadmins must be able to create further subadmin accounts (one per cPanel account).

$ /opt/open-xchange/sbin/createadmin -A oxadminmaster -P secret -u cpanelmaster1 -d "cPanel Superadmin 1" -p secret -a Subadmin.CanCreateSubadmin=true

$ /opt/open-xchange/sbin/createadmin -A oxadminmaster -P secret -u cpanelmaster2 -d "cPanel Superadmin 2" -p secret -a Subadmin.CanCreateSubadmin=true

and so on.
You can also restrict the maximum number of subadmins a subadmin can create, see [[Reseller_Bundle#Open-Xchange_Reseller_package|Reseller Bundle]] description for further details.

$ /opt/open-xchange/sbin/listadmin -A oxadminmaster -P secret
Id Name Displayname Parent Restrictions
96 cpanelmaster1 cPanel Superadmin 1 0 Subadmin.CanCreateSubadmin=true
97 cpanelmaster2 cPanel Superadmin 2 0 Subadmin.CanCreateSubadmin=true

Now on each WHM/cPanel installation, instead of using the oxadminmaster account when running the <tt>oxcpanelinstaller</tt>, specify the corresponding cpanel supadmin, e.g.

$ /usr/local/cpanel/bin/oxcpanelinstall --oxurl http://ox.example.com --oxadmin-name cpanelmaster1 --oxadmin-password secret

and so on.

AppSuite:Upgrade from 6.22 for RHEL6

2013-02-27T14:36:31Z

Malasa:

= Update of Open-Xchange Server v6.22 to OX App Suite 7.0 on RHEL 6. =
This example describes updating an OX 6 Server installation to OX App Suite 7.

= Supported update path =
Updates from an OX6 installation to App Suite are only possible from 6.22 to 7.0. If you have an earlier version of Open-Xchange Server 6 installed, please update to the latest release of v6.22 before attempting an update to OX App Suite 7. See [[Open-Xchange_620_622_Update_Guide_for_RHEL6|Open-Xchange 6.20 to 6.22 Update Guide for RHEL 6]] for instructions regarding that update.

= Requirements =
* An Open-Xchange Server installation v6.22.0 or later. This update guide is valid for a system installed through our [[Open-Xchange_Installation_Guide_for_RHEL6_622|Download and Installation Guide for RHEL 6]]
* If you have custom packages done by Open-Xchange, please discuss with your Open-Xchange contact when these packages are available for OX App Suite 7. Do not attempt the update earlier.
* Custom packages built for 6.22.1 or earlier might not work with OX App Suite 7.0.
* As for every update we strongly recommend that you make a backup of your system(s) before you proceed.

= Update Open-Xchange Repositories =
We start by adding the App Suite repos to our yum repos. Edit the file <code>/etc/yum.repos.d/ox.repo</code>:

[appsuite-frontend]
name=Appsuite-frontend
baseurl=http://software.open-xchange.com/products/appsuite/stable/appsuiteui/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[appsuite-backend]
name=Appsuite-backend
baseurl=http://software.open-xchange.com/products/appsuite/stable/backend/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[appsuite-usm]
name=Appsuite-usm
baseurl=http://software.open-xchange.com/products/appsuite/stable/usm/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[appsuite-eas]
name=Appsuite-eas
baseurl=http://software.open-xchange.com/products/appsuite/stable/mobilityconnector/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

Verify the repos:

# yum repolist

It may be necessary to

# yum clean all

to make your new repos appear.

= Updating repositories and update packages =

Download and update all installed packages:

$ yum update

This will install new config files of some packages as <code>.rpmnew</code> files. Check those files to identlfy files where you want to keep the existing version, put the new version in place, or merge them.

One configuration setting is to be made manually:

# vi /opt/open-xchange/etc/cluster.properties
com.openexchange.cluster.name=oxcluster

= Restart Open-Xchange =

To restart Open-Xchange Server after the update, run

$ /etc/init.d/open-xchange restart

You might want to check with

$ ps aux | grep open-xchange

that there is exactly one newly spawned process running Open-Xchange Server.

Now the backend has been upgraded to 7.0.x. The v6.22 frontend might still work with this new backend but is *NOT*' supported up to version 6.22.1. The next version 6.22.2 is planned to be fully compatible with the 7.0.2 backend. Upon the first connection after the backend update, you will ge the message <code>Error: updating database, try later</code>. The second try should succeed.

= Add the App Suite UI =

# yum install open-xchange-appsuite open-xchange-appsuite-backend open-xchange-appsuite-manifest

It them remains to adjust Apache's <code>ox.conf</code> as well as <code>proxy_ajp.conf</code>. Full sample versions of those files are given in the following.

# /etc/httpd/conf.d/ox.conf
<VirtualHost *:80>
ServerAdmin webmaster@localhost

DocumentRoot /var/www/html

<Directory /var/www/html>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Order allow,deny
allow from all
RedirectMatch ^/$ /appsuite/
</Directory>

<Directory /var/www/html/appsuite>
Options None +SymLinksIfOwnerMatch
AllowOverride Indexes FileInfo
</Directory>

ErrorLog ${APACHE_LOG_DIR}/error.log

# Possible values include: debug, info, notice, warn, error, crit,
# alert, emerg.
LogLevel warn

CustomLog ${APACHE_LOG_DIR}/access.log combined

# deflate
AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css text/xml application/xml text/x-js application/x-javascript

# pre-compressed files
AddType text/javascript .jsz
AddType text/css .cssz
AddType text/xml .xmlz
AddType text/plain .po

AddEncoding gzip .jsz .cssz .xmlz
SetEnvIf Request_URI "\.(jsz|cssz|xmlz)$" no-gzip

ExpiresActive On

<Location /ox6>
# Expires (via ExpiresByType to override global settings)
ExpiresByType image/gif "access plus 6 months"
ExpiresByType image/png "access plus 6 months"
ExpiresByType image/jpg "access plus 6 months"
ExpiresByType image/jpeg "access plus 6 months"
ExpiresByType text/css "access plus 6 months"
ExpiresByType text/html "access plus 6 months"
ExpiresByType text/xml "access plus 6 months"
ExpiresByType text/javascript "access plus 6 months"
ExpiresByType text/x-js "access plus 6 months"
ExpiresByType application/x-javascript "access plus 6 months"
ExpiresDefault "access plus 6 months"
Header append Cache-Control "private"
Header unset Last-Modified
Header unset Vary
# Strip version
RewriteEngine On
RewriteRule v=\w+/(.+) $1 [L]
# Turn off ETag
Header unset ETag
FileETag None
</Location>

<Location /ox6/ox.html>
ExpiresByType text/html "now"
ExpiresDefault "now"
Header unset Last-Modified
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
# Turn off ETag
Header unset ETag
FileETag None
</Location>

<Location /ox6/index.html>
ExpiresByType text/html "now"
ExpiresDefault "now"
Header unset Last-Modified
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
# Turn off ETag
Header unset ETag
FileETag None
</Location>
</VirtualHost>

# /etc/httpd/conf.d/proxy_ajp.conf
# Please note that the servlet path to the soap API has changed:
<Location /webservices>
# restrict access to the soap provisioning API
Order Deny,Allow
Deny from all
Allow from 127.0.0.1
# you might add more ip addresses / networks here
# Allow from 192.168 10 172.16
</Location>
# the old path is kept for compatibility reasons

<Location /servlet/axis2/services>
# restrict access to the soap provisioning API
Order Deny,Allow
Deny from all
Allow from 127.0.0.1
# you might add more ip addresses / networks here
# Allow from 192.168 10 172.16
</Location>
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so

<IfModule mod_proxy_ajp.c>
ProxyRequests Off
<Proxy balancer://oxcluster>
Order deny,allow
Allow from all
# multiple server setups need to have the hostname inserted instead localhost
BalancerMember ajp://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
# Enable and maybe add additional hosts running OX here
# BalancerMember ajp://oxhost2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
ProxySet stickysession=JSESSIONID
</Proxy>

# OX AppSuite frontend
<Proxy /appsuite/api>
ProxyPass balancer://oxcluster/ajax
</Proxy>

<Proxy /ajax>
ProxyPass balancer://oxcluster/ajax
</Proxy>
<Proxy /servlet>
ProxyPass balancer://oxcluster/servlet
</Proxy>
<Proxy /infostore>
ProxyPass balancer://oxcluster/infostore
</Proxy>
<Proxy /publications>
ProxyPass balancer://oxcluster/publications
</Proxy>
<Proxy /Microsoft-Server-ActiveSync>
ProxyPass balancer://oxcluster/Microsoft-Server-ActiveSync
</Proxy>
<Proxy /usm-json>
ProxyPass balancer://oxcluster/usm-json
</Proxy>
<Proxy /webservices>
ProxyPass balancer://oxcluster/webservices
</Proxy>
</IfModule>

After this, stop and start the httpd and open-xchange services. Then you should be able to use the App Suite UI.

= Remove the OX6 GUI =

This step is optional. You may just skip it and offer both GUIs, the OX6 GUI and the App Suite UI. This will only be supported after the 6.22.2 release!

If you want to uninstall the OX6 GUI, this step consists of removing the OX6 GUI packages and and adjusting Apache's configuration.

The packages to be removed can be identified by their version number in the output of <code>rpm -qa | grep open-x</code>. It will probably boil down to uninstall everything which starts with <code>open-xchange-gui</code>, as the names of the App Suite UI packages start with <code>open-xchange-appsuite</code>.

# yum remove open-xchange-gui*

Then adjust the <code>/etc/httpd/conf.d/ox.conf</code> file to remove obsolete stuff which was required for the OX6 GUI, but is not required by the App Suite. To do so, you may consult the [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6|Installation Guide for OX App Suite]] to learn which sections of the file are required for an App Suite UI.

The file <code>/etc/httpd/conf.d/proxy_ajp.conf</code> will not require adjustments; the settings for App Suite are a superset of the settings of the OX6 GUI.

= Leftover configuration files and runtime data =

After the update you may see leftover configuration files and runtime data below <code>/opt/open-xchange/etc</code> It is safe to remove all files ending in .rpmsave or .rpmnew once you are confident that your configuration is working after the update.

AppSuite:Upgrade from 6.22 for CentOS6

2013-02-27T14:35:22Z

Malasa: wrong link for eas repo

= Update of Open-Xchange Server v6.22 to OX App Suite 7.0 on CentOS 6. =
This example describes updating an OX 6 Server installation to OX App Suite 7.

= Supported update path =
Updates from an OX6 installation to App Suite are only possible from 6.22 to 7.0. If you have an earlier version of Open-Xchange Server 6 installed, please update to the latest release of v6.22 before attempting an update to OX App Suite 7. See [[Open-Xchange_620_622_Update_Guide_for_CentOS6|Open-Xchange 6.20 to 6.22 Update Guide for CentOS 6]] for instructions regarding that update.

= Requirements =
* An Open-Xchange Server installation v6.22.0 or later. This update guide is valid for a system installed through our [[Open-Xchange_Installation_Guide_for_CentOS_6_622|Download and Installation Guide for CentOS 6]]
* If you have custom packages done by Open-Xchange, please discuss with your Open-Xchange contact when these packages are available for OX App Suite 7. Do not attempt the update earlier.
* Custom packages built for 6.22.1 or earlier might not work with OX App Suite 7.0.
* As for every update we strongly recommend that you make a backup of your system(s) before you proceed.

= Update Open-Xchange Repositories =
We start by adding the App Suite repos to our yum repos. Edit the file <code>/etc/yum.repos.d/ox.repo</code>:

[appsuite-frontend]
name=Appsuite-frontend
baseurl=http://software.open-xchange.com/products/appsuite/stable/appsuiteui/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[appsuite-backend]
name=Appsuite-backend
baseurl=http://software.open-xchange.com/products/appsuite/stable/backend/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[appsuite-usm]
name=Appsuite-usm
baseurl=http://software.open-xchange.com/products/appsuite/stable/usm/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[appsuite-eas]
name=Appsuite-eas
baseurl=http://software.open-xchange.com/products/appsuite/stable/mobilityconnector/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

Verify the repos:

# yum repolist

It may be necessary to

# yum clean all

to make your new repos appear.

= Updating repositories and update packages =

Download and update all installed packages:

$ yum update

This will install new config files of some packages as <code>.rpmnew</code> files. Check those files to identlfy files where you want to keep the existing version, put the new version in place, or merge them.

One configuration setting is to be made manually:

# vi /opt/open-xchange/etc/cluster.properties
com.openexchange.cluster.name=oxcluster

= Restart Open-Xchange =

To restart Open-Xchange Server after the update, run

$ /etc/init.d/open-xchange restart

You might want to check with

$ ps aux | grep open-xchange

that there is exactly one newly spawned process running Open-Xchange Server.

Now the backend has been upgraded to 7.0.x. The v6.22 frontend might still work with this new backend but is *NOT*' supported up to version 6.22.1. Upon the first connection after the backend update, you will ge tthe message <code>Error: updating database, try later</code>. The second try should succeed.

= Add the OX App Suite UI =

# yum install open-xchange-appsuite open-xchange-appsuite-backend open-xchange-appsuite-manifest

It them remains to adjust Apache's <code>ox.conf</code> as well as <code>proxy_ajp.conf</code>. Full sample versions of those files are given in the following.

# /etc/httpd/conf.d/ox.conf
<VirtualHost *:80>
ServerAdmin webmaster@localhost

DocumentRoot /var/www/html

<Directory /var/www/html>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Order allow,deny
allow from all
RedirectMatch ^/$ /appsuite/
</Directory>

<Directory /var/www/html/appsuite>
Options None +SymLinksIfOwnerMatch
AllowOverride Indexes FileInfo
</Directory>

ErrorLog ${APACHE_LOG_DIR}/error.log

# Possible values include: debug, info, notice, warn, error, crit,
# alert, emerg.
LogLevel warn

CustomLog ${APACHE_LOG_DIR}/access.log combined

# deflate
AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css text/xml application/xml text/x-js application/x-javascript

# pre-compressed files
AddType text/javascript .jsz
AddType text/css .cssz
AddType text/xml .xmlz
AddType text/plain .po

AddEncoding gzip .jsz .cssz .xmlz
SetEnvIf Request_URI "\.(jsz|cssz|xmlz)$" no-gzip

ExpiresActive On

<Location /ox6>
# Expires (via ExpiresByType to override global settings)
ExpiresByType image/gif "access plus 6 months"
ExpiresByType image/png "access plus 6 months"
ExpiresByType image/jpg "access plus 6 months"
ExpiresByType image/jpeg "access plus 6 months"
ExpiresByType text/css "access plus 6 months"
ExpiresByType text/html "access plus 6 months"
ExpiresByType text/xml "access plus 6 months"
ExpiresByType text/javascript "access plus 6 months"
ExpiresByType text/x-js "access plus 6 months"
ExpiresByType application/x-javascript "access plus 6 months"
ExpiresDefault "access plus 6 months"
Header append Cache-Control "private"
Header unset Last-Modified
Header unset Vary
# Strip version
RewriteEngine On
RewriteRule v=\w+/(.+) $1 [L]
# Turn off ETag
Header unset ETag
FileETag None
</Location>

<Location /ox6/ox.html>
ExpiresByType text/html "now"
ExpiresDefault "now"
Header unset Last-Modified
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
# Turn off ETag
Header unset ETag
FileETag None
</Location>

<Location /ox6/index.html>
ExpiresByType text/html "now"
ExpiresDefault "now"
Header unset Last-Modified
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
# Turn off ETag
Header unset ETag
FileETag None
</Location>
</VirtualHost>

# /etc/httpd/conf.d/proxy_ajp.conf
# Please note that the servlet path to the soap API has changed:
<Location /webservices>
# restrict access to the soap provisioning API
Order Deny,Allow
Deny from all
Allow from 127.0.0.1
# you might add more ip addresses / networks here
# Allow from 192.168 10 172.16
</Location>
# the old path is kept for compatibility reasons

<Location /servlet/axis2/services>
# restrict access to the soap provisioning API
Order Deny,Allow
Deny from all
Allow from 127.0.0.1
# you might add more ip addresses / networks here
# Allow from 192.168 10 172.16
</Location>
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so

<IfModule mod_proxy_ajp.c>
ProxyRequests Off
<Proxy balancer://oxcluster>
Order deny,allow
Allow from all
# multiple server setups need to have the hostname inserted instead localhost
BalancerMember ajp://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
# Enable and maybe add additional hosts running OX here
# BalancerMember ajp://oxhost2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
ProxySet stickysession=JSESSIONID
</Proxy>

# OX AppSuite frontend
<Proxy /appsuite/api>
ProxyPass balancer://oxcluster/ajax
</Proxy>

<Proxy /ajax>
ProxyPass balancer://oxcluster/ajax
</Proxy>
<Proxy /servlet>
ProxyPass balancer://oxcluster/servlet
</Proxy>
<Proxy /infostore>
ProxyPass balancer://oxcluster/infostore
</Proxy>
<Proxy /publications>
ProxyPass balancer://oxcluster/publications
</Proxy>
<Proxy /Microsoft-Server-ActiveSync>
ProxyPass balancer://oxcluster/Microsoft-Server-ActiveSync
</Proxy>
<Proxy /usm-json>
ProxyPass balancer://oxcluster/usm-json
</Proxy>
<Proxy /webservices>
ProxyPass balancer://oxcluster/webservices
</Proxy>
</IfModule>

After this, stop and start the httpd and open-xchange services. Then you should be able to use the App Suite UI.

= Remove the OX6 GUI =

This step is optional. You may just skip it and offer both GUIs, the OX6 GUI and the OX App Suite UI. This will only be supported after the 6.22.2 release!

If you want to uninstall the OX6 GUI, this step consists of removing the OX6 GUI packages and and adjusting Apache's configuration.

The packages to be removed can be identified by their version number in the output of <code>rpm -qa | grep open-x</code>. It will probably boil down to uninstall everything which starts with <code>open-xchange-gui</code>, as the names of the OX App Suite UI packages start with <code>open-xchange-appsuite</code>.

# yum remove open-xchange-gui*

Then adjust the <code>/etc/httpd/conf.d/ox.conf</code> file to remove obsolete stuff which was required for the OX6 GUI, but is not required by the OX App Suite. To do so, you may consult the [[AppSuite:Open-Xchange_Installation_Guide_for_CentOS_6|Installation Guide for OX App Suite]] to learn which sections of the file are required for an OX App Suite UI.

The file <code>/etc/httpd/conf.d/proxy_ajp.conf</code> will not require adjustments; the settings for OX App Suite are a superset of the settings of the OX6 GUI.

= Leftover configuration files and runtime data =

After the update you may see leftover configuration files and runtime data below <code>/opt/open-xchange/etc</code> It is safe to remove all files ending in .rpmsave or .rpmnew once you are confident that your configuration is working after the update.

AppSuite:DocumentConverterAPIInstall

2013-02-26T10:58:02Z

Malasa:

{{InstallPlugin|pluginname=open-xchange-documentconverter-api|toplevel=products|sopath=appsuite/stable/documentconverter-api|version=App Suite|reponame=documentconverter-api}}